From a4604752f5d260f05d9107dbed306a451faf7d3e Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 11:54:21 +0330 Subject: [PATCH 1/6] feat: prompt messages --- cookiecutter-django-app/cookiecutter.json | 20 ++++++++-- .../requirements/base.in | 2 +- .../tests/test_models.py | 2 +- .../{{cookiecutter.app_name}}/models.py | 2 +- cookiecutter-django-ida/cookiecutter.json | 13 +++++- cookiecutter-python-library/cookiecutter.json | 13 +++++- cookiecutter-xblock/cookiecutter.json | 17 ++++++-- python-template/cookiecutter.json | 40 +++++++++---------- 8 files changed, 77 insertions(+), 32 deletions(-) diff --git a/cookiecutter-django-app/cookiecutter.json b/cookiecutter-django-app/cookiecutter.json index aced33bf..c7d9ee17 100644 --- a/cookiecutter-django-app/cookiecutter.json +++ b/cookiecutter-django-app/cookiecutter.json @@ -9,9 +9,21 @@ "author_name": "Open edX Project", "author_email": "oscm@openedx.org", "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"], - "models": "Comma-separated list of models", + "models": "No Model", "config_class_name": "{{ cookiecutter.app_name|replace('_', ' ')|title|replace(' ', '') }}Config", - "_copy_without_render": [ - ".github/workflows/*.yml" - ] + "_copy_without_render": [".github/workflows/*.yml"], + "__prompts__": { + "github_org": "GitHub organization", + "repo_name": "Repository name", + "app_name": "Application name", + "project_name": "Project name", + "project_title": "Project title", + "project_short_description": "Short description of the project", + "version": "Version", + "author_name": "Author's name", + "author_email": "Author's email", + "open_source_license": "Package license", + "models": "Comma-separated list of models", + "config_class_name": "Configuration class name" + } } diff --git a/cookiecutter-django-app/{{cookiecutter.repo_name}}/requirements/base.in b/cookiecutter-django-app/{{cookiecutter.repo_name}}/requirements/base.in index 5eaa316e..95273a57 100644 --- a/cookiecutter-django-app/{{cookiecutter.repo_name}}/requirements/base.in +++ b/cookiecutter-django-app/{{cookiecutter.repo_name}}/requirements/base.in @@ -2,7 +2,7 @@ -c constraints.txt Django # Web application framework -{% if cookiecutter.models != "Comma-separated list of models" -%} +{% if cookiecutter.models != "No Model" -%} django-model-utils # Provides TimeStampedModel abstract base class {%- endif %} diff --git a/cookiecutter-django-app/{{cookiecutter.repo_name}}/tests/test_models.py b/cookiecutter-django-app/{{cookiecutter.repo_name}}/tests/test_models.py index 2e20beaf..f1f4f301 100644 --- a/cookiecutter-django-app/{{cookiecutter.repo_name}}/tests/test_models.py +++ b/cookiecutter-django-app/{{cookiecutter.repo_name}}/tests/test_models.py @@ -4,7 +4,7 @@ """ import pytest -{%- if cookiecutter.models != "Comma-separated list of models" -%} +{%- if cookiecutter.models != "No Model" -%} {%- for model in cookiecutter.models.replace(' ', '').split(',') %} diff --git a/cookiecutter-django-app/{{cookiecutter.repo_name}}/{{cookiecutter.app_name}}/models.py b/cookiecutter-django-app/{{cookiecutter.repo_name}}/{{cookiecutter.app_name}}/models.py index ac812e1d..aaefcebe 100644 --- a/cookiecutter-django-app/{{cookiecutter.repo_name}}/{{cookiecutter.app_name}}/models.py +++ b/cookiecutter-django-app/{{cookiecutter.repo_name}}/{{cookiecutter.app_name}}/models.py @@ -1,7 +1,7 @@ """ Database models for {{cookiecutter.app_name}}. """ -{%- if cookiecutter.models != "Comma-separated list of models" %} +{%- if cookiecutter.models != "No Model" %} # from django.db import models from model_utils.models import TimeStampedModel {%- for model in cookiecutter.models.replace(' ', '').split(',') %} diff --git a/cookiecutter-django-ida/cookiecutter.json b/cookiecutter-django-ida/cookiecutter.json index 71a8c4ab..b9aaac2f 100644 --- a/cookiecutter-django-ida/cookiecutter.json +++ b/cookiecutter-django-ida/cookiecutter.json @@ -7,5 +7,16 @@ "author_name": "Open edX Project", "author_email": "oscm@openedx.org", "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"], - "port": 8000 + "port": 8000, + "__prompts__": { + "github_org": "GitHub organization", + "repo_name": "Repository name", + "project_name": "Project name", + "project_short_description": "Short description of the project", + "version": "Version", + "author_name": "Author's name", + "author_email": "Author's email", + "open_source_license": "Package license", + "port": "Port" + } } diff --git a/cookiecutter-python-library/cookiecutter.json b/cookiecutter-python-library/cookiecutter.json index b1bcce23..e3804cf1 100644 --- a/cookiecutter-python-library/cookiecutter.json +++ b/cookiecutter-python-library/cookiecutter.json @@ -7,5 +7,16 @@ "version": "0.1.0", "author_name": "Open edX Project", "author_email": "oscm@openedx.org", - "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"] + "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"], + "__prompts__": { + "github_org": "GitHub organization", + "repo_name": "Repository name", + "library_name": "Library name", + "project_name": "Project name", + "project_short_description": "Short description of the project", + "version": "Version", + "author_name": "Author's name", + "author_email": "Author's email", + "open_source_license": "Package license" + } } diff --git a/cookiecutter-xblock/cookiecutter.json b/cookiecutter-xblock/cookiecutter.json index a948db98..8cf0227f 100644 --- a/cookiecutter-xblock/cookiecutter.json +++ b/cookiecutter-xblock/cookiecutter.json @@ -10,7 +10,18 @@ "author_name": "Open edX Project", "author_email": "oscm@openedx.org", "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"], - "_copy_without_render": [ - ".github/workflows/*.yml" - ] + "_copy_without_render": [".github/workflows/*.yml"], + "__prompts__": { + "github_org": "GitHub organization", + "repo_name": "Repository name", + "project_desc": "Project description", + "package_name": "Package name", + "i18n_namespace": "Internationalization namespace", + "tag_name": "Tag name", + "version": "Version", + "class_name": "Class name", + "author_name": "Author's name", + "author_email": "Author's email", + "open_source_license": "Package license" + } } diff --git a/python-template/cookiecutter.json b/python-template/cookiecutter.json index eebaa20a..3893f056 100644 --- a/python-template/cookiecutter.json +++ b/python-template/cookiecutter.json @@ -7,26 +7,26 @@ "version": "0.1.0", "author_name": "Open edX Project", "author_email": "oscm@openedx.org", - "open_source_license": [ - "AGPL 3.0", - "Apache Software License 2.0", - "Not open source" - ], + "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"], "setup_py_keyword_args": "None", - "setup_py_loading_pkg_data": [ - "no", - "yes" - ], - "requires_django": [ - "no", - "yes" - ], - "if_features_docs": [ - "no", - "yes" - ], + "setup_py_loading_pkg_data": ["no", "yes"], + "requires_django": ["no", "yes"], + "if_features_docs": ["no", "yes"], "placeholder_repo_name": "placeholder_repo_name", - "_copy_without_render": [ - ".github/workflows/*.yml" - ] + "_copy_without_render": [".github/workflows/*.yml"], + "__prompts__": { + "github_org": "GitHub organization", + "repo_name": "Repository name", + "sub_dir_name": "Sub-directory name", + "project_name": "Project name", + "project_short_description": "Short description of the project", + "version": "Version", + "author_name": "Author's name", + "author_email": "Author's email", + "open_source_license": "Package license", + "setup_py_keyword_args": "Keyword arguments for setup.py", + "setup_py_loading_pkg_data": "Load package data in setup.py (yes/no)", + "requires_django": "Requires Django (yes/no)", + "if_features_docs": "Add features documentation (yes/no)" + } } From ad68f36cf7941406967bead28ac7c17b969ccae0 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 12:01:11 +0330 Subject: [PATCH 2/6] chore: MAINTAINER is deprecated https://docs.docker.com/engine/deprecated/#maintainer-in-dockerfile --- cookiecutter-django-ida/{{cookiecutter.repo_name}}/Dockerfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/Dockerfile b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/Dockerfile index 3ff2b51c..dffdcbe4 100644 --- a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/Dockerfile +++ b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/Dockerfile @@ -1,6 +1,4 @@ FROM ubuntu:focal as app -MAINTAINER sre@edx.org - # Packages installed: From 1e14433165f4070412fde818a5b03e19208a6073 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 12:02:41 +0330 Subject: [PATCH 3/6] chore: comments added --- .../{{cookiecutter.repo_name}}/Dockerfile | 26 +++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/cookiecutter-xblock/{{cookiecutter.repo_name}}/Dockerfile b/cookiecutter-xblock/{{cookiecutter.repo_name}}/Dockerfile index 996388ef..449f0520 100644 --- a/cookiecutter-xblock/{{cookiecutter.repo_name}}/Dockerfile +++ b/cookiecutter-xblock/{{cookiecutter.repo_name}}/Dockerfile @@ -1,11 +1,27 @@ +# Use the official Open edX XBlock SDK image as the base image FROM openedx/xblock-sdk + +# Create the directory for the repository RUN mkdir -p /usr/local/src/{{cookiecutter.repo_name}} + +# Set the created directory as a Docker volume VOLUME ["/usr/local/src/{{cookiecutter.repo_name}}"] -RUN apt-get update && apt-get install -y gettext -RUN echo "pip install -r /usr/local/src/{{cookiecutter.repo_name}}/requirements.txt" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh -RUN echo "pip install -e /usr/local/src/{{cookiecutter.repo_name}}" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh -RUN echo "cd /usr/local/src/{{cookiecutter.repo_name}} && make compile_translations && cd /usr/local/src/xblock-sdk" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh -RUN echo "exec python /usr/local/src/xblock-sdk/manage.py \"\$@\"" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh + +# Update the package list and install gettext +RUN apt-get update && \ + apt-get install -y gettext + +# Prepare the install_and_run_xblock script by appending necessary commands +RUN echo "pip install -r /usr/local/src/{{cookiecutter.repo_name}}/requirements.txt" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh && \ + echo "pip install -e /usr/local/src/{{cookiecutter.repo_name}}" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh && \ + echo "cd /usr/local/src/{{cookiecutter.repo_name}} && make compile_translations && cd /usr/local/src/xblock-sdk" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh && \ + echo "exec python /usr/local/src/xblock-sdk/manage.py \"\$@\"" >> /usr/local/src/xblock-sdk/install_and_run_xblock.sh + +# Make the install_and_run_xblock script executable RUN chmod +x /usr/local/src/xblock-sdk/install_and_run_xblock.sh + +# Define the entrypoint to use the custom script ENTRYPOINT ["/bin/bash", "/usr/local/src/xblock-sdk/install_and_run_xblock.sh"] + +# Set the default command for the container CMD ["runserver", "0.0.0.0:8000"] From f0c3141690266dc1e9261e82e9f7b404eebd7e6e Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 12:06:01 +0330 Subject: [PATCH 4/6] chore: typos fixed --- cookiecutter-django-ida/hooks/post_gen_project.py | 2 +- docs/decisions/0003-layered-cookiecutter.rst | 6 +++--- docs/decisions/0004-which-cookiecutters-included.rst | 6 +++--- .../test_utils/__init__.py | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/cookiecutter-django-ida/hooks/post_gen_project.py b/cookiecutter-django-ida/hooks/post_gen_project.py index bd4e99c9..4280c615 100644 --- a/cookiecutter-django-ida/hooks/post_gen_project.py +++ b/cookiecutter-django-ida/hooks/post_gen_project.py @@ -23,6 +23,6 @@ } ) -# Removing unecessary files from python and django templates: +# Removing unnecessary files from python and django templates: os.remove("setup.py") os.remove("MANIFEST.in") diff --git a/docs/decisions/0003-layered-cookiecutter.rst b/docs/decisions/0003-layered-cookiecutter.rst index 7abf1d00..5d845aa0 100644 --- a/docs/decisions/0003-layered-cookiecutter.rst +++ b/docs/decisions/0003-layered-cookiecutter.rst @@ -15,7 +15,7 @@ Context Decision ******** -We will layer cookiecutters in order to share boilerpate code. This approach requires two categories of cookiecutters: +We will layer cookiecutters in order to share boilerplate code. This approach requires two categories of cookiecutters: * *template-only*: These cookiecutters contain files used as boilerplate across other cookiecutters, but do not result in a workable repository output. * *final-output*: These cookiecutters produce the final output, resulting in a working directory. @@ -62,8 +62,8 @@ Additionally, the decision to not allow partial file overwrites should help some Rejected Alternatives ********************* -No sharing of boilerpate code -============================= +No sharing of boilerplate code +============================== As noted in the `Context`_, we had a maintenance problem when not sharing boilerplate code. It remains to be seen if the potential drawbacks of this approach will outweigh the drawbacks of the original maintenance problem. diff --git a/docs/decisions/0004-which-cookiecutters-included.rst b/docs/decisions/0004-which-cookiecutters-included.rst index e7a8c6dc..37c92f80 100644 --- a/docs/decisions/0004-which-cookiecutters-included.rst +++ b/docs/decisions/0004-which-cookiecutters-included.rst @@ -24,7 +24,7 @@ Decision edx-cookiecutter should be the central point for public edx cookiecutters. Most Open edx public cookiecutters should be placed in this repository. -If there is a complelling case why a cookiecutter should be elsewhere, a link to it should be added the edx-cookiecutter/README.rst. +If there is a compelling case why a cookiecutter should be elsewhere, a link to it should be added the edx-cookiecutter/README.rst. Consequences @@ -35,7 +35,7 @@ All edx cookiecutters should be moved to this repository. Rejected Alternatives ********************* -Seperate Repos for frontend and backend cookiecutters +Separate Repos for frontend and backend cookiecutters ===================================================== -Rejected because of the very real possiblity of creating a cookiecutter that deals with both frontend and backend. +Rejected because of the very real possibility of creating a cookiecutter that deals with both frontend and backend. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/test_utils/__init__.py b/python-template/{{cookiecutter.placeholder_repo_name}}/test_utils/__init__.py index 7961e470..94666f1c 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/test_utils/__init__.py +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/test_utils/__init__.py @@ -1,7 +1,7 @@ """ Test utilities. -Since pytest discourages putting __init__.py into testdirectory +Since pytest discourages putting __init__.py into test directory (i.e. making tests a package) one cannot import from anywhere under tests folder. However, some utility classes/methods might be useful in multiple test modules (i.e. factoryboy factories, base test classes). From 240654e0892f7497effad1689fde7b402e368f01 Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 14:16:28 +0330 Subject: [PATCH 5/6] fix: update README files --- README.rst | 49 ++++++------ cookiecutter-django-app/README.rst | 76 ++++++++++--------- cookiecutter-django-ida/README.rst | 22 +++--- cookiecutter-python-library/README.rst | 29 ++++--- cookiecutter-xblock/README.rst | 15 ++-- lib/README.rst | 3 + .../README.rst | 12 +-- 7 files changed, 116 insertions(+), 90 deletions(-) diff --git a/README.rst b/README.rst index 19fac5a3..36fdc603 100644 --- a/README.rst +++ b/README.rst @@ -3,8 +3,6 @@ edx-cookiecutters This repository holds most of the Open edX public cookiecutters. - - Available cookiecutters *********************** @@ -18,7 +16,7 @@ cookiecutter-python-library for creating a Python package that follows Open edX standards. cookiecutter-xblock - for creating a XBlock repository as well as a Dockerfile for building and running your XBlock in the xblock-sdk workbench. + for creating an XBlock repository and a Dockerfile for building and running your XBlock in the xblock-sdk workbench. Using the cookiecutters @@ -26,7 +24,8 @@ Using the cookiecutters 1. One Time Setup ================= -.. code-block:: + +.. code-block:: bash # Clone the repository git clone git@github.com:openedx/edx-cookiecutters.git @@ -40,19 +39,20 @@ Using the cookiecutters These instructions assume you have cloned this repository and are currently in its head dir. You will need a virtualenv for running the cookiecutter. You can discard it once the cookiecutter has made your new repo. -Commands:: +.. code-block:: bash + + make requirements # from inside edx-cookiecutter repo - $ make requirements # from inside edx-cookiecutter repo # Replace with the base directory; your new directory will go inside. # Replace with one of the available cookiecutters documented above. - $ cookiecutter -o + cookiecutter -o 3. TODOs after running cookiecutter =================================== -- Modify project README -- Modify the "requirements upgrade workflow" at ".github/workflows/upgrade-python-requirements.yml" and add "team_reviewers" and the "email_address" of the team/person -- Modify project docs/decisions/0001-purpose-of-this-repo.rst ADR +- Modify project ``README.rst``. +- Modify the "requirements upgrade workflow" at ``.github/workflows/upgrade-python-requirements.yml`` and add ``team_reviewers`` and the ``email_address`` of the team/person. +- Modify project ``docs/decisions/0001-purpose-of-this-repo.rst`` ADR. - Commit and push to GitHub - On GitHub, update repo's "About" description @@ -62,12 +62,15 @@ Updating cookiecutters If you find anything that is outdated in the cookiecutters in this repository, please create a PR with updates. -.. Note:: Some of the cookiecutters in this repository use the layered cookiecutter approach. If you are modifying these, please see "Local Debugging of the layered cookiecutters" section below. +**Note:** Some of the cookiecutters in this repository use the layered cookiecutter approach. If you are modifying these, please see `Local Debugging of the layered cookiecutters`_ section below. + +.. _Local Debugging of the layered cookiecutters: #local-debugging-of-the-layered-cookiecutters Directions for contributing to this repository ============================================== -.. code-block:: + +.. code-block:: bash # Clone the repository git clone git@github.com:openedx/edx-cookiecutters.git @@ -123,16 +126,20 @@ Local Debugging of the layered cookiecutters -------------------------------------------- To ensure that the layered cookiecutters pull from your local code, -instead of GitHub, run cookiecutter like:: +instead of GitHub, run cookiecutter like: + +.. code-block:: bash - $ make cookiecutter- + make cookiecutter- -eg:: +eg: - $ make cookiecutter-django-app - $ make cookiecutter-django-ida - $ make cookiecutter-python-library - $ make cookiecutter-xblock +.. code-block:: bash + + make cookiecutter-django-app + make cookiecutter-django-ida + make cookiecutter-python-library + make cookiecutter-xblock Decisions @@ -152,9 +159,7 @@ License ======= The code in this repository is licensed under the Apache Software License 2.0 unless -otherwise noted. - -Please see ``LICENSE.txt`` for details. +otherwise noted. Please see `LICENSE.txt`_ for details. Reporting Security Issues diff --git a/cookiecutter-django-app/README.rst b/cookiecutter-django-app/README.rst index 5fdab368..72328c89 100644 --- a/cookiecutter-django-app/README.rst +++ b/cookiecutter-django-app/README.rst @@ -1,12 +1,12 @@ Cookiecutter Django Package ########################### -A cookiecutter_ template for creating reusable Django packages (installable apps) quickly. +A `cookiecutter`_ template for creating reusable Django packages (installable apps) quickly. If you're creating a standalone Django service, you should probably use `cookiecutter-django-ida`_ instead. -.. _Cookiecutter: https://github.com/audreyr/cookiecutter +.. _cookiecutter: https://cookiecutter.readthedocs.org/en/latest/index.html .. _cookiecutter-django-ida: https://github.com/openedx/edx-cookiecutters/tree/master/cookiecutter-django-ida @@ -29,43 +29,49 @@ it ``blogging_for_humans``) and set up your virtual environment with your favorite method. If you are an edX employee, request a new repo in the ``edx`` organization by submitting an ITSUPPORT ticket. Details are in the `How to request a new GitHub repo`_ wiki page. This ticket should also -request that Github Actions and Codecov be enabled for the new repository. +request that GitHub Actions and Codecov be enabled for the new repository. .. _How to request a new GitHub repo: https://openedx.atlassian.net/wiki/pages/viewpage.action?pageId=70385719 -**Note**: Your project will be created with README.rst file containing a pypi -badge, a Github Actions CI badge and a link to documentation on readthedocs.org. You +**Note**: Your project will be created with a ``README.rst`` file containing a Pypi +badge, a GitHub Actions CI badge, and a link to documentation on `readthedocs.org`_. You don't need to have these accounts set up before using Cookiecutter or -cookiecutter-django-app. - +``cookiecutter-django-app``. To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_. +.. _readthedocs.org: https://readthedocs.org .. _readme: https://github.com/openedx/edx-cookiecutters/blob/master/README.rst + After the new folder is created, you will need to: -Enter the project and take a look around:: +Enter the project and take a look around: - $ cd blogging_for_humans/ - $ ls +.. code-block:: bash + + cd blogging_for_humans/ + ls Generate a virtualenv and generate requirements files with dependencies -pinned to current versions (make sure you're using pip 9.0.2+ and Python 3.8):: +pinned to current versions (make sure you're using pip 9.0.2+ and Python 3.8): - $ mkvirtualenv Blogging-for-humans - $ make upgrade +.. code-block:: bash -Create a GitHub repo and push it there:: + mkvirtualenv Blogging-for-humans + make upgrade - $ git init - $ git add . - $ git commit -m "first awesome commit" - $ git remote add origin git@github.com:edx/blogging_for_humans.git - $ git push -u origin master +Create a GitHub repo and push it there: -Now take a look at your repo. Awesome, right? +.. code-block:: bash + git init + git add . + git commit -m "first awesome commit" + git remote add origin git@github.com:edx/blogging_for_humans.git + git push -u origin master + +Now take a look at your repo. Awesome, right? Address TODOs ============= @@ -73,12 +79,12 @@ Address TODOs Look around in the new repo for sections marked `TODO`. Here are a few known places where they may appear: -* `openedx.yaml`: Various OEP states need to be updated. See `OEP-2\: Repository Metadata`_ for more information. -* `{{cookiecutter.app_name}}/models.py`: If you specified any models to generate, the various docstrings need to be filled in, and PII annotations need to be added. See `OEP-30\: PII Markup and Auditing`_ for more information on PII annotations. -* `tests/test_models.py`: Fill in docstrings here too. +* ``openedx.yaml``: Various OEP states need to be updated. See `OEP-2 - Repository Metadata`_ for more information. +* ``{{cookiecutter.app_name}}/models.py``: If you specified any models to generate, the various docstrings need to be filled in, and PII annotations need to be added. See `OEP-30 - PII Markup and Auditing`_ for more information on PII annotations. +* ``tests/test_models.py``: Fill in docstrings here too. -.. _OEP-2\: Repository Metadata: https://open-edx-proposals.readthedocs.io/en/latest/oep-0002-bp-repo-metadata.html -.. _OEP-30\: PII Markup and Auditing: https://open-edx-proposals.readthedocs.io/en/latest/oep-0030-arch-pii-markup-and-auditing.html +.. _OEP-2 - Repository Metadata: https://docs.openedx.org/projects/openedx-proposals/en/latest/archived/oep-0002-bp-repo-metadata.html +.. _OEP-30 - PII Markup and Auditing: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0030-arch-pii-markup-and-auditing.html Finally, it's time to write the code!!! @@ -88,19 +94,19 @@ Running Tests Code has been written, but does it actually work? Let's find out! -:: +.. code-block:: bash workon (myenv) $ make requirements (myenv) $ make test-all -Github Checks +GitHub Checks ============= On your first PR, ensure Github Actions and Codecov checks are running. -If Github Actions are not running, you can look their state here https://github.com/openedx/edx-cookiecutters/actions +If Github Actions are not running, you can look at their state here https://github.com/openedx/edx-cookiecutters/actions If Codecov is not running, complete an ITSUPPORT ticket. @@ -113,7 +119,7 @@ register the application on PyPI. You should use PyPa's official Github action: https://github.com/marketplace/actions/pypi-publish to publish your package to PyPi in your Github workflow file you'd need to add the following -:: +.. code-block:: yaml - name: Publish the package to PyPi uses: pypa/gh-action-pypi-publish@master @@ -122,18 +128,20 @@ to publish your package to PyPi in your Github workflow file you'd need to add t password: ${{ secrets.PYPI_UPLOAD_TOKEN }} -``PY_UPLOAD_TOKEN`` is available organization wide edX repos via Github secrets. +``PY_UPLOAD_TOKEN`` is available organization-wide Open edX repos via Github secrets. Releasing on PyPI ================= Time to release a new version? Update the version number in the application -module's ``__init__.py`` file, update ``CHANGELOG.rst`` accordingly, and run:: +module's ``__init__.py`` file, update ``CHANGELOG.rst`` accordingly, and run: + +.. code-block:: bash - $ python setup.py tag + python setup.py tag -and create a Github release with new tag, your Github workflow should automatically run once a new release is -created and should publish the package to PyPi +and create a Github release with a new tag, your GitHub workflow should automatically run once a new release is +created and should publish the package to PyPi. Add to Django Packages ====================== diff --git a/cookiecutter-django-ida/README.rst b/cookiecutter-django-ida/README.rst index ee404f47..f59f422d 100644 --- a/cookiecutter-django-ida/README.rst +++ b/cookiecutter-django-ida/README.rst @@ -1,7 +1,7 @@ cookiecutter-django-ida ####################### -A cookiecutter_ template for edX Django projects. +A cookiecutter_ template for Open edX Django projects. .. _cookiecutter: https://cookiecutter.readthedocs.org/en/latest/index.html @@ -27,16 +27,14 @@ The necessary configuration is also in place to support: Usage ***** - To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_. .. _readme: https://github.com/openedx/edx-cookiecutters/blob/master/README.rst - After the new folder is created, you will need to: 1. ``cd `` -2. Create a python 3 virtual environment and activate it +2. Create a Python 3 virtual environment and activate it 3. ``make upgrade`` 4. ``make docker_build`` 5. ``docker-compose up`` @@ -69,7 +67,7 @@ The project includes a custom Django user model in ``core/models.py``. You must .. code-block:: bash - $ python manage.py makemigrations + python manage.py makemigrations Documentation ============= @@ -86,16 +84,16 @@ Contributions are welcome. Please read `How To Contribute `` -2. Create a python 3 virtual environment and activate it +2. Create a Python 3 virtual environment and activate it 3. ``make upgrade`` -**Note** This cookiecutter repo currently has some issues with repos that use a hyphen in their name. If this is the case, some pieces of the repo will need to be changed from ``new-repo-name`` to ``new_repo_name``, particularly the Python pieces. +**Note:** This cookiecutter repo currently has some issues with repos that use a hyphen in their name. +If this is the case, some pieces of the repo will need to be changed from ``new-repo-name`` to ``new_repo_name``, +particularly the Python pieces. Requirements ============ @@ -41,23 +43,26 @@ in order to perform this process on a regular cadence. Documentation ============= -Sphinx is set up for your project in the ``docs`` directory. All developer documentation should be added here (as opposed to a long README file). Doing this also has the added benefit of giving you a good starting point when the time comes to open source your project! +Sphinx is set up for your project in the ``docs`` directory. All developer documentation should be added here (as opposed to a long ``README`` file). Doing this also has the added benefit of giving you a good starting point when the time comes to open source your project! -Sphinx is themed with the Sphinx book theme `sphinx-book-theme `_ by default. If you wish to publish your documentation to Read the Docs you will need to make sure to take the steps `outlined here `_. +Sphinx is themed with the Sphinx book theme `sphinx-book-theme`_ by default. If you wish to publish your documentation to Read the Docs you will need to make sure to take the steps `outlined here`_. + +.. _sphinx-book-theme: https://github.com/executablebooks/sphinx-book-theme +.. _outlined here: https://openedx.atlassian.net/wiki/spaces/DOC/pages/3723755596/How+to+Add+a+Repo+to+ReadTheDocs Testing ======= -The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes:: +The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes: - * Create a new project using the template. - * Generate and install pinned requirements - * Run the project's migrations and validations. - * Extract and compile translations. - * Compile documentation. +* Create a new project using the template. +* Generate and install pinned requirements +* Run the project's migrations and validations. +* Extract and compile translations. +* Compile documentation. Run this validation using the command below. .. code-block:: bash - $ make test + make test diff --git a/cookiecutter-xblock/README.rst b/cookiecutter-xblock/README.rst index 6c23d498..209fcf56 100644 --- a/cookiecutter-xblock/README.rst +++ b/cookiecutter-xblock/README.rst @@ -1,6 +1,9 @@ +cookiecutter-xblock +################### + This is a cookiecutter template for new XBlocks. -It enables creation of the XBlock repository as well as a Dockerfile for building and running your XBlock in the xblock-sdk workbench. +It enables the creation of the XBlock repository as well as a Dockerfile for building and running your XBlock in the xblock-sdk workbench. To create a new XBlock using this cookiecutter template, follow the instructions found in edx-cookiecutter's `readme`_. @@ -9,12 +12,14 @@ To create a new XBlock using this cookiecutter template, follow the instructions Enter the short name and primary class name of your new XBlock when prompted. -To see your new XBlock in action, build and run a Docker image containing it:: +To see your new XBlock in action, build and run a Docker image containing it: + +.. code-block:: bash - $ make dev.run + make dev.run Your XBlock should now be available at http://localhost:8000 -As a next step, you can pick up the XBlock tutorial at the `Customizing Your XBlock`_ section. +As a next step, you can pick up the XBlock tutorial in the `Customizing Your XBlock`_ section. -.. _Customizing Your XBlock: https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/customize/index.html +.. _Customizing Your XBlock: https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/customize/index.html diff --git a/lib/README.rst b/lib/README.rst index 31dbc6ac..2a67b281 100644 --- a/lib/README.rst +++ b/lib/README.rst @@ -1,2 +1,5 @@ +edx_cookiecutter_lib +#################### + This is an installable library of code for use by the hooks in the cookiecutters. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst index 45451f00..bc7a6b8e 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst @@ -18,14 +18,16 @@ Purpose TODO: The ``README.rst`` file should start with a brief description of the repository and its purpose. It should be described in the context of other repositories under the ``openedx`` -organization. It should make clear where this fits in to the overall Open edX +organization. It should make clear where this fits into the overall Open edX codebase and should be oriented towards people who are new to the Open edX project. Getting Started with Development ******************************** -Please see the Open edX documentation for `guidance on Python development `_ in this repo. +Please see the Open edX documentation for `guidance on Python development`_ in this repo. + +.. _guidance on Python development: https://docs.openedx.org/en/latest/developers/how-tos/get-ready-for-python-dev.html Deploying ********* @@ -33,7 +35,7 @@ Deploying TODO: How can a new user go about deploying this component? Is it just a few commands? Is there a larger how-to that should be linked here? -PLACEHOLDER: For details on how to deploy this component, see the `deployment how-to`_ +PLACEHOLDER: For details on how to deploy this component, see the `deployment how-to`_. .. _deployment how-to: https://docs.openedx.org/projects/{{ cookiecutter.repo_name }}/how-tos/how-to-deploy-this-component.html @@ -86,8 +88,8 @@ Please read `How To Contribute `_ for d This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure -to have a discussion about your new feature idea with the maintainers prior to -beginning development to maximize the chances of your change being accepted. +to discuss your new feature idea with the maintainers before beginning development +to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea. From 7901995393d25e7c4bbc4723d08e0ddf5a3b692d Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Sat, 25 May 2024 14:16:43 +0330 Subject: [PATCH 6/6] chore: changelog entry added --- CHANGELOG.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index d5b26efa..255ac097 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -5,6 +5,13 @@ Change Log This file loosely adheres to the structure of https://keepachangelog.com/, but in reStructuredText instead of Markdown. +2024-05-25 +********** + +- Prompts added to all cookiecutters. +- "models" default value in django-app cookiecutter changed to "No Model" +- All README files updated. + 2024-04-30 **********