diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 9dd2c72c..4f33e605 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,45 +1,53 @@ Change Log -========== +########## .. This file loosely adheres to the structure of https://keepachangelog.com/, but in reStructuredText instead of Markdown. +2020-08-08 +********** + +Changed +======= + +- Re-ruled all the RST files to match the new docs guidance. + 2022-07-17 ----------- +********** Fixed -~~~~~ +===== - Update the cookiecutter for XBlocks to use the supported Docker image rather than a legacy, unsupported fork 2022-07-13 ----------- +********** Fixed -~~~~~ +===== - Standardised the Requirements file structure in all templates. 2022-07-12 ----------- +********** Fixed -~~~~~ +===== - Only run ``make check_keywords`` for IDAs, not all repos - Ensure django-app unit tests will work, and test this in cookiecutter's own CI Removed -~~~~~~~ +======= - Removed redundant New Relic agent injection in Makefile - Removed references to now unsupported Travis CI 2022-07-11 ----------- +********** Fixed -~~~~~ +===== - Fix or remove ``tags`` repo metadata in several templates; remove deprecated ``nick`` from openedx.yaml (see OEP-2) - Remove extraneous period after short description @@ -48,166 +56,165 @@ Fixed - Change Django documentation and setup.py references from 2.2 to 3.2 2022-07-05 ----------- +********** Fixed -~~~~~ +===== - Used newer, non-deprecated name for middleware to add custom attributes to requests from edx-drf-extensions ->>>>>>> master 2022-05-31 ----------- +********** Fixed -~~~~~ +===== - Used newer, non-deprecated name for metrics monitoring middleware from edx-django-utils Added -~~~~~ +===== - Added several more monitoring middlewares for IDAs 2022-04-08 ----------- +********** Fixed -~~~~~ +===== * Fixed an issue with default config for JWT auth for new IDAs. 2022-02-18 ----------- +********** Removed -~~~~~~~ +======= * Removed redundant New Relic agent injection in Dockerfile 2022-01-19 ----------- +********** Added -~~~~~ +===== * Added Support for Django40 Removed -~~~~~~~ +======= * Removed Support for Django22, 30, 31 2022-01-14 ----------- +********** Changed -~~~~~~~ +======= * Makefile created for django-ida now interpolates repo_name into dockerhub commands. 2021-10-27 ----------- +********** Added -~~~~~ +===== * Added GitHub Actions to the python-template cookiecutter so that all cookiecutters will make repos that check for conventional commits. 2021-10-01 ----------- +********** Added -~~~~~ +===== * Include system checks for Django apps in order to catch mismatches between model fields and Django admin. 2021-07-15 ----------- +********** Changed -~~~~~~~ +======= * Update cookiecutters so that sphinx warnings are treated as errors. 2021-06-01 ----------- +********** Fixed -~~~~~ +===== * Django-IDA Dockerfiles Added -~~~~~ +===== * Testing Dockerfiles into `make test` for Django-IDA Changed -~~~~~~~ +======= * Django-IDA Dockerfile now uses ubuntu focal 2021-04-05 ----------- +********** Fixed -~~~~~ +===== * Fixed django module documentation by using proper django settings. Added -~~~~~ +===== * Added "Edit on Github" button to new project's ReadTheDocs. 2020-11-25 ----------- +********** Changed -~~~~~~~ +======= * Add a typical development workflow to the generated README 2020-11-06 ----------- +********** Changed -~~~~~~~ +======= * All projects (including top level) use Python 3.8 and Django 2.2 2020-11-06 ----------- +********** Fixed -~~~~~ +===== * Fix Read the Docs config to point to the correct config file. ``requirements/docs.txt`` should be ``requirements/doc.txt`` 2020-11-05 ----------- +********** Fixed -~~~~~ +===== * Use virtualenv to prevent flakiness in ``make upgrade`` test 2020-10-30 ----------- +********** Fixed -~~~~~ +===== * Don't fill in a sample url pattern for Django apps, just suggest one in a comment 2020-08-26 ----------- +********** Changed -~~~~~~~ +======= * Configure devstack Django settings to have a good JWT_AUTH and a DATABASES that point at the mysql container. * Install mysqlclient @@ -219,18 +226,18 @@ Changed * Ignore emacs backup files. 2020-08-14 ----------- +********** Changed -~~~~~~~ +======= * Ignores /healthcheck endpoint in monitoring for IDAs 2020-08-07 ----------- +********** Fixed -~~~~~ +===== - Tweaks to the READMEs to separate using cookiecutters from updating cookiecutters; clarify the use of a virtualenv for running cookiecutters; @@ -238,57 +245,57 @@ Fixed improvements. 2020-08-03 ----------- +********** Fixed -~~~~~~~ +======= * Doc8 configs no longer have a max line length, which goes against our best practice to not use hard line breaks, as documented in `OEP-19: Developer Documentation Best Practices`_. .. _`OEP-19: Developer Documentation Best Practices`: https://open-edx-proposals.readthedocs.io/en/latest/oep-0019-bp-developer-documentation.html#best-practices 2020-07-28 ----------- +********** Fixed -~~~~~~~ +======= * Include ``JWT_AUTH_COOKIE`` in the base ``JWT_AUTH`` settings dict. 2020-07-15 ----------- +********** Changed -~~~~~~~ +======= * Changed how oauth2_urlpatterns is imported in the urls.py file 2020-07-09 ----------- +********** Fixed -~~~~~ +===== * Added csrf.urls to IDA cookiecutter so that CSRF works (some intervening changes not captured) 2020-06-02 ----------- +********** * Adding decision to make this repo the place for all edx cookiecutters. 2020-05-27 ----------- +********** * Used the layered approach for cookiecutter-xblock * setup.py is now only in python-template 2020-05-12 ----------- +********** Added -~~~~~ +===== * Added cookiecutter-argocd-application - a cookiecutter used by devops @@ -296,9 +303,9 @@ Added 2020-05-11 ----------- +********** Added -~~~~~ +===== * Added CHANGELOG diff --git a/README.rst b/README.rst index 8a1b2c96..548f8e67 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ -================= edx-cookiecutters -================= +################# This repository holds most of the Open edX public cookiecutters. @@ -26,7 +25,7 @@ Using the cookiecutters *********************** 1. One Time Setup ------------------ +================= .. code-block:: # Clone the repository @@ -37,7 +36,7 @@ Using the cookiecutters mkvirtualenv -p python3.8 edx-cookiecutters 2. Create a cookiecutter Repository --------------------------------- +================================ 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. @@ -49,7 +48,7 @@ Commands:: $ cookiecutter -o 3. TODOs after creating cookiecutter ------------------------------------ +=================================== - Modify project README - Modify project docs/decisions/0001-purpose-of-this-repo.rst ADR @@ -64,7 +63,7 @@ If you find anything that is outdated in the cookiecutters in this repository, p Directions for contributing to this repository ----------------------------------------------- +============================================== .. code-block:: # Clone the repository @@ -106,7 +105,7 @@ Directions for contributing to this repository Cookiecutters using layered approach ------------------------------------- +==================================== - cookiecutter-python-library - cookiecutter-django-app @@ -118,7 +117,7 @@ If you are updating above cookiecutters, please see `0003-layered-cookiecutter A <./docs/how_tos/modifying_layered_cookiecutter.rst>`_. Local Debugging of the layered cookiecutters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------- To ensure that the layered cookiecutters pull from your local code, instead of GitHub, run cookiecutter like:: @@ -142,12 +141,12 @@ Community ********* Contributing ------------- +============ Contributions are very welcome. Tests can be run with `tox`_. Please ensure the coverage at least stays the same before you submit a pull request. License -------- +======= The code in this repository is licensed under the Apache Software License 2.0 unless otherwise noted. @@ -156,12 +155,12 @@ Please see ``LICENSE.txt`` for details. Reporting Security Issues -------------------------- +========================= Please do not report security issues in public. Please email security@edx.org. Getting Help ------------- +============ If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. diff --git a/cookiecutter-django-app/README.rst b/cookiecutter-django-app/README.rst index 24500c17..cfe2978b 100644 --- a/cookiecutter-django-app/README.rst +++ b/cookiecutter-django-app/README.rst @@ -1,6 +1,5 @@ -=========================== Cookiecutter Django Package -=========================== +########################### |ci-badge| |license-badge| @@ -14,7 +13,7 @@ If you're creating a standalone Django service, you should probably use Features --------- +******** * Sane setup.py for easy PyPI registration/distribution * Github Actions for CI configuration @@ -25,7 +24,7 @@ Features * Basic model generation Usage ------ +***** First, create your empty repo on Github (in our example below, we would call it ``blogging_for_humans``) and set up your virtual environment with your @@ -71,7 +70,7 @@ Now take a look at your repo. Awesome, right? Address TODOs -~~~~~~~~~~~~~ +============= Look around in the new repo for sections marked `TODO`. Here are a few known places where they may appear: @@ -87,7 +86,7 @@ Finally, it's time to write the code!!! Running Tests -~~~~~~~~~~~~~ +============= Code has been written, but does it actually work? Let's find out! @@ -99,7 +98,7 @@ Code has been written, but does it actually work? Let's find out! Github Checks -~~~~~~~~~~~~~ +============= On your first PR, ensure Github Actions and Codecov checks are running. @@ -108,7 +107,7 @@ If Github Actions are not running, you can look their state here https://github. If Codecov is not running, complete an ITSUPPORT ticket. Register on PyPI -~~~~~~~~~~~~~~~~ +================ Once you have at least a prototype working and tests running, it's time to register the application on PyPI. @@ -128,7 +127,7 @@ to publish your package to PyPi in your Github workflow file you'd need to add t ``PY_UPLOAD_TOKEN`` is available organization wide 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:: @@ -139,13 +138,13 @@ and create a Github release with new tag, your Github workflow should automatica created and should publish the package to PyPi Add to Django Packages -~~~~~~~~~~~~~~~~~~~~~~ +====================== Once you have a release, and assuming you have an account there, just go to https://www.djangopackages.com/packages/add/ and add it there. License -------- +******* The code in this repository is licensed under the Apache License, Version 2.0, unless otherwise noted. @@ -154,7 +153,7 @@ Please see ``LICENSE.txt`` for details. How to Contribute ------------------ +***************** Contributions are very welcome. Please read `How To Contribute `_ for details. @@ -163,12 +162,12 @@ should be followed for all Open edX projects. Reporting Security Issues -------------------------- +************************* Please do not report security issues in public. Please email security@edx.org Getting Help ------------- +************ Have a question about this repository, or about the Open edX project in general? Please refer to this `list of resources`_ if you need any assistance. diff --git a/cookiecutter-django-app/{{cookiecutter.repo_name}}/docs/internationalization.rst b/cookiecutter-django-app/{{cookiecutter.repo_name}}/docs/internationalization.rst index 500861e9..9b25877c 100644 --- a/cookiecutter-django-app/{{cookiecutter.repo_name}}/docs/internationalization.rst +++ b/cookiecutter-django-app/{{cookiecutter.repo_name}}/docs/internationalization.rst @@ -1,7 +1,7 @@ .. _chapter-i18n: Internationalization -==================== +#################### All user-facing text content should be marked for translation. Even if this application is only run in English, our open source users may choose to use another language. Marking content for translation ensures our users have this choice. @@ -11,7 +11,7 @@ Follow the `internationalization coding guidelines`_ in the edX Developer's Guid .. _internationalization coding guidelines: https://edx.readthedocs.org/projects/edx-developer-guide/en/latest/internationalization/i18n.html Updating Translations -~~~~~~~~~~~~~~~~~~~~~ +********************* This project uses `Transifex`_ to translate content. After new features are developed the translation source files should be pushed to Transifex. Our translation community will translate the content, after which we can retrieve the translations. @@ -38,7 +38,7 @@ The `make` targets listed below can be used to push or pull translations. - Push source translation files to Transifex Fake Translations -~~~~~~~~~~~~~~~~~ +***************** As you develop features it may be helpful to know which strings have been marked for translation, and which are not. Use the `fake_translations` make target for this purpose. This target will extract all strings marked for translation, generate fake translations in the Esperanto (eo) language directory, and compile the translations. diff --git a/cookiecutter-django-ida/README.rst b/cookiecutter-django-ida/README.rst index fc58d775..9b699182 100644 --- a/cookiecutter-django-ida/README.rst +++ b/cookiecutter-django-ida/README.rst @@ -1,5 +1,5 @@ cookiecutter-django-ida -======================= +####################### A cookiecutter_ template for edX Django projects. @@ -25,7 +25,7 @@ The necessary configuration is also in place to support: .. _Sphinx: https://sphinx-doc.org/ Usage ------ +***** To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_. @@ -49,7 +49,7 @@ After the new folder is created, you will need to: **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 -~~~~~~~~~~~~ +============ Once you initialize your project, run ``make upgrade`` to generate ``.txt`` files in the ``requirements/`` directory, @@ -63,7 +63,7 @@ It is recommended to follow the instructions in in order to perform this process on a regular cadence. User Model Customization -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== The project includes a custom Django user model in ``core/models.py``. You must further customize this model as your IDA/service requires. You MUST generate migrations for this model before Django can start: @@ -72,19 +72,19 @@ The project includes a custom Django user model in ``core/models.py``. You must $ python manage.py makemigrations 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 themed with the common edX theme `edx-sphinx-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 `_. How To Contribute ------------------ +***************** Contributions are welcome. Please read `How To Contribute `_ for details. Even though it was written with ``edx-platform`` in mind, these guidelines should be followed for Open edX code in general. Testing -~~~~~~~ +======= The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes:: @@ -101,12 +101,12 @@ Run this validation using the command below. $ make test Reporting Security Issues -------------------------- +************************* Please do not report security issues in public. Please email security@edx.org. Getting Help ------------- +************ If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. diff --git a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/features.rst b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/features.rst index d9b53e39..073bbe99 100644 --- a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/features.rst +++ b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/features.rst @@ -1,7 +1,7 @@ .. _chapter-features: Feature Toggling -================ +################ All new features/functionality should be released behind a feature gate. This allows us to easily disable features in the event that an issue is discovered in production. This project uses the `Waffle `_ library for feature gating. @@ -24,7 +24,7 @@ For information on creating or updating features, refer to the `Waffle documentation `_. Permanent Feature Rollout -------------------------- +************************* Over time some features may become permanent and no longer need a feature gate around them. In such instances, the relevant code and tests should be updated to remove the feature gate. Once the code is released, the feature flag/switch should be deleted. diff --git a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/internationalization.rst b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/internationalization.rst index 500861e9..9b25877c 100644 --- a/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/internationalization.rst +++ b/cookiecutter-django-ida/{{cookiecutter.repo_name}}/docs/internationalization.rst @@ -1,7 +1,7 @@ .. _chapter-i18n: Internationalization -==================== +#################### All user-facing text content should be marked for translation. Even if this application is only run in English, our open source users may choose to use another language. Marking content for translation ensures our users have this choice. @@ -11,7 +11,7 @@ Follow the `internationalization coding guidelines`_ in the edX Developer's Guid .. _internationalization coding guidelines: https://edx.readthedocs.org/projects/edx-developer-guide/en/latest/internationalization/i18n.html Updating Translations -~~~~~~~~~~~~~~~~~~~~~ +********************* This project uses `Transifex`_ to translate content. After new features are developed the translation source files should be pushed to Transifex. Our translation community will translate the content, after which we can retrieve the translations. @@ -38,7 +38,7 @@ The `make` targets listed below can be used to push or pull translations. - Push source translation files to Transifex Fake Translations -~~~~~~~~~~~~~~~~~ +***************** As you develop features it may be helpful to know which strings have been marked for translation, and which are not. Use the `fake_translations` make target for this purpose. This target will extract all strings marked for translation, generate fake translations in the Esperanto (eo) language directory, and compile the translations. diff --git a/cookiecutter-python-library/README.rst b/cookiecutter-python-library/README.rst index 95b566e1..bf1e3ae5 100644 --- a/cookiecutter-python-library/README.rst +++ b/cookiecutter-python-library/README.rst @@ -1,5 +1,5 @@ cookiecutter-python-library -=========================== +########################### A cookiecutter_ template for edX python projects. For django related cookiecutters, see cookiecutters-django-{ida, app} located in edx-cookiecutters. @@ -10,7 +10,7 @@ A cookiecutter_ template for edX python projects. For django related cookiecutte This cookiecutter template is intended for new edX python libraries. Usage ------ +***** To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_. @@ -25,7 +25,7 @@ After the new folder is created, you will need to: **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 -~~~~~~~~~~~~ +============ Once you initialize your project, run ``make upgrade`` to generate ``.txt`` files in the ``requirements/`` directory, @@ -39,14 +39,14 @@ It is recommended to follow the instructions in 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 themed with the common edX theme `edx-sphinx-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 `_. Testing -~~~~~~~ +======= The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes:: @@ -63,12 +63,12 @@ Run this validation using the command below. $ make test Reporting Security Issues -------------------------- +************************* Please do not report security issues in public. Please email security@edx.org. Getting Help ------------- +************ If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. diff --git a/cookiecutter-xblock/{{cookiecutter.repo_name}}/README.rst b/cookiecutter-xblock/{{cookiecutter.repo_name}}/README.rst index 896dbf50..cc943e06 100644 --- a/cookiecutter-xblock/{{cookiecutter.repo_name}}/README.rst +++ b/cookiecutter-xblock/{{cookiecutter.repo_name}}/README.rst @@ -1,8 +1,8 @@ -README for {{cookiecutter.project_desc}} - +{{cookiecutter.project_desc}} +############################# Testing with Docker -==================== +******************** This XBlock comes with a Docker test environment ready to build, based on the xblock-sdk workbench. To build and run it:: @@ -11,7 +11,7 @@ This XBlock comes with a Docker test environment ready to build, based on the xb The XBlock SDK Workbench, including this XBlock, will be available on the list of XBlocks at http://localhost:8000 Translating -============= +************* Internationalization (i18n) is when a program is made aware of multiple languages. Localization (l10n) is adapting a program to local language and cultural habits. @@ -32,7 +32,7 @@ The general steps to provide multilingual messages for a Python program (or an X 4. Use ``gettext`` to translate strings. 1. Mark translatable strings ------------------------------ +============================= Mark translatable strings in python:: @@ -55,7 +55,7 @@ See `edx-developer-guide `_. @@ -75,10 +75,10 @@ The ``text.po`` file is created from the ``django-partial.po`` file created by this is why you will not see a ``django-partial.po`` file. 3. Create language specific translations ----------------------------------------------- +============================================== 3.1 Add translated strings -*************************** +--------------------------- After creating the raw message catalogs, all translations should be filled out by the translator. One or more translators must edit the entries created in the message catalog, i.e. the ``.po`` file(s). @@ -106,7 +106,7 @@ See `transifex documentation `_ django with transiflex. 3.2 Compile translations -************************* +------------------------- Once translations are in place, use the following Make target to compile the translation catalogs ``.po`` into ``.mo`` message files:: @@ -135,12 +135,12 @@ django with transiflex. $ make detect_changed_source_translations 4. Use ``gettext`` to translate strings ----------------------------------------- +======================================== Django will automatically use ``gettext`` and the compiled translations to translate strings. Troubleshooting -================ +**************** If there are any errors compiling ``.po`` files run the following command to validate your ``.po`` files:: diff --git a/docs/decisions/0001-combined-cookiecutter-repo.rst b/docs/decisions/0001-combined-cookiecutter-repo.rst index 69990f15..a8c1e235 100644 --- a/docs/decisions/0001-combined-cookiecutter-repo.rst +++ b/docs/decisions/0001-combined-cookiecutter-repo.rst @@ -1,13 +1,13 @@ 1. Combined Cookiecutter Repo -============================= +############################# Status ------- +****** Accepted Context -------- +******* There were multiple Python cookiecutter repositories with lots of overlap, and it was difficult to keep even one always up to date. @@ -17,17 +17,17 @@ Some examples: * cookiecutter-xblock Decision --------- +******** Move the edx's public python cookiecutters into edx-cookiecutters repository. This repository might one day be a place for all of edx's cookiecutters, but this decision is only relevant to our python cookiecutters. Consequences ------------- +************ Find all of edx's python cookiecutters, move them to this repositories, and archive the previous repositories. References ----------- +********** Archived cookiecutters: diff --git a/docs/decisions/0002-use-changelog.rst b/docs/decisions/0002-use-changelog.rst index 44b12e2b..b2be122b 100644 --- a/docs/decisions/0002-use-changelog.rst +++ b/docs/decisions/0002-use-changelog.rst @@ -1,18 +1,18 @@ 2. Use CHANGELOG.rst -==================== +#################### Status ------- +****** Accepted Context -------- +******* This is a new repository that isn't currently capturing changes. Additionally, we don't yet have an accepted OEP for Changelogs. Decision --------- +******** * Add a CHANGELOG.rst to tracking changes. * The changelog will be formatted according to `keepachangelog.com`_. @@ -20,13 +20,13 @@ Decision This enables all the benefits of changelogs, as documented in `keepachangelog.com`_. Consequences ------------- +************ * New PRs will need to have updated changelog entries. * A Pull Request template will be added to provide a reminder. References ----------- +********** * `keepachangelog.com`_ diff --git a/docs/decisions/0003-layered-cookiecutter.rst b/docs/decisions/0003-layered-cookiecutter.rst index c200a3a2..9859b791 100644 --- a/docs/decisions/0003-layered-cookiecutter.rst +++ b/docs/decisions/0003-layered-cookiecutter.rst @@ -1,19 +1,19 @@ 1. Layered Cookiecutters -======================== +######################## Status ------- +****** Accepted Context -------- +******* * We duplicate boilerplate files across our multiple cookiecutters. * Historically, it's been difficult keeping the same files across the multiple cookiecutters up-to-date. Decision --------- +******** We will layer cookiecutters in order to share boilerpate code. This approach requires two categories of cookiecutters: @@ -35,7 +35,7 @@ Here is an example of 3 final-output cookiecutters layered with one shared templ python-template Implementation Details -~~~~~~~~~~~~~~~~~~~~~~ +====================== Cookiecutter allows you to define ``pre_gen_project.py`` and ``post_gen_project.py`` files that run at the beginning and end of folder creation. @@ -46,10 +46,10 @@ The layers are copied in high to low order, so the top-most (the most specific) For example: for cookiecutter-django-ida (CDI), the CDI specific files/folders are created first. To avoid conflicts, ``post_gen_project.py`` uses the python-template to create files/folders in ``placeholder_repo_name_0``. After file creation, the files are moved to the correct location. Finally, CDI can delete any unnecessary files created by python-template. Consequences ------------- +************ Possible drawbacks -~~~~~~~~~~~~~~~~~~ +================== This approach of layers and shared files may make it difficult to know where to find a particular file since it could have been abstracted into any of the layers. @@ -60,20 +60,20 @@ To offset this, it is recommended that there be only one template-only layer. If Additionally, the decision to not allow partial file overwrites should help someone more quickly find the correct location for a change. Rejected Alternatives ---------------------- +********************* No sharing of boilerpate 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. Failed alternative layering implementation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================== Initially, we tried to layer from bottom up by doing most of the layering in pre_gen_project.py file. This failed because cookiecutter folder creation does allow overlaying a folder from a higher layer. If a folder ``{{ cookiecutter.name }}`` already exists from a previous layer, the cookiecutter would error out. This cookiecutter behavior resulted in us moving the layering to ``post_gen_project.py``, which results in a top-to-bottom approach to layering. References ----------- +********** Archived cookiecutters: diff --git a/docs/decisions/0004-which-cookiecutters-included.rst b/docs/decisions/0004-which-cookiecutters-included.rst index f17f193b..e7a8c6dc 100644 --- a/docs/decisions/0004-which-cookiecutters-included.rst +++ b/docs/decisions/0004-which-cookiecutters-included.rst @@ -1,14 +1,14 @@ 4. Which Cookiecutters in edx-cookiecutters? -============================================ +############################################ Status ------- +****** Accepted Context -------- +******* * Currently, the only cookiecutters in this repository are the Open edx public python cookiecutters. @@ -20,7 +20,7 @@ Context Decision --------- +******** edx-cookiecutter should be the central point for public edx cookiecutters. Most Open edx public cookiecutters should be placed in this repository. @@ -28,14 +28,14 @@ If there is a complelling case why a cookiecutter should be elsewhere, a link to Consequences ------------- +************ All edx cookiecutters should be moved to this repository. Rejected Alternatives ---------------------- +********************* Seperate Repos for frontend and backend cookiecutters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================================== Rejected because of the very real possiblity of creating a cookiecutter that deals with both frontend and backend. diff --git a/docs/decisions/0005-cookiecutter-default-branch.rst b/docs/decisions/0005-cookiecutter-default-branch.rst index 87aa7a91..fb0dd7c2 100644 --- a/docs/decisions/0005-cookiecutter-default-branch.rst +++ b/docs/decisions/0005-cookiecutter-default-branch.rst @@ -1,14 +1,14 @@ Cookiecutter default branch -=========================== +########################### Status ------- +****** Accepted Context -------- +******* Github now sets default branch of each new repository to main. And the software industry as a whole has been moving towards default branch name flexibility and away from naming the default branch "master". @@ -16,14 +16,14 @@ There are number of places in edx-cookiecutters where we make assumption about t Decision --------- +******** edx-cookiecutters tooling will assume new repositories created using the cookiecutters will have the default name of "main". As an additional nudge in this direction, it was decided not to provide an option that defaults to "main". If you need to use "master", you will need to manually rename references. Consequences ------------- +************ - Using "main" for a new repository for a library should be safe at this time, but using it for a new IDA may required additional changes to support it. diff --git a/docs/decisions/0005-store-one-off-scripts.rst b/docs/decisions/0005-store-one-off-scripts.rst index 419a9eb8..c9138286 100644 --- a/docs/decisions/0005-store-one-off-scripts.rst +++ b/docs/decisions/0005-store-one-off-scripts.rst @@ -1,37 +1,37 @@ 5. Where to put one-off update scripts? -============================================ +############################################ Status ------- +****** Accepted Context -------- +******* * Sometimes we want to make changes to a cookiecutter and have those changes applied retroactively to all repositories that were created with it. * We don't currently have a location to store scripts that can be used to apply these changes to individual repositories Decision --------- +******** Scripts used to update old cookiecutter code to reflect new changes will live in the scripts/ directory of this repository. Rejected Alternatives ---------------------- +********************* Use @edx/repo-tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================================== Rejected because repo-tools is more suited to creating CLI commands that may need to be run multiple times to gather information or make regular updates. Use @edx/jenkins-job-dsl -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================================== This was proposed as a containing repository since the cleanup-python-code job configured there can and will probably often be used to run these kinds of bash scripts against multiple repositories at once. It was rejected because diff --git a/docs/how_tos/modifying_layered_cookiecutter.rst b/docs/how_tos/modifying_layered_cookiecutter.rst index 49e7fbbf..eeb33043 100644 --- a/docs/how_tos/modifying_layered_cookiecutter.rst +++ b/docs/how_tos/modifying_layered_cookiecutter.rst @@ -1,11 +1,10 @@ -=================================== How to modify layered cookiecutters -=================================== +################################### First, read docs/decisions/0003-layered-cookiecutter.rst to understand why we are using layers and how they have been implemented. Adding a new file ------------------ +***************** * Search this repo for the file name to see if it already exists in the any template-only or final-output cookiecutters. * Determine if the file should be shared and added to a template-only cookiecutter layer. @@ -13,7 +12,7 @@ Adding a new file * Test all affected final-output cookiecutters. Modifying a file ----------------- +**************** * Search the repo for the file name to find all locations of the file. * Even if the file is not shared across cookiecutters, it may be similar enough to copies of a file where the modification might be needed in multiple locations. @@ -21,7 +20,7 @@ Modifying a file * Test all affected final-output cookiecutters. Adding a new template-only cookiecutter ---------------------------------------- +*************************************** Think hard before adding a new layer (template-only cookiecutter). They add lots of complexity and it is unlikely to be worth it. We are hoping for a single shared layer to simplify things. diff --git a/docs/how_tos/running_one_off_scripts.rst b/docs/how_tos/running_one_off_scripts.rst index b4b116aa..be1ed51c 100644 --- a/docs/how_tos/running_one_off_scripts.rst +++ b/docs/how_tos/running_one_off_scripts.rst @@ -1,11 +1,10 @@ -=================================== How to use the scripts in /scripts -=================================== +################################### First, read docs/decisions/0005-store-one-off-scripts.rst to understand why scripts of this nature are stored in this repository. To apply the changes from a script to your repository ------------------ +***************** 1. (for edx.org): Run the cleanup-python-code job in Jenkins with the contents of the script (minus the #!) as the input. This will automatically create a PR against the repositories you specify in the configuration. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/CHANGELOG.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/CHANGELOG.rst index b430e703..034666e9 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/CHANGELOG.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/CHANGELOG.rst @@ -1,25 +1,25 @@ Change Log ----------- +########## .. All enhancements and patches to {{ cookiecutter.sub_dir_name }} will be documented in this file. It adheres to the structure of https://keepachangelog.com/ , but in reStructuredText instead of Markdown (for ease of incorporation into Sphinx documentation and the PyPI description). - + This project adheres to Semantic Versioning (https://semver.org/). .. There should always be an "Unreleased" section for changes pending release. Unreleased -~~~~~~~~~~ +********** * [{{ cookiecutter.version }}] - {% now 'local' %} -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +************************************************ Added -_____ +===== * First release on PyPI. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst index 8e0107b9..f0320b76 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst @@ -1,5 +1,5 @@ {{cookiecutter.project_name}} -============================= +############################# |pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge| |license-badge| @@ -12,22 +12,22 @@ organization. It should make clear where this fits in to the overall edX codebase. Overview (please modify) ------------------------- +************************ The ``README.rst`` file should then provide an overview of the code in this repository, including the main components and useful entry points for starting to understand the code in more detail. Documentation -------------- +************* (TODO: `Set up documentation `_) Development Workflow --------------------- +******************** One Time Setup -~~~~~~~~~~~~~~ +============== .. code-block:: # Clone the repository @@ -39,7 +39,7 @@ One Time Setup Every time you develop something in this repo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================= .. code-block:: # Activate the virtualenv @@ -74,7 +74,7 @@ Every time you develop something in this repo # Open a PR and ask for review. License -------- +******* The code in this repository is licensed under the {{ cookiecutter.open_source_license }} unless otherwise noted. @@ -82,7 +82,7 @@ otherwise noted. Please see `LICENSE.txt `_ for details. How To Contribute ------------------ +***************** Contributions are very welcome. Please read `How To Contribute `_ for details. @@ -96,12 +96,12 @@ The issue report template should be automatically applied if you are creating an can find it at `ISSUE_TEMPLATE.md <.github/ISSUE_TEMPLATE.md>`_. Reporting Security Issues -------------------------- +************************* Please do not report security issues in public. Please email security@edx.org. Getting Help ------------- +************ If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions.rst index e93f2360..a21903c8 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions.rst @@ -1,5 +1,5 @@ Decisions -========= +######### The following `ADRs` are a record of all decisions made as a part of developing this library. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions/0001-purpose-of-this-repo.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions/0001-purpose-of-this-repo.rst index 65ceb953..d67cb897 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions/0001-purpose-of-this-repo.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/decisions/0001-purpose-of-this-repo.rst @@ -1,8 +1,8 @@ 0001 Purpose of This Repo -========================= +######################### Status ------- +****** **Draft** @@ -17,14 +17,14 @@ Status If an ADR has Draft status and the PR is under review, you can either use the intended final status (e.g. Provisional, Accepted, etc.), or you can clarify both the current and intended status using something like the following: "Draft (=> Provisional)". Either of these options is especially useful if the merged status is not intended to be Accepted. Context -------- +******* TODO: Add context of what led to the creation of this repo. .. This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. Decision --------- +******** We will create a repository... @@ -33,21 +33,21 @@ TODO: Clearly state how the context above led to the creation of this repo. .. This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" Consequences ------------- +************ TODO: Add what other things will change as a result of creating this repo. .. This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. Rejected Alternatives ---------------------- +********************* TODO: If applicable, list viable alternatives to creating this new repo and give reasons for why they were rejected. If not applicable, remove section. .. This section lists alternate options considered, described briefly, with pros and cons. References ----------- +********** TODO: If applicable, add any references. If not applicable, remove section. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/getting_started.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/getting_started.rst index f203bbb5..cec54185 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/getting_started.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/getting_started.rst @@ -1,5 +1,5 @@ Getting Started -=============== +############### If you have not already done so, create/activate a `virtualenv`_. Unless otherwise stated, assume all terminal code below is executed within the virtualenv. @@ -8,7 +8,7 @@ below is executed within the virtualenv. Install dependencies --------------------- +******************** Dependencies can be installed via the command below. .. code-block:: bash diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/index.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/index.rst index c9a1038c..284a4124 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/index.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/index.rst @@ -26,7 +26,7 @@ Contents: Indices and tables -================== +################## * :ref:`genindex` * :ref:`modindex` diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/internationalization.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/internationalization.rst index 500861e9..9b25877c 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/internationalization.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/internationalization.rst @@ -1,7 +1,7 @@ .. _chapter-i18n: Internationalization -==================== +#################### All user-facing text content should be marked for translation. Even if this application is only run in English, our open source users may choose to use another language. Marking content for translation ensures our users have this choice. @@ -11,7 +11,7 @@ Follow the `internationalization coding guidelines`_ in the edX Developer's Guid .. _internationalization coding guidelines: https://edx.readthedocs.org/projects/edx-developer-guide/en/latest/internationalization/i18n.html Updating Translations -~~~~~~~~~~~~~~~~~~~~~ +********************* This project uses `Transifex`_ to translate content. After new features are developed the translation source files should be pushed to Transifex. Our translation community will translate the content, after which we can retrieve the translations. @@ -38,7 +38,7 @@ The `make` targets listed below can be used to push or pull translations. - Push source translation files to Transifex Fake Translations -~~~~~~~~~~~~~~~~~ +***************** As you develop features it may be helpful to know which strings have been marked for translation, and which are not. Use the `fake_translations` make target for this purpose. This target will extract all strings marked for translation, generate fake translations in the Esperanto (eo) language directory, and compile the translations. diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/testing.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/testing.rst index 4e82436f..d639dbea 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/docs/testing.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/docs/testing.rst @@ -1,7 +1,7 @@ .. _chapter-testing: Testing -======= +####### {{ cookiecutter.project_name }} has an assortment of test cases and code quality checks to catch potential problems during development. To run them all in the