docs: Update template README.rst to match OEP-55 Guidelines #241
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -2,32 +2,27 @@ | |||||
| ############################# | ||||||
|
|
||||||
| |pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge| | ||||||
| |license-badge| |status-badge| | ||||||
|
|
||||||
| Purpose | ||||||
| ******* | ||||||
|
|
||||||
| {{ cookiecutter.project_short_description}} | ||||||
|
|
||||||
| The ``README.rst`` file should start with a brief description of the repository and its purpose. | ||||||
|
There was a problem hiding this comment. I know this is merged already, but thinking about linting, and also for clarification: what if we started each paragraph like this with There was a problem hiding this comment. Actually, I will make a PR with this change, and we can discuss there. |
||||||
| 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. | ||||||
|
|
||||||
| Getting Started | ||||||
| *************** | ||||||
|
|
||||||
| 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 <your_github_username>/<short_description> | ||||||
|
|
||||||
| # Using your favorite editor, edit the code to make your change. | ||||||
| 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 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? | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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 | ||||||
|
There was a problem hiding this comment. Maybe {{cookiecutter.repo_name}} in here, too?
Suggested change
|
||||||
|
|
||||||
| 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 <https://openedx.atlassian.net/wiki/spaces/DOC/pages/21627535/Publish+Documentation+on+Read+the+Docs>`_) | ||||||
|
|
||||||
| 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`_. | ||||||
|
|
||||||
robrap marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| 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/{{ cookiecutter.repo_name }}/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 <LICENSE.txt>`_ for details. | ||||||
|
|
||||||
| Contributing | ||||||
| ************ | ||||||
|
|
||||||
| Contributions are very welcome. | ||||||
| Please read `How To Contribute <https://openedx.org/r/how-to-contribute>`_ for details. | ||||||
|
|
||||||
| 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 Open edX Code of Conduct | ||||||
| **************************** | ||||||
|
|
||||||
| All community members are expected to follow the `Open edX Code of Conduct`_. | ||||||
|
|
||||||
| .. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/ | ||||||
|
|
||||||
| People | ||||||
| ****** | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| .. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/{{ cookiecutter.repo_name }} | ||||||
|
|
||||||
| Reporting Security Issues | ||||||
| ************************* | ||||||
|
|
||||||
| Please do not report security issues in public. Please email [email protected]. | ||||||
|
|
||||||
| .. |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 | ||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if there should be some replacement for "(please modify)". Could be something like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@feanil: Can you confirm your intention? Not sure if you intentionally don't want to add a note, or if you just missed this. Thanks.
Also note that if you read the README, it is clear that it should be updated. But, I'm just wondering if anything can make it more clear for cases where your eyes are passing over it, but you aren't actually reading it. It might be that mu suggestion is no better than what is there.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missed this the first time, I'll add it along with the other suggestions.