[Bug][Documentation] Translation: "main" is not default, but "release/ulmo.1"

Site Operators
1

From Configuration and customisation — Tutor documentation

ATLAS_REVISION (default: "main" for Tutor Main, or "{{ OPENEDX_COMMON_VERSION }}" if a named release is used)

But it was by default ulmo.1 on my instance. So either the doc is wrong, or the code is wrong, which I don’t know. (PS: In case anyone read this too fast, I do not need help for translations)

Extra information

Context

I was looking to fix french translations, and while investigating, I saw that the repository openedx-translations/translations at main · openedx/openedx-translations · GitHub already contained the proper french translation for some stuff, but my instance didn’t.

Issue

Default translations I had on my Ulmo instance, is base on git branch release/ulmo.1, which is a tag. Simple diagnostic:

grep -RIn ATLAS "$(tutor config printroot)/env"  
/home/user/.local/share/tutor/env/plugins/mfe/build/mfe/Dockerfile:50:RUN make OPENEDX_ATLAS_PULL=true ATLAS_OPTIONS="--repository=openedx/openedx-translations --revision=release/ulmo.1 " pull_translations

Fix

For anyone having the issue, the fix is simple, set ATLAS_REVISION: main in config.yml. And rebuild affected docker images (mfe, …).

Others

I investigated this around and after 16 March from my notes, and I don’t remember exactly when I created this instance of Open edX, but it is no older than start of February.

PS: Don’t really know what tags I should put.

2

Oh well, amusing how writing help see see things more clearly:

The documentation actually state it correctly ATLAS_REVISION (default: "main" for Tutor Main, or "{{ OPENEDX_COMMON_VERSION }}" if a named release is used)

"{{ OPENEDX_COMMON_VERSION }}" must be release/ulmo.1 then ?

I don’t know where that variable is set:

# Both returns nothing
grep -RIn OPENEDX_COMMON_VERSION ~/.local/share/tutor/env/
grep -RIn OPENEDX_COMMON_VERSION ~/.local/share/tutor/config.yml

I also installed tutor[full], latest version, simply following the tutorial, although the version is fixed with a lock file in my repository.

In conclusion, the simplest thing that could be done, is changing the documentation sentence by something like:

ATLAS_REVISION (default: “{{ OPENEDX_COMMON_VERSION }}”, check Configuration and customisation — Tutor documentation)

As the link contains the following doc:

OPENEDX_COMMON_VERSION (default: "release/ulmo.2", or master in Tutor Main)

3

OPENEDX_COMMON_VERSION would be set by the version of Tutor that you are using, for example 21.0.1 would be release/ulmo.1 or similarly 21.0.3 would be release/ulmo.2

You can query your current version with tutor config printvalue OPENEDX_COMMON_VERSION

The correct method to do this in CLI would be tutor config save --set ATLAS_REVISION=main

4

@omar @brian.smith just flagging this post - could you take a look and see if anything in documentation needs to be updated? (I haven’t read it closely)

5

To clarify the different ways to use ATLAS_REVISON:

  • release/ulmo.1
    • This is the default for someone running ulmo.1 in Tutor
    • It comes from {{ OPENEDX_COMMON_VERSION }}
    • It is frozen in time (a git tag as opposed to a git branch on the openedx-translations repo)
      • This is done to enable reproducible builds.
  • release/ulmo
    • This is a git branch on the openedx-translations repo
    • It will pull the latest translations for the source strings that exist in the ulmo named release.
  • main
    • This is also a git branch on the openedx-translations repo
    • This will pull the latest translations for the source strings that exist in the main/master branches of the repos to be included in the next named Open edX release

While it is quite likely that pulling from main will work for ulmo, it is also possible for strings that exist in ulmo to get removed in main, leading to gaps.

I recommend setting ATLAS_REVISION to release/ulmo instead.

Docs that could be updated:

The openedx-translations README still mentions the branch naming format we used before teak (open-release/<release-name>.master).

The Tutor documentation for “Getting and customizing Translations” could probably benefit from mentioning setting release/<release-name> (as opposed to release/<release-name>.x) as the recommended way to pull updated translations for any given named release.

6

PR to update the readme - docs: Change release branch naming conventions by sarina · Pull Request #69795 · openedx/openedx-translations · GitHub

PR to update Tutor docs - docs: Use branch, not tags, for translations by sarina · Pull Request #1368 · overhangio/tutor · GitHub

7

The tradeoff is the operator either gets reproducible builds that will always work (or break) by setting a specific tag. Or use release/ulmo and expects some builds to fail due to translation updates.

By default, it’s always set to a tag release/ulmo.1 to ensure reproducible builds for the unsuspecting operator. In practice, everyone needs to use release/ulmo instead.

This is intentional and sorry you had to ask, if you’ve got a minute kindly consider updating the docs so others don’t have to :slight_smile:

8

@omar I made the changes and had already posted the PR. It looks like the Tutor maintainer just merged it so I hope I got it right :sweat_smile: