2011-09-19 02:33:15 +00:00
|
|
|
Contributing to Read the Docs
|
|
|
|
=============================
|
|
|
|
|
2015-07-21 08:34:36 +00:00
|
|
|
You are here to help on Read the Docs? Awesome, feel welcome and read the
|
2018-02-21 23:46:13 +00:00
|
|
|
following sections in order to know how to ask questions and how to work on something.
|
2015-07-21 08:34:36 +00:00
|
|
|
|
2017-03-02 23:11:03 +00:00
|
|
|
All members of our community are expected to follow our :doc:`/code-of-conduct`.
|
|
|
|
Please make sure you are welcoming and friendly in all of our spaces.
|
|
|
|
|
2018-02-21 23:46:13 +00:00
|
|
|
Get in touch
|
|
|
|
------------
|
|
|
|
|
|
|
|
- Ask usage questions ("How do I?") on `StackOverflow`_.
|
|
|
|
- Report bugs, suggest features or view the source code `on GitHub`_.
|
|
|
|
- Discuss topics on `Gitter`_.
|
2018-02-21 23:49:16 +00:00
|
|
|
- On IRC find us at `#readthedocs`_.
|
2018-02-21 23:46:13 +00:00
|
|
|
|
|
|
|
.. _StackOverFlow: https://stackoverflow.com/questions/tagged/read-the-docs
|
|
|
|
.. _on GitHub: https://github.com/rtfd/readthedocs.org
|
|
|
|
.. _Gitter: https://gitter.im/rtfd/readthedocs.org
|
2018-02-21 23:49:16 +00:00
|
|
|
.. _#readthedocs: irc://irc.freenode.net/readthedocs
|
2015-07-21 08:34:36 +00:00
|
|
|
|
|
|
|
Contributing to development
|
|
|
|
---------------------------
|
|
|
|
|
2015-07-21 08:39:31 +00:00
|
|
|
If you want to deep dive and help out with development on Read the Docs, then
|
|
|
|
first get the project installed locally according to the
|
2018-05-24 19:29:59 +00:00
|
|
|
:doc:`Installation Guide <install>`. After that is done we
|
2015-07-21 08:39:31 +00:00
|
|
|
suggest you have a look at tickets in our issue tracker that are labelled `Good
|
2017-11-13 01:57:11 +00:00
|
|
|
First Issue`_. These are meant to be a great way to get a smooth start and
|
2015-07-21 08:39:31 +00:00
|
|
|
won't put you in front of the most complex parts of the system.
|
|
|
|
|
2018-09-06 00:44:24 +00:00
|
|
|
If you are up to more challenging tasks with a bigger scope,
|
|
|
|
then there are a set of tickets with a `Feature`_ or `Improvement`_ tag.
|
|
|
|
These tickets have a general overview and description of the work required to finish.
|
|
|
|
If you want to start somewhere, this would be a good place to start
|
|
|
|
(make sure that the issue also have the `Accepted`_ label).
|
|
|
|
That said, these aren't necessarily the easiest tickets.
|
|
|
|
They are simply things that are explained.
|
|
|
|
If you still didn't find something to work on, search for the `Sprintable`_ label.
|
|
|
|
Those tickets are meant to be standalone and can be worked on ad-hoc.
|
2015-07-21 08:39:31 +00:00
|
|
|
|
|
|
|
When contributing code, then please follow the standard Contribution
|
|
|
|
Guidelines set forth at `contribution-guide.org`_.
|
2014-01-05 22:20:43 +00:00
|
|
|
|
2017-12-01 06:51:11 +00:00
|
|
|
We have a strict code style that is easy to follow since you just have to
|
|
|
|
install `pre-commit`_ and it will automatically run different linting tools
|
|
|
|
(`autoflake`_, `autopep8`_, `docformatter`_, `isort`_, `prospector`_, `unify`_
|
|
|
|
and `yapf`_) to check your changes before you commit them. `pre-commit` will let
|
2019-02-13 16:22:04 +00:00
|
|
|
you know if there were any problems that it wasn't able to fix automatically.
|
2017-12-01 06:51:11 +00:00
|
|
|
|
2018-12-12 09:56:20 +00:00
|
|
|
To run the `pre-commit` command and check your changes:
|
2017-12-01 06:51:11 +00:00
|
|
|
|
2018-12-12 09:56:20 +00:00
|
|
|
.. prompt:: bash $
|
2017-12-01 06:51:11 +00:00
|
|
|
|
2018-12-12 09:56:20 +00:00
|
|
|
pip install -U pre-commit
|
|
|
|
git add <your-modified-files>
|
|
|
|
pre-commit run
|
2017-12-01 06:51:11 +00:00
|
|
|
|
2018-12-12 09:56:20 +00:00
|
|
|
or to run against a specific file:
|
|
|
|
|
|
|
|
.. prompt:: bash $
|
|
|
|
|
|
|
|
pre-commit run --files <file.py>
|
2017-12-01 06:51:11 +00:00
|
|
|
|
|
|
|
`pre-commit` can also be run as a git pre-commit hook. You can set this up
|
2018-12-12 09:56:20 +00:00
|
|
|
with:
|
|
|
|
|
|
|
|
.. prompt:: bash $
|
2017-12-01 06:51:11 +00:00
|
|
|
|
2018-12-12 09:56:20 +00:00
|
|
|
pre-commit install
|
2017-12-01 06:51:11 +00:00
|
|
|
|
|
|
|
After this installation, the next time you run `git commit` the `pre-commit run`
|
|
|
|
command will be run immediately and will inform you of the changes and errors.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
Our code base is still maturing and the core team doesn't yet recommend
|
|
|
|
running this as a pre-commit hook due to the number of changes this will
|
|
|
|
cause while constructing a pull request. Independent pull requests with
|
|
|
|
linting changes would be a great help to making this possible.
|
|
|
|
|
2017-11-27 16:42:09 +00:00
|
|
|
|
2018-09-06 00:44:24 +00:00
|
|
|
.. _Feature: https://github.com/rtfd/readthedocs.org/issues?direction=desc&labels=Feature&page=1&sort=updated&state=open
|
|
|
|
.. _Improvement: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3AImprovement
|
|
|
|
.. _Accepted: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3AAccepted
|
2017-11-13 01:57:11 +00:00
|
|
|
.. _Good First Issue: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
|
2015-07-21 08:39:31 +00:00
|
|
|
.. _Sprintable: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3ASprintable
|
|
|
|
.. _contribution-guide.org: http://www.contribution-guide.org/#submitting-bugs
|
2012-10-03 16:18:34 +00:00
|
|
|
|
2017-12-03 22:51:16 +00:00
|
|
|
.. _pre-commit: https://github.com/pre-commit/pre-commit
|
2017-11-27 16:42:09 +00:00
|
|
|
.. _autoflake: https://github.com/myint/autoflake
|
|
|
|
.. _autopep8: https://github.com/hhatto/autopep8
|
|
|
|
.. _docformatter: https://github.com/myint/docformatter
|
2017-12-01 06:40:30 +00:00
|
|
|
.. _isort: https://github.com/timothycrosley/isort
|
2017-12-01 06:51:11 +00:00
|
|
|
.. _prospector: https://prospector.landscape.io/en/master
|
2017-11-27 16:42:09 +00:00
|
|
|
.. _unify: https://github.com/myint/unify
|
|
|
|
.. _yapf: https://github.com/google/yapf
|
|
|
|
|
2015-07-21 08:41:57 +00:00
|
|
|
Triaging tickets
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Here is a brief explanation on how we triage incoming tickets to get a better
|
|
|
|
sense of what needs to be done on what end.
|
|
|
|
|
2017-03-09 22:56:46 +00:00
|
|
|
.. note:: You will need Triage permission on the project in order to do this.
|
|
|
|
You can ask one of the members of the :doc:`team` to give you access.
|
|
|
|
|
2015-07-21 09:18:48 +00:00
|
|
|
Initial triage
|
|
|
|
~~~~~~~~~~~~~~
|
|
|
|
|
2015-07-21 08:41:57 +00:00
|
|
|
When sitting down to do some triaging work, we start with the `list of
|
|
|
|
untriaged tickets`_. We consider all tickets that do not have a label as
|
|
|
|
untriaged. The first step is to categorize the ticket into one of the
|
|
|
|
following categories and either close the ticket or assign an appropriate
|
|
|
|
label. The reported issue …
|
|
|
|
|
|
|
|
… is not valid
|
|
|
|
If you think the ticket is invalid comment why you think it is invalid,
|
|
|
|
then close the ticket. Tickets might be invalid if they were already fixed
|
|
|
|
in the past or it was decided that the proposed feature will not be
|
|
|
|
implemented because it does not conform with the overall goal of Read the
|
|
|
|
Docs. Also if you happen to know that the problem was already reported,
|
2018-09-06 00:44:24 +00:00
|
|
|
reference the other ticket that is already addressing the problem and close the duplicate.
|
2015-07-21 08:41:57 +00:00
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Builds fail when using matplotlib*:
|
|
|
|
If the described issue was already fixed, then explain and instruct to
|
|
|
|
re-trigger the build.
|
|
|
|
- *Provide way to upload arbitrary HTML files*:
|
|
|
|
It was already decided that Read the Docs is not a dull hosting platform
|
|
|
|
for HTML. So explain this and close the ticket.
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
.. _triage-not-enough-information:
|
|
|
|
|
2015-07-21 08:41:57 +00:00
|
|
|
… does not provide enough information
|
|
|
|
Add the label **Needed: more information** if the reported issue does not
|
|
|
|
contain enough information to decide if it is valid or not and ask on the
|
|
|
|
ticket for the required information to go forward. We will re-triage all
|
|
|
|
tickets that have the label **Needed: more information** assigned. If the
|
|
|
|
original reporter left new information we can try to re-categorize the
|
|
|
|
ticket. If the reporter did not come back to provide more required
|
|
|
|
information after a long enough time, we will close the ticket (this will be
|
|
|
|
roughly about two weeks).
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *My builds stopped working. Please help!*
|
|
|
|
Ask for a link to the build log and for which project is affected.
|
|
|
|
|
2018-09-06 00:44:24 +00:00
|
|
|
… is a valid feature proposal
|
|
|
|
If the ticket contains a feature that aligns with the goals
|
|
|
|
of Read the Docs, then add the label **Feature**. If the proposal
|
2015-07-21 08:41:57 +00:00
|
|
|
seems valid but requires further discussion between core contributors
|
|
|
|
because there might be different possibilities on how to implement the
|
2018-09-06 00:44:24 +00:00
|
|
|
feature, then also add the label **Needed: design decision**.
|
2015-07-21 08:41:57 +00:00
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Provide better integration with service XYZ*
|
|
|
|
- *Achieve world domination* (also needs the label **Needed: design
|
|
|
|
decision**)
|
|
|
|
|
2018-09-06 00:44:24 +00:00
|
|
|
… is a small change to the source code
|
|
|
|
If the ticket is about code cleanup or small changes to existing features
|
|
|
|
would likely have the **Improvement** label.
|
|
|
|
The distinction for this label is that these issues have a lower priority than a Bug,
|
|
|
|
and aren't implementing new features.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Refactor namedtuples to dataclasess*
|
|
|
|
- *Change font size for the project's title*
|
|
|
|
|
2015-07-21 08:41:57 +00:00
|
|
|
… is a valid problem within the code base:
|
|
|
|
If it's a valid bug, then add the label **Bug**. Try to reference related
|
|
|
|
issues if you come across any.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Builds fail if conf.py contains non-ascii letters*
|
|
|
|
|
|
|
|
… is a currently valid problem with the infrastructure:
|
|
|
|
Users might report about web server downtimes or that builds are not
|
|
|
|
triggered. If the ticket needs investigation on the servers, then add the
|
|
|
|
label **Operations**.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Builds are not starting*
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
.. _triage-support-tickets:
|
|
|
|
|
2015-07-21 08:41:57 +00:00
|
|
|
… is a question and needs answering:
|
|
|
|
If the ticket contains a question about the Read the Docs platform or the
|
|
|
|
code, then add the label **Support**.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *My account was set inactive. Why?*
|
|
|
|
- *How to use C modules with Sphinx autodoc?*
|
|
|
|
- *Why are my builds failing?*
|
|
|
|
|
|
|
|
… requires a one-time action on the server:
|
|
|
|
Tasks that require a one time action on the server should be assigned the
|
|
|
|
two labels **Support** and **Operations**.
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
- *Please change my username*
|
2016-02-11 16:16:15 +00:00
|
|
|
- *Please set me as owner of this abandoned project*
|
2015-07-21 08:41:57 +00:00
|
|
|
|
|
|
|
After we finished the initial triaging of new tickets, no ticket should be left
|
|
|
|
without a label.
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
.. _list of untriaged tickets: https://github.com/rtfd/readthedocs.org/issues?q=is:issue+is:open+no:label
|
|
|
|
|
2015-07-21 09:18:48 +00:00
|
|
|
Additional labels for categorization
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
Additionally to the labels already involved in the section above, we have a
|
|
|
|
few more at hand to further categorize issues.
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
*High Priority*
|
2015-07-21 09:18:48 +00:00
|
|
|
If the issue is urgent, assign this label. In the best case also go forward to
|
|
|
|
resolve the ticket yourself as soon as possible.
|
|
|
|
|
2018-01-11 20:16:24 +00:00
|
|
|
*Good First Issue*
|
2015-07-21 09:18:48 +00:00
|
|
|
This label marks tickets that are easy to get started with. The ticket
|
|
|
|
should be ideal for beginners to dive into the code base. Better is if the
|
|
|
|
fix for the issue only involves touching one part of the code.
|
|
|
|
|
|
|
|
*Sprintable*
|
|
|
|
Sprintable are all tickets that have the right amount of scope to be
|
|
|
|
handled during a sprint. They are very focused and encapsulated.
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
For a full list of available labels and their meanings, see
|
2018-05-24 19:29:59 +00:00
|
|
|
:doc:`issue-labels`.
|
2015-07-24 10:31:39 +00:00
|
|
|
|
2015-07-21 09:20:19 +00:00
|
|
|
Helpful links for triaging
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
2015-07-24 10:31:39 +00:00
|
|
|
Here is a list of links for contributors that look for work:
|
2015-07-21 09:20:19 +00:00
|
|
|
|
|
|
|
- `Untriaged tickets
|
|
|
|
<https://github.com/rtfd/readthedocs.org/issues?q=is:issue+is:open+no:label>`_:
|
|
|
|
Go and triage them!
|
|
|
|
- `Tickets labelled with Needed: more information
|
|
|
|
<https://github.com/rtfd/readthedocs.org/issues?utf8=✓&q=is:open+is:issue+label:"Needed:+more+information">`_:
|
|
|
|
Come back to these tickets once in a while and close those that did not get
|
|
|
|
any new information from the reporter. If new information is available, go
|
|
|
|
and re-triage the ticket.
|
|
|
|
- `Tickets labelled with Operations
|
|
|
|
<https://github.com/rtfd/readthedocs.org/issues?q=is:open+is:issue+label:Operations>`_:
|
|
|
|
These tickets are for contributors who have access to the servers.
|
|
|
|
- `Tickets labelled with Support
|
|
|
|
<https://github.com/rtfd/readthedocs.org/issues?q=is:open+is:issue+label:Support>`_:
|
|
|
|
Experienced contributors or community members with a broad knowledge about
|
|
|
|
the project should handle those.
|
|
|
|
- `Tickets labelled with Needed: design decision
|
|
|
|
<https://github.com/rtfd/readthedocs.org/issues?q=is:open+is:issue+label:"Needed:+design+decision">`_:
|
|
|
|
Project leaders must take actions on these tickets. Otherwise no other
|
|
|
|
contributor can go forward on them.
|
|
|
|
|
2015-07-21 08:41:19 +00:00
|
|
|
Helping on translations
|
|
|
|
-----------------------
|
2012-10-03 16:18:34 +00:00
|
|
|
|
|
|
|
If you wish to contribute translations, please do so on `Transifex`_.
|
|
|
|
|
|
|
|
.. _Transifex: https://www.transifex.com/projects/p/readthedocs/
|