From 9eaee096484e6cb74aa178071982a7a78cf129d5 Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Tue, 9 Aug 2022 14:39:07 -0400 Subject: [PATCH 1/3] docs: Update template README.rst to match OEP-55 Guidelines --- CHANGELOG.rst | 3 + .../README.rst | 129 ++++++++++++------ 2 files changed, 90 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 4f33e605..f710d607 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -12,6 +12,9 @@ Changed ======= - Re-ruled all the RST files to match the new docs guidance. +- Update template README.rst to match `OEP-55 Guidelines`_ + +.. _OEP-55 Guidelines: https://open-edx-proposals.readthedocs.io/en/latest/processes/oep-0055/decisions/0003-readme-specification.html 2022-07-17 ********** diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst index f0320b76..3ab8d591 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst @@ -2,32 +2,27 @@ ############################# |pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge| -|license-badge| +|license-badge| |status-badge| -{{ cookiecutter.project_short_description}} - -The ``README.rst`` file should start with a brief description of the repository, -which sets it in the context of other repositories under the ``edx`` -organization. It should make clear where this fits in to the overall edX -codebase. +Purpose +******* -Overview (please modify) -************************ +{{ cookiecutter.project_short_description}} -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. +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 +codebase and should be oriented towards people who are new to the Open edX +project. -Documentation -************* +Getting Started +*************** -(TODO: `Set up documentation `_) - -Development Workflow -******************** +Developing +========== One Time Setup -============== +-------------- .. code-block:: # Clone the repository @@ -39,7 +34,7 @@ One Time Setup Every time you develop something in this repo -============================================= +--------------------------------------------- .. code-block:: # Activate the virtualenv @@ -59,7 +54,7 @@ Every time you develop something in this repo git checkout -b / # Using your favorite editor, edit the code to make your change. - vim … + vim ... # Run your new tests pytest ./path/to/new/tests @@ -68,11 +63,53 @@ Every time you develop something in this repo make validate # Commit all your changes - git commit … + git commit ... git push # Open a PR and ask for review. +Deploying +========= + +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? + +For details on how to deploy this component, checkout the `deployment how-to`_ + +.. _deployment how-to: https://docs.openedx.org/projects/this-project/how-tos/how-to-deploy-this-component.html + +Getting Help +************ + +Documentation +============= + +Start by going through `the documentation`_. If you need more help see below. + +.. _the documentation: https://docs.openedx.org/projects/{{cookiecutter.repo_name}} + +(TODO: `Set up documentation `_) + +More Help +========= +If you're having trouble, we have discussion forums at +https://discuss.openedx.org where you can connect with others in the +community. + +Our real-time conversations are on Slack. You can request a `Slack +invitation`_, then join our `community Slack workspace`_. + +For anything non-trivial, the best path is to open an issue in this +repository with as many details about the issue you are facing as you +can provide. + +https://github.com/openedx/DoneXBlock/issues + +For more information about these options, see the `Getting Help`_ page. + +.. _Slack invitation: https://openedx.org/slack +.. _community Slack workspace: https://openedx.slack.com/ +.. _Getting Help: https://openedx.org/getting-help + License ******* @@ -81,37 +118,39 @@ otherwise noted. Please see `LICENSE.txt `_ for details. -How To Contribute -***************** +Contributing +************ Contributions are very welcome. -Please read `How To Contribute `_ for details. -Even though they were written with ``edx-platform`` in mind, the guidelines -should be followed for all Open edX projects. +Please read `How To Contribute `_ for details. -The pull request description template should be automatically applied if you are creating a pull request from GitHub. Otherwise you -can find it at `PULL_REQUEST_TEMPLATE.md <.github/PULL_REQUEST_TEMPLATE.md>`_. +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. +You can start a conversation by creating a new issue on this repo summarizing +your idea. -The issue report template should be automatically applied if you are creating an issue on GitHub as well. Otherwise you -can find it at `ISSUE_TEMPLATE.md <.github/ISSUE_TEMPLATE.md>`_. +The Open edX Code of Conduct +**************************** -Reporting Security Issues -************************* +All community members are expected to follow the `Open edX Code of Conduct`_. -Please do not report security issues in public. Please email security@edx.org. +.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/ -Getting Help -************ +People +****** -If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. +The assigned maintainers for this component and other project details may be +found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml`` +file in this repo. -Our real-time conversations are on Slack. You can request a `Slack invitation`_, then join our `community Slack workspace`_. +.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/{{ cookiecutter.repo_name }} -For more information about these options, see the `Getting Help`_ page. +Reporting Security Issues +************************* -.. _Slack invitation: https://openedx.org/slack -.. _community Slack workspace: https://openedx.slack.com/ -.. _Getting Help: https://openedx.org/getting-help +Please do not report security issues in public. Please email security@tcril.org. .. |pypi-badge| image:: https://img.shields.io/pypi/v/{{ cookiecutter.repo_name }}.svg :target: https://pypi.python.org/pypi/{{ cookiecutter.repo_name }}/ @@ -136,3 +175,9 @@ For more information about these options, see the `Getting Help`_ page. .. |license-badge| image:: https://img.shields.io/github/license/edx/{{ cookiecutter.repo_name }}.svg :target: https://github.com/edx/{{ cookiecutter.repo_name }}/blob/main/LICENSE.txt :alt: License + +.. Choose one of the statuses below and remove the other status-badge lines. +.. |status-badge| image:: https://img.shields.io/badge/Status-Experimental-yellow +.. .. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen +.. .. |status-badge| image:: https://img.shields.io/badge/Status-Deprecated-orange +.. .. |status-badge| image:: https://img.shields.io/badge/Status-Unsupported-red From f0fddb91bdf46b706f0186837423ecb85d180afd Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Thu, 11 Aug 2022 13:48:05 -0400 Subject: [PATCH 2/3] docs: Correct the link to use the template. --- .../{{cookiecutter.placeholder_repo_name}}/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst index 3ab8d591..3ba794c9 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst @@ -102,7 +102,7 @@ For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide. -https://github.com/openedx/DoneXBlock/issues +https://github.com/openedx/{{ cookiecutter.repo_name }}/issues For more information about these options, see the `Getting Help`_ page. From aa883dd420894ef6580342e1f97a39350609d35c Mon Sep 17 00:00:00 2001 From: Feanil Patel Date: Fri, 12 Aug 2022 09:22:32 -0400 Subject: [PATCH 3/3] docs: Respond to review feedback. Fix a typo and add a header to clearly indicate that the readme should be read and updated after it has been generated. --- .../{{cookiecutter.placeholder_repo_name}}/README.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst index 3ba794c9..37f8d907 100644 --- a/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst +++ b/python-template/{{cookiecutter.placeholder_repo_name}}/README.rst @@ -1,6 +1,11 @@ {{cookiecutter.project_name}} ############################# +.. note:: + + This README was auto-generated. Please review its contents and update all + relevant sections. + |pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge| |license-badge| |status-badge| @@ -71,11 +76,11 @@ Every time you develop something in this repo Deploying ========= -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? +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? For details on how to deploy this component, checkout the `deployment how-to`_ -.. _deployment how-to: https://docs.openedx.org/projects/this-project/how-tos/how-to-deploy-this-component.html +.. _deployment how-to: https://docs.openedx.org/projects/{{ cookiecutter.repo_name }}/how-tos/how-to-deploy-this-component.html Getting Help ************