christianlight
/
tutor
mirror of https://github.com/ChristianLight/tutor.git
7
0
Fork 0
Code Issues Releases Activity

Clarify contributing/troubleshooting instructions

This commit is contained in:
Régis Behmo 2020-11-30 15:32:43 +01:00
parent 727c204e92
commit e6176e293c
4 changed files with 30 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -7,6 +7,9 @@ assignees: ''
---
<!-- Are you quite sure that you followed the instructions from the Troubleshooting section in the Tutor documentation? https://docs.tutor.overhang.io/troubleshooting.html -->
<!-- If not, please take the time to read them. -->
**Bug description**
<!-- A clear and concise description of what the bug is. Don't be afraid to include a lot of context and as much background information as possible. If applicable, add screenshots to help explain your problem. -->
<!-- Also include relevant error logs; for instance, to debug the LMS provide the output of `tutor local logs lms --tail=100` -->

4
CONTRIBUTING.rst
View File

@ -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 <http://discuss.overhang.io/>`_, although this is not mandatory. Are you trying to fix an existing issue? Please first `create a new issue <https://github.com/overhangio/tutor/issues/new/choose>`_, where we can discuss the problem and possible solutions.
Happy hacking! ☘️
Please check the relevant section of the Tutor docs: `https://docs.tutor.overhang.io/tutor.html#contributing <https://docs.tutor.overhang.io/tutor.html#contributing>`__.

7
docs/troubleshooting.rst
View File

@ -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 <https://github.com/overhangio/tutor/issues?utf8=%E2%9C%93&q=is%3Aissue>`_.
4. Search for your problem in the `community forums <https://discuss.overhang.io>`__.
5. If, despite all your efforts, you can't solve the problem, you may want to first discuss it in the `community forums <https://discuss.overhang.io>`__. 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 <https://discuss.overhang.io>`__. 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 <https://github.com/overhangio/tutor/issues/new>`__. 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 <https://github.com/overhangio/tutor/issues/new>`_. **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 <https://overhang.io/tutor/lts>`__.

21
docs/tutor.rst
View File

@ -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 <https://discuss.overhang.io>`__.
- Once we agree on a high-level solution, you should open a pull request on the `Tutor repository <https://github.com/overhangio/tutor/pulls>`__ 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! ☘️