Help document the Open edX platform in celebration of International Day of Education (Jan 24)!
UPDATE: Doc-a-thon results available in our blog post.
This page is about the Doc-a-thon on Toggles and Settings, taking place January 25-29, 2021, and extended through March 15.
Participation will take a couple of hours to help research and document some of our feature toggles or settings.
The documentation for toggles and settings is a crucial source of information for a very wide audience, including platform administrators, product owners and developers.
Additionally, we can help reduce the complexity of our system by properly documenting which toggles and settings were meant to be temporary, along with target removal dates (as detailed later), to help drive deprecation/removal.
January 25, 11am EST / 4pm UTC: (Optional) Opening meeting on Zoom
(Optional) Watch recorded Opening meeting (Passcode: $VA7g^s6)
January 25-29, asynchronous doc-a-thon efforts.
January 29, 11:30am EST / 4:30pm UTC: Watch recorded Closing meeting (Passcode: N.R8=3Zn)
UPDATE: doc-a-thon extended through March 15.
There is a dedicated Open edX Slack channel #doc-a-thon.
Please join if you want to discuss, ask questions, and exchange information.
We will have several community or edX team members available there to answer your questions and help.
FYI: edX employees can access this same channel from our Slack instance. Just ask to be invited.
Feel great for celebrating the International Day of Education (Jan 24) by making it easier to use the Open edX platform to help educate everyone, everywhere.
Earn a participation badge or a top-2-participants, badge if badges are your thing.
Get mentioned or highlighted in our Open edX blog article detailing the results of the doc-a-thon.
Feel free to add comments with questions or ask in Slack. Thank you!
Get familiar with the type of documentation we will be writing, which uses annotations.
Toggles (includes boolean Django Settings)
Settings (non-toggle, non-boolean)
Choosing a setting or toggle in the LMS Sign-up for Toggle and Settings Doc-a-thon spreadsheet:
First, prioritize documenting Toggles over Settings.
All unassigned Toggles have a yellow background on the sheet and have a value of “Toggle” in the “Toggle or Setting” column.
Only if you don’t see a Toggle that’s available for you, then sign up for a “Setting”.
Why: We have 200 Toggles and 530 Settings. We want to complete Toggles first since they:
provide an on-ramp to our deprecation/removal (DEPR) pipeline and allow Open edX operators discoverability into the various features they can turn on and off.
Next, choose a setting or toggle that matches the complexity-level you are looking for:
If the sign-up column
Bonus Refactor column is True, there is a somewhat more complicated refactor requested. Comments on how to refactor should exist in the code.
If the sign-up column
class starts with “Legacy”, there is some minor refactoring requested. Here are the refactoring instructions for Legacy classes.
If you choose a
toggle setting, there is an optional refactor described below.
module column has a value, and none of the above cases match, you should be able to quickly locate the toggle or setting.
Next, add your github username to the row to claim it as yours.
Choose any that interests you, whether you are an expert or not. If you need help from experts, just ask for help.
Research the toggle or setting to prepare for your documentation.
If the sign-up sheet includes a value in the
module column, it should help you quickly locate the definition.
Many modules should be in edx/edx-platform, but it could be in the repo of a dependency.
Additionally, see instructions to help with your research here.
Please try to annotate a single toggle or setting in each PR, or a group of related toggles and settings. See “Create your PR” for more details.
See the “Read How-tos” section above for instructions on how to document toggles and settings.
As noted above, please try to annotate a single toggle or setting in each PR, unless there is a group of related settings and toggles. The simpler the PR, the easier it will be to approve and merge.
Start your PR title with
[TSD]. This will designate the PR as part of the Toggle and Setting Doc-a-thon.
For the PR description:
Clearly state the name of the toggle or setting.
Include links to any documentation supporting your annotations in the PR description. Don’t make your reviewer repeat all the research you already did.
Include any additional details from the sign-in sheet that might be useful, or note any additional refactoring that was requested.
Add a link to the PR in the PR column in the sign-up spreadsheet.
We’ll follow the typical review process from here, and merge as soon as we can.
Thank you for documenting one of our toggles or settings! If you want to put your new skills to good use, sign-up for another one and start again.
In addition to following the standard PR review process, see the following special considerations:
Add your github username to the
Github reviewer column in the sign-up spreadsheet for the row (or rows) associated with the PR.
If the rows are knowingly missing from the sign-up spreadsheet, Natalia Berdnikov can help add it.
If the PR link is missing from the sign-up spreadsheet, please update or ask the author to update.
If the PR title or description doesn’t include the information requested under “Create your PR” above, please ask for it and move on. This information should make your review much simpler.
Read through the “Process for PR Authors”.
Note: some sections may not apply to the PR you are reviewing, and the PR description should help you understand where you need to focus.
If the PR contains multiple toggles and settings, and it isn’t clear to you why, feel free to ask that it be split into multiple PRs.
Linting for annotations is enabled, which should help reduce the burden on reviewers.
Inline in the code where it is defined.
For edx-platform, the annotations are published to readthedocs.
Some toggle annotations are not included in this document, but are used as part of other reporting. Please provide feedback if you’d like to see additional details.
Annotations defined in edx-platform dependencies are not yet included in this report.
Note: Additional linting is still in progress. You may need to rebase your PR to pick up additional linting.
You can see toggle annotation errors by searching the quality pylint errors for type “toggle” or “setting”.
Sure, you can add new ones. Reach out to Robert Raposa to add new toggles to the sheet. You can ping in the #doc-a-thon Slack channel.
You can pick anything you are interested in, whether you are an expert or not. If you are not an expert, feel free to ask on Slack.
If you are a core contributor and can review, please do so. Also, anyone is welcome to help do a first-pass review. Robert will work on finding reviewers to get the rest of the PRs merged.
For now, please annotate that it is slated for removal/deprecation in the annotation as detailed in the how-to document. We can later follow the full DEPR process.
See instructions for the same toggle in different services.
Announced earlier at contributors meeting
Announced in discourse - including banner!
Announced in slack
Separate slack channel was great!
This document was very useful in getting started. Regis’s video was also nice to get started, having the full process recorded would be really nice.
Spreadsheet to self-serve for signups and add notes.
Opening and closing ceremonies!
Perfect is the enemy of good?
What could have sped up the PR reviews?
(Future) Toggle linting and lint amnesty will provide faster feedback loops.
We were resolving open questions while reviewing.
Splitting delegation and reviewing to different people.
Extend the event to a longer duration!
What are the bottlenecks?
Longer time → How to keep the energy up?
Have a goal!
Badges and “competition” helps encourage
Would prefer to externalize outside of Discourse.
Top contributor award as well
edX Legal team needs to be given heads up about the doc-a-thon. If many new authors participate, signing a new contributor agreement and Legal processing them can become a bottleneck. Also, need this agreement in Docusign!