Page Comparison

...

1.

...

Read How-Tos

Get familiar with the type of documentation we will be writing, which uses annotations.

• Toggles (includes boolean Django Settings)

  • Read how to document feature toggles (including boolean settings)

    • Give attention to the section on documenting legacy toggles.

• Settings (non-toggle, non-boolean)

  • See an example annotated setting.

  • See the definition for all setting annotations.

    • Note: There are fewer setting annotations than toggle annotations, but there is an optional setting_warning annotation.

  • Read how to document (non-boolean) settings.

2. Sign up

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:

  • Most complex:

    • If the sign-up column Bonus Refactor column is True, there is a somewhat more complicated refactor requested (see below). If you don’t want this challenge, please choose a different toggle. Comments on how to refactor should exist in the code.

  • Somewhat complex:

    • If the sign-up column class starts with “Legacy”, there is some minor refactoring requested (see below). If you don’t want to do the extra refactoring, please choose a different toggle. Here are the refactoring instructions for Legacy classes.

  • Optionally complex:

    • If you choose a toggle setting, there is an optional refactor described below.

  • Easiest:

    • If the 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.

  • If the module is not available, you’ll need to use search:

    • https://github.com/search?q=org%3Aedx+TYPE_YOUR_TOGGLE_OR_SETTING_HERE&type=code.

  • If you can’t find the toggle or setting, ask for help and/or add a note to the sign-up spreadsheet and choose a new row.

    • You can use git log search (a.k.a. pickaxe) to find when things were added/removed. This may help you determine if something wasn’t fully cleaned up. Also, here is another article on using pickaxe with additional options.

  • Note: It is possible that some toggles or settings in the sign-up sheet are from Studio and not LMS. Either way, we can document it.

• Learn about the purpose of the toggle.

  • Important: Save any links to useful background and documentation for the PR description.

  • Explore code, git blame, and past PRs and commit comments.

  • Search edX Feature Flags to potentially find past notes.

  • Search the additional reference tab in the sign-up spreadsheet to potentially find notes or date details.

• You may not feel confident in what to fill in for all of the annotations you’ll need to write. That is 100% ok. Please keep going.

  • In the description annotation, feel free to note any hesitations or partial confidence you have in any of the values.

  • An example sentence might read: “Due to a lack of history, it is unclear whether this toggle was meant to be temporary or not.”

• Additionally, see instructions to help with your research here.

4. Write the annotation

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.

...

• Remember that your documentation will be used by platform administrators, product owners and developers, and should address all of their needs.

• See “Short Background Reading” (above) for more details on how to write your annotations.

• Linting:

  • PRs in edx-platform will have linting enabled (soon) to ensure correctness on your annotations.

    • Note: You may be asked to rebase if you create your PR before linting lands.

  • If you are working in a different repo, ask if this linting can be added.

...

For toggle setting or non-toggle setting:

• Whether the setting is a toggle (boolean), or non-toggle (non-boolean), the toggle may be defined in the Open edX codebase, or the envs file may simply be setting the default for a setting defined in a third-party dependency.

• If the setting is being set for a third-party dependency, please note that in the annotation. If possible, provide a link to the third-party docs for the setting in the description annotation.

• If the sign-up sheet reads toggle setting, use toggle annotations and if it reads non-toggle setting, use setting annotations. See “Short Background Reading” (above) for details.

• (Optional) Refactor for toggle setting.

  • The following refactor only applies to Django Settings that are defined in the Open edX codebase, and not for defaults that are being set for settings defined in third-party dependencies.

  • There are new classes named SettingToggle and SettingDictToggle to support boolean Django Settings that are used as a toggle.

    • Read the ADR for SettingToggle and SettingDictToggle for background and sample usage.

    • Add a SettingToggle or SettingDictToggle definition to represent your chosen toggle.

    • This new class should be added to the Django app that most closely relates to the setting.

      • If all usages of the setting exist in one Django app, the choice is simple.

      • If the setting is used in both LMS and Studio, you can add it to openedx/core/toggles.py.

      • If you have questions about where to locate the definition, please ask for help.

    • Once you have added the definition, you can use it in place of settings throughout, as detailed in the ADR above or the sample PR below.

    • See this example PR refactoring to use SettingDictToggle.

...

For Legacy waffle classes:

• If you selected a deprecated Legacy waffle class, please help update it.

  • Import WaffleFlag instead of LegacyWaffleFlag or WaffleSwitch instead of LegacyWaffleSwitch.

  • For initializing these classes, provide an updated string with the flag name containing the namespace followed by a period, in place of the separate namespace string or class.

    • For example, if the legacy namespace was “my_namespace” and the legacy flag name was “my_flag”, then the updated flag name would be “my_namespace.my_flag”.

    • If the code was using LegacyWaffleFlagNamespace or LegacyWaffleSwitchNamespace and it is no longer used, remove it.

...

Bonus refactoring:

• If you signed-up for a toggle with Bonus Refactor as True in the sign-up sheet, there is a slightly more complex refactor requested.

• You’ll need to replace uses of any of the following functions def waffle(), def waffle_flags(), def waffle_switch(name).

• In place of these functions that are used to dynamically create the toggle classes, you will create a module level constant for each toggle.

  • See this PR with example replacement of waffle() and waffle_switch(name)

See the “Read How-tos” section above for instructions on how to document toggles and settings.

5. Create your PR

As noted above, please try to annotate a single toggle or setting in each PR. If you have reason to believe a PR should include multiple related toggles and settings, please ask, unless there is a group of related settings and toggles. The simpler the PR, the easier it will be to approve and merge.

...

• 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, Robert Raposa Natalia Berdnikov (Deactivated) 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.

• If the PR is in edx-platform, linting will help ensure correctness of the annotations. Your job will be more focused on ensuring the annotation details seem reasonable based on the details provided in the PR description.

• If the PR is for a repo other than edx-platform, ask for help to see if we can enable linting for that repository.

  • Also, linting is still in-progress for edx-platform, so PRs may need to rebase to pick this up once it is ready.

• Linting for annotations is enabled, which should help reduce the burden on reviewers.

FAQ

Where can I see the toggle and settings documentation?

...

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.

How do I document a setting or toggle that can be configured independently for both, LMS and CMS service variants? do I have to duplicate the annotations in both env files?

There are some settings or toggles that are defined in both, LMS and CMS env files. Before duplicating the annotations in both env files, please perform research on the setting/toggle purpose in both service variants. Then you can proceed according to the following scenarios:

...

The setting/toggle servers to the same purpose in both service variants: Document both the LMS and CMS settings using annotations, but make the CMS annotations refer to the LMS annotations rather than duplicating text on both sides.  Use the warning annotation to highlight if the setting/toggle needs to be set in both LMS and CMS with the same value, or any other non-obvious considerations. You can find an excellent example of this case in this pull request, where CMS annotations reference LMS annotations

...

See instructions for the same toggle in different services.

Retro

Pluses

1. Communications

   1. Announced earlier at contributors meeting

   2. Announced in discourse - including banner!

   3. Announced in slack

   4. Separate slack channel was great!

2. 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.

3. Spreadsheet to self-serve for signups and add notes.

4. Opening and closing ceremonies!

   1. With Metrics!

...