From e6176e293c2e5f3d13be331c6ff23a07c0665a19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Mon, 30 Nov 2020 15:32:43 +0100 Subject: [PATCH] Clarify contributing/troubleshooting instructions --- .github/ISSUE_TEMPLATE/bug_report.md | 3 +++ CONTRIBUTING.rst | 4 +--- docs/troubleshooting.rst | 7 ++++++- docs/tutor.rst | 21 ++++++++++++++++++++- 4 files changed, 30 insertions(+), 5 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f56346b..69c4738 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,6 +7,9 @@ assignees: '' --- + + + **Bug description** diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d57bc4b..ad357f5 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,6 +1,4 @@ Contribution Guidelines ======================= -You are most warmly welcome to make contributions and open pull requests on the Tutor repository! Would you like to develop a new feature? You can discuss it first on the `Tutor discussion forums `_, although this is not mandatory. Are you trying to fix an existing issue? Please first `create a new issue `_, where we can discuss the problem and possible solutions. - -Happy hacking! ☘️ \ No newline at end of file +Please check the relevant section of the Tutor docs: `https://docs.tutor.overhang.io/tutor.html#contributing `__. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 1a5e1cd..de1c581 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -5,11 +5,16 @@ Troubleshooting What should you do if you have a problem? +.. warning:: + **Do not** create a Github issue! + 1. Read the error logs that appear in the console. When running a single server platform as daemon, you can view the logs with the ``tutor local logs`` command. (see :ref:`logging` below) 2. Check if your problem already has a solution right here in the :ref:`troubleshooting` section. 3. Search for your problem in the `open and closed Github issues `_. 4. Search for your problem in the `community forums `__. -5. If, despite all your efforts, you can't solve the problem, you may want to first discuss it in the `community forums `__. Please give as much details about your problem as possible! As a rule of thumb, people will not dedicate more time to solving your problem than you took to write your question. +5. If, despite all your efforts, you can't solve the problem by yourself, you should discuss it in the `community forums `__. Please give as much details about your problem as possible! As a rule of thumb, **people will not dedicate more time to solving your problem than you took to write your question**. +6. If you are *absolutely* positive that you are facing a technical issue with Tutor, and not with Open edX, not with your server, not your custom configuration, then, and only then, should you open an issue on `Github `__. You *must* follow the instructions from the issue template!!! If you do not follow this procedure, your Github issues will be mercilessly closed 🤯. + 6. If you have a technical background, you may try to decide if the issue is related to Open edX or if it's specific to Tutor. In the latter case, you are most welcome to open an `issue on Github `_. **Please follow the instructions from the issue template!!!** Your issue will be examined in all cases, but you can make our life much easier by giving us as much background information as possible. Do you need professional assistance with your tutor-managed Open edX platform? Overhang.IO offers online support as part of its `Long Term Support (LTS) offering `__. diff --git a/docs/tutor.rst b/docs/tutor.rst index 7a84f67..4ed7984 100644 --- a/docs/tutor.rst +++ b/docs/tutor.rst @@ -63,8 +63,27 @@ Releasing a new version ----------------------- - Bump the ``__version__`` value in ``tutor/__about__.py``. -- Replace "Latest" by the version name and date in CHANGELOG.md. +- Replace "Unreleased" by the version name and date in CHANGELOG.md. - Create a commit with the version changelog. - ``make release`` (this assumes that there are two remotes named "origin" and "overhangio") After a regular push to ``master``, run ``make nightly`` to update the "nightly" tag. + +.. _contributing: + +Contributing to Tutor +--------------------- + +Third-party contributions to Tutor and its plugins are more than welcome! Just make sure to follow these guidelines: + +- Outside of obvious bugs, contributions should be discussed first in the `official Tutor forums `__. +- Once we agree on a high-level solution, you should open a pull request on the `Tutor repository `__ or the corresponding plugin. +- Write a good Git commit title and message: explain why you are making this change, what problem you are solving and which solution you adopted. Link to the relevant conversation topics in the forums and describe your use case. We *love* long, verbose descriptions :) +- Make sure that all tests pass by running ``make test`` (see above). +- If your PR is in the Tutor core repository, add an item to the CHANGELOG file, in the "Unreleased" section. Use the same format as the other items:: + + - [TYPE] DESCRIPTION + +Where "TYPE" is either "Bugfix", "Improvement", "Feature" or "Security". You should add an explosion emoji ("💥") before "[TYPE]" if you are making a breaking change. + +Happy hacking! ☘️