christianlight/tutor
6
0
Fork 0
mirror of https://github.com/ChristianLight/tutor.git synced 2024-11-16 01:57:16 +00:00
Code Issues Releases Activity
9446095665
tutor/docs/tutor.rst

121 lines
4.3 KiB
ReStructuredText
Raw Normal View History

Improve documentation
2018-12-26 15:00:47 +00:00
.. _tutor:
Tutor development
=================
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
Setting up your development environment
---------------------------------------
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
Start by cloning the Tutor repository::
Improve documentation
2018-12-26 15:00:47 +00:00
Migrate github repo to overhangio organization
2019-06-23 17:56:15 +00:00
git clone https://github.com/overhangio/tutor.git
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
cd tutor/
Improve documentation
2018-12-26 15:00:47 +00:00
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
Install requirements
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
~~~~~~~~~~~~~~~~~~~~
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
::
pip install -r requirements/dev.txt
Add unit tests! yay! Now, that was seriously missing.
2019-03-23 23:16:03 +00:00
Run tests
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
~~~~~~~~~
Add unit tests! yay! Now, that was seriously missing.
2019-03-23 23:16:03 +00:00
::
make test
Introduce automatic code formatting/linting Code formatting makes sure that the python code looks decent, but it does not check for coding errors. https://black.readthedocs.io/en/stable/ Code linting runs static error detection on the python code, but does not bother about formatting: https://pylint.readthedocs.io/en/latest/
2019-05-05 09:40:49 +00:00
Yes, there are very few unit tests for now, but this is probably going to change.
Code formatting
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
~~~~~~~~~~~~~~~
Introduce automatic code formatting/linting Code formatting makes sure that the python code looks decent, but it does not check for coding errors. https://black.readthedocs.io/en/stable/ Code linting runs static error detection on the python code, but does not bother about formatting: https://pylint.readthedocs.io/en/latest/
2019-05-05 09:40:49 +00:00
Tutor code formatting is enforced by `black <https://black.readthedocs.io/en/stable/>`_. To check whether your code changes conform to formatting standards, run::
make test-format
And to automatically fix formatting errors, run::
make format
Static error detection is performed by `pylint <https://pylint.readthedocs.io/en/latest/>`_. To detect errors, run::
make test-lint
Add unit tests! yay! Now, that was seriously missing.
2019-03-23 23:16:03 +00:00
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
Common developer tasks
----------------------
Generating the ``tutor`` executable binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
::
make bundle
Better documentation - More concise table of contents - New intro - Simpler make commands - Fix a couple typos here and there - Get rid of the default github issue template, and start using the template created online.
2019-05-13 14:33:26 +00:00
Generating the documentation
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
::
Better documentation - More concise table of contents - New intro - Simpler make commands - Fix a couple typos here and there - Get rid of the default github issue template, and start using the template created online.
2019-05-13 14:33:26 +00:00
pip install -r requirements/docs.txt
Tutor v3 complete rewrite Replace all make commands by a single "tutor" binary. Environment and data are all moved to ~/.tutor/local/share/tutor. We take the opportunity to add a web UI and revamp the documentation. This is a complete rewrite. Close #121. Close #147.
2019-01-22 20:25:04 +00:00
cd docs/
make html
You can then browse the documentation with::
make browse
Make tutor ready for the AWS cloud
2019-02-13 22:44:42 +00:00
Releasing a new version
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
~~~~~~~~~~~~~~~~~~~~~~~
Make tutor ready for the AWS cloud
2019-02-13 22:44:42 +00:00
feat: dynamic app name and version suffix Here, we make it possible to automatically append a suffix to the version and app name (in the sense of appdirs). This guarantees that a tutor edge project will not accidentally override another community release. In addition, we take the opportunity to document the tutor versioning format. (I've been meaning to do that for a long time)
2021-09-16 14:48:16 +00:00
- Bump the ``__version__`` value in ``tutor/__about__.py``. (see :ref:`versioning` below)
Clarify contributing/troubleshooting instructions
2020-11-30 14:32:43 +00:00
- Replace "Unreleased" by the version name and date in CHANGELOG.md.
Make tutor ready for the AWS cloud
2019-02-13 22:44:42 +00:00
- Create a commit with the version changelog.
Simplify the release process Instead of pushing to multiple remotes, push to just one. It will then sync changes to the other.
2021-03-17 15:45:01 +00:00
- Run ``make release``: this will push to the default repo/branch for the current branch.
Clarify contributing/troubleshooting instructions
2020-11-30 14:32:43 +00:00
feat: dynamic app name and version suffix Here, we make it possible to automatically append a suffix to the version and app name (in the sense of appdirs). This guarantees that a tutor edge project will not accidentally override another community release. In addition, we take the opportunity to document the tutor versioning format. (I've been meaning to do that for a long time)
2021-09-16 14:48:16 +00:00
.. _versioning:
Versioning
----------
The versioning format used in Tutor is the following::
RELEASE.MAJOR.MINOR(-BRANCH)
When making a new Tutor release, increment the:
- RELEASE version when a new Open edX release comes out. The new value should match the ordinal value of the first letter of the release name: Aspen 🡒 1, Birch 🡒 2, ... Zebra 🡒 26.
- MAJOR version when making a backward-incompatible change (prefixed by "💥" in the changelog, as explained below).
- MINOR version when making a backward-compatible change.
goodbye "edge" hello "nightly"! In conversations with edX, we learned that the name "edge" had negative undertones for historical reasons. Thus, we switch to "nightly", which means pretty much the same thing.
2021-09-28 16:18:36 +00:00
An optional BRANCH suffix may be appended to the release name to indicate that extra changes were added on top of the latest release. For instance, "x.y.z-nightly" corresponds to release x.y.z on top of which extra changes were added to make it compatible with the Open edX master branches (see the :ref:`tutorial on running Tutor Nightly <nightly>`).
feat: dynamic app name and version suffix Here, we make it possible to automatically append a suffix to the version and app name (in the sense of appdirs). This guarantees that a tutor edge project will not accidentally override another community release. In addition, we take the opportunity to document the tutor versioning format. (I've been meaning to do that for a long time)
2021-09-16 14:48:16 +00:00
`Officially-supported plugins <https://overhang.io/tutor/plugins>`__ follow the same versioning pattern. As a third-party plugin developer, you are encouraged to use the same pattern to make it immediately clear to your end-users which Open edX versions are supported.
Clarify contributing/troubleshooting instructions
2020-11-30 14:32:43 +00:00
.. _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.
- 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.
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
- 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 :) As for the title, `conventional commits <https://www.conventionalcommits.org>`__ are preferred. Check the repo history!
Clarify contributing/troubleshooting instructions
2020-11-30 14:32:43 +00:00
Happy hacking! ☘️
docs: link to the maintainers team handbook
2021-03-25 16:13:22 +00:00
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
.. _maintainers:
docs: link to the maintainers team handbook
2021-03-25 16:13:22 +00:00
Joining the team of Tutor Maintainers
-------------------------------------
docs: advertise Cairn and the maintainers group Here we add to the docs a few shameless plugs about Cairn -- because it's really awesome! We also add a few improvements to the wording, here and there.
2021-06-25 14:52:05 +00:00
We have an open team of volunteers who help support the project. You can read all about it `here <https://discuss.overhang.io/t/the-tutor-maintainer-handbook/1375>`__ -- and we hope that you'll consider joining us 😉
Copy Permalink