docs: add 0003-release-management.rst decision | FC-0012

[OmarIthawi]

Problem

Tutor operators needs to set ATLAS_REVISION with explicit values to invalidate cache and create reproducible builds.

Solution

Set up automated tagging, release branches and fork the Transifex projects.

Preview the decision doc

• 0003-release-management.rst

References

This pull request is part of the FC-0012 project which implements the Translation Infrastructure update OEP-58.

[openedx-webhooks]

Thanks for the pull request, @OmarIthawi! Please note that it may take us up to several weeks or months to complete a review and merge your PR.

Feel free to add as much of the following information to the ticket as you can:

• supporting documentation
• Open edX discussion forum threads
• timeline information ("this must be merged by XX date", and why that is)
• partner information ("this is a course on edx.org")
• any other information that can help Product understand the context for the PR

All technical communication about the code itself will be done via the GitHub pull request interface. As a reminder, our process documentation is here.

Please let us know once your PR is ready for our review and all tests are green.

[regisb]

I don't understand the use of daily tags. The release branches could be updated daily, but there is no need for tags between minor releases (release/redwood.x tags). Instead, I suggest that the openedx-translations repo be updated daily, and tags created automatically during the release process using an openedx.yaml file.

Pulling in @nedbat (as openedx.taml expert) and @cmltaWt0 (as release manager) for insights.

[OmarIthawi]

Thanks @regisb for the feedback.

The release branches could be updated daily, but there is no need for tags between minor releases (release/redwood.x tags).

The release branches are updated in near real-time whenever Transifex translations is updated. We don't control the timing. GitHub Transifex app does.

This creates a problem in two ways:

• If the operator updates Transifex translations and wants to update the build, they'll have to rebuild the images without cache to ensure latest translations are pulled.
• If the operator needs to rebuild the same image, it'll rebuild with newer (different) translations at random time depending on the cache expiration.

This is a typical "cache invalidation is hard".

I don't understand the use of daily tags.

It's the first idea came to my mind to address the cache invalidation challenge. I'd love to hear other's suggestions though.

The daily tags provides a solution to both problems:

• Specify a point-in-time for release translations to ensure reproducible builds.
• If an update is needed, use a more recent date.

I thought about using a similar strategy to Tutor MFE get_github_refs_path, but I realize it has been removed in Quince.

... and tags created automatically during the release process using an openedx.yaml file.

I don't understand how this would be done. I might need to read more about the openedx.yaml OEPs.

[regisb]

You should assume that users don't ever install Open edX from release branches -- only from release tags. This is how it's done in Tutor, because (as you mentioned) reproducible builds are absolutely essential.

I don't understand how this would be done. I might need to read more about the openedx.yaml OEPs.

The tl;dr is that every two months or so, the release manager runs a script that tags all repos that contain a proper "openedx.yaml" file. This is how we produce the open-release/quince.1, open-release/quince.2, etc. tags. The tags are applied to the tip of the open-release/quince.master branch. For Redwood, branch naming will change: release/redwood.X tags will be applied to the tip of the release/redwood branch.

[brian-smith-tcril]

I'm not in favor of daily tags, I feel like it would just make it harder to find the tags people are looking for.

If we want to support pulling translations from a specific point in time between minor releases, we could update atlas to support pulling by sha.

So this would mean:

• When a new major release happens we create a new release branch and a new release tag.
• As translation updates happen for that release, the branch is updated.
• When a new minor release happens, we create a new release tag on the release branch.

I believe this should satisfy the reproducible build requirement.

[OmarIthawi]

@brian-smith-tcril and @regisb thanks for the feedback. I'll update the proposal to make it more aligned with OEP-10 which should address both of your points and update this repo's openedx.yml.

If we want to support pulling translations from a specific point in time between minor releases, we could update atlas to support pulling by sha.

I agree with you. Do you think it's worth opening an issue for in https://github.com/openedx/openedx-atlas/issues/?

[OmarIthawi]

@regisb @brian-smith-tcril I've just caught up with the latest decisions and I think this pull request should be closed and the proposal needs to be dismissed in favor of standardized OEP-55 and catalog-file.yaml tagging.

Thanks for your feedback.

[brian-smith-tcril]

I agree with you. Do you think it's worth opening an issue for in https://github.com/openedx/openedx-atlas/issues/?

@OmarIthawi The idea is definitely worth documenting, and an issue on the atlas repo sounds like the perfect place for that. I don't know if there is demand for that functionality, but if/when someone presents a use case that requires pulling by sha someone can pick up that issue and make a PR.

[OmarIthawi]

Thanks again @regisb and @brian-smith-tcril. I'm closing this pull request because we ended up rejecting the decision and standardizing this repository with OEP-10.

The atlas pull --revision feature request has been created:

• feat: support pulling by a specific commit or a date  openedx-atlas#48

[openedx-webhooks]

@OmarIthawi Even though your pull request wasn’t merged, please take a moment to answer a two question survey so we can improve your experience in the future.