» Contributing to Read the Docs
Contributing to Read the Docs
You are here to help on Read the Docs? Awesome, feel welcome and read the following sections in order to know how to ask questions and how to work on something.
All members of our community are expected to follow our Code of Conduct. Please make sure you are welcoming and friendly in all of our spaces.
Get in touch
Contributing to development
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 installation guide. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Issue. These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system.
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.
You can read all of our Developer documentation to understand more the development of Read the Docs. When contributing code, then please follow the standard Contribution Guidelines set forth at contribution-guide.org​.
Contributing to documentation
Documentation for Read the Docs itself is hosted by Read the Docs at https://docs.readthedocs.io (likely the website you are currently reading).
There are guidelines around writing and formatting documentation for the project. For full details, including how to build it, see Building and Contributing to Documentation.
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.
You will need Triage permission on the project in order to do this. You can ask one of the members of the Read the Docs Team to give you access.
Initial triage
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, reference the other ticket that is already addressing the problem and close the duplicate.
… 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).
My builds stopped working. Please help! Ask for a link to the build log and for which project is affected.
… 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 seems valid but requires further discussion between core contributors because there might be different possibilities on how to implement the feature, then also add the label Needed: design decision.
… 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.
… 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.
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.
Builds are not starting
… 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.
… 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.
After we finished the initial triaging of new tickets, no ticket should be left without a label.
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.
High Priority
If the issue is urgent, assign this label. In the best case also go forward to resolve the ticket yourself as soon as possible.
Good First Issue
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 are all tickets that have the right amount of scope to be handled during a sprint. They are very focused and encapsulated.
For a full list of available labels and their meanings, see Overview of issue labels.
Helpful links for triaging
Here is a list of links for contributors that look for work:
Helping on translations
If you wish to contribute translations, please do so on Transifex.
DigitalOcean App Platform ship your code to production in just a few clicks. Try now with $100 credit.
Ad by EthicalAds
© Copyright 2010-2021, Read the Docs, Inc & contributors. Revision a878daa8.
Built with Sphinx using a theme provided by Read the Docs.
LogoRead the Docs tutorialGetting Started with SphinxGetting Started with MkDocsImporting Your DocumentationRead the Docs featuresChoosing Between Our Two SitesGlossaryConfiguration FileVCS IntegrationsCustom Domains and White LabelingVersioned DocumentationDownloadable DocumentationDocumentation Hosting FeaturesServer Side SearchTraffic AnalyticsPreview Documentation from Pull RequestsBuild Notifications and WebhooksSecurity LogConnecting Your VCS AccountBuild ProcessEnvironment VariablesBadgesSite SupportFrequently Asked QuestionsGuides for documentation authorsGuides for project administratorsGuides for developers and designersSubprojectsSingle Version DocumentationFeature FlagsLocalization of DocumentationUser-defined RedirectsAutomatic RedirectsAutomation RulesPublic APIGet in touchContributing to developmentContributing to documentationTriaging ticketsInitial triageAdditional labels for categorizationHelpful links for triagingHelping on translationsDeveloper documentationRoadmapGoogle Summer of CodeCode of ConductSecurityDMCA Takedown PolicyPolicy for Abandoned ProjectsChangelogAbout Read the DocsRead the Docs TeamRead the Docs Open Source PhilosophyThe Story of Read the DocsAdvertisingSponsors of Read the DocsRead the Docs for BusinessLegal Documents and Policies
Read the Docs