chore: release docs and script updates | FC-12

Makefile

@@ -1,12 +1,9 @@
-.PHONY: piptools upgrade fix_transifex_resource_names translations_scripts_requirements validate_translation_files \
-sync_translations sync_translations_github_workflow rerun_tests_for_transifex_bot_pull_requests
-
-
-# Default languages for the sync_translations.py file
-# This list represents the supported languages by the Open edX community as stated by the Translators Working Group:
-#   - https://openedx.atlassian.net/wiki/spaces/COMM/pages/3157524644/Translation+Working+Group#The-following-is-a-table-of-the-latest-list-of-languages-supported--by-the-Translation-Working-Group
-export TX_LANGUAGES := ar,da,de_DE,el,es_419,es_ES,fr_CA,hi,he,id,it_IT,pt_BR,pt_PT,ru,th,tr_TR,uk,zh_CN
+.PHONY: piptools upgrade fix_transifex_resource_names translations_scripts_requirements \
+validate_translation_files test_requirements test fix_transifex_resource_names_dry_run \
+retry_merge_transifex_bot_pull_requests
 
+# Default project to work on. Override to release project e.g. `openedx-translations-redwood` when cutting a release.
+export TRANSIFEX_PROJECT_SLUG := openedx-translations
 
 piptools:
 	pip install -q -r requirements/pip_tools.txt
@@ -24,10 +21,10 @@ upgrade: piptools  ## update the requirements/*.txt files with the latest packag
 translations_scripts_requirements:  ## Installs the requirements file
 	pip install -q -r requirements/translations.txt
 
-fix_transifex_resource_names:  ## Runs the script
+fix_transifex_resource_names:  ## Runs the script on the TRANSIFEX_PROJECT_SLUG project
 	python scripts/fix_transifex_resource_names.py
 
-fix_transifex_resource_names_dry_run:  ## Runs the script in --dry-run mode
+fix_transifex_resource_names_dry_run:  ## Runs the script in --dry-run mode on the TRANSIFEX_PROJECT_SLUG project
 	python scripts/fix_transifex_resource_names.py --dry-run
 
 
@@ -40,12 +37,6 @@ test:  ## Run scripts tests
 validate_translation_files:  ## Run basic validation to ensure files are compilable
 	python scripts/validate_translation_files.py
 
-sync_translations:  ## Syncs from the old projects to the new openedx-translations project
-	python scripts/sync_translations.py $(SYNC_ARGS)
-
-sync_translations_github_workflow:  ## Run with parameters from .github/workflows/sync-translations.yml
-	make SYNC_ARGS="--simulate-github-workflow $(SYNC_ARGS)" sync_translations
-
 export MAX_PULL_REQUESTS_TO_RESTART := 1000
 retry_merge_transifex_bot_pull_requests:  ## Fix Transifex bot stuck and unmerged pull requests.
 	bash scripts/retry_merge_transifex_bot_pull_requests.sh

README.rst

@@ -1,7 +1,7 @@
 openedx-translations
 ####################
 
-The openedx-translations repository contains translation files from Open edX repositories
+This openedx-translations repository contains translation files from Open edX repositories
 to be kept in sync with Transifex. To accomplish this task, a GitHub Action in
 ``.github/workflows/`` named ``extract-translation-source-files.yml`` regularly extracts
 English translation source files form Open edX repositories containing code and adds them
@@ -11,20 +11,58 @@ into this repository. The translation files in this repository can then be acces
 using the `openedx-atlas`_ CLI tool to download specific directories of translation files
 from openedx-translations.
 
-Current State
-*************
+This repository implements the `OEP-58`_ proposal.
 
-This repository is currently under active development with limited use.
-The GitHub Action
-``extract-translation-source-files.yml`` generates English translation source
-files for the configured repositories. These translation source files are the only
-ones uploaded to the Transifex project openedx-translations. The English translation
-source files have only been translated into one language: French Canadian (fr_CA). The
-`openedx-atlas`_ CLI tool can only be used to pull translation files from the credentials
-directory in openedx-translations.
+Main and Release branches
+*************************
+
+This repository has a main branch in addition to a dedicated branch for every
+release. As of May 10th, 2024 the following are the release branches:
+
+``main`` branch
+===============
+
+This branch is used for the latest version of Open edX such as
+`Tutor nightly`_, `edx-platform "master" branch`_ and others.
+
+To translate the latest versions the `open-edx/openedx-translations`_ Transifex
+project should be used.
+
+
+``open-release/<release-name>.master`` branch
+=============================================
+
+This branch is used for the latest version of the Open edX Release, which will
+be a version of Tutor and corresponding branches in tagged repos. For example,
+for the Redwood release (June 2024), the branches were:
+`Tutor Redwood v18`_, `edx-platform "open-release/redwood.master" branch`_
+and others.
+
+To update translations for a named release, find the corresponding named release project in the `Open edX Transifex project <https://app.transifex.com/open-edx/>`_  by searching for the release name (for example, Redwood) in the search box. 
+
+Tools for repository maintainers
+********************************
+
+This repository contains both `GitHub Actions workflows`_ and
+`Makefile programs`_ to automate and assist maintainers chores including:
+
+Fix resource names in Transifex
+===============================
+
+The GitHub Transifex App integeration puts an inconvenient names for resources like ``translations..frontend-app-something..src-i18n-transifex-input--main``
+instead of ``frontend-app-something``.
+
+Running this command should be safe and can be ran multiple times on
+both the main ``openedx-translations`` project or on release projects
+by setting the ``TRANSIFEX_PROJECT_SLUG`` make variable as shown below::
+
+    # Dry run the name fix
+    make TRANSIFEX_PROJECT_SLUG='openedx-translations-zebrawood' fix_transifex_resource_names_dry_run
+    # If runs without errors, run the actual command:
+    make TRANSIFEX_PROJECT_SLUG='openedx-translations-zebrawood' fix_transifex_resource_names
 
 Translation validation
-**********************
+======================
 
 This repository validates translations with the GNU gettext ``msgfmt`` tool.
 
@@ -38,6 +76,9 @@ The validation can be run locally with the following command:
 The validation errors is also posted as a comment on the update translation
 pull requests.
 
+Retry merging Transifex pull requests
+=====================================
+
 If GitHub Actions has an outage or any other issues there will be a backlog
 of stale unmerged Transifex bot pull requests. To re-run tests and merge the
 pull requests, run the following command:
@@ -46,31 +87,19 @@ pull requests, run the following command:
 
     make retry_merge_transifex_bot_pull_requests
 
-
-Translations sync from old Transifex projects
-*********************************************
-
-This repository allows for syncing translations old
-`open-edx/edx-platform`_ and `open-edx/xblocks`_ Transifex projects into
-the new `open-edx/openedx-translations`_ Transifex project. This is done by
-trigger the `sync_translations.yml workflow on GitHub`_.
-
-Alternatively, you can run the following command to trigger the workflow:
-
-.. code-block:: bash
-
-    # Run with parameters from .github/workflows/sync-translations.yml
-    make sync_translations_github_workflow
-
-
-For more information, please see the pull request for `OEP-58`_.
-
-
 .. _OEP-58: https://github.com/openedx/open-edx-proposals/pull/367
 .. _openedx-atlas: https://github.com/openedx/openedx-atlas
 
 .. _sync_translations.yml workflow on GitHub: https://github.com/openedx/openedx-translations/actions/workflows/sync-translations.yml
 
-.. _open-edx/edx-platform: https://app.transifex.com/open-edx/edx-platform/dashboard/
-.. _open-edx/xblocks: https://app.transifex.com/open-edx/xblocks/dashboard/
 .. _open-edx/openedx-translations: https://app.transifex.com/open-edx/openedx-translations/dashboard/
+.. _open-edx/openedx-translations-redwood: https://app.transifex.com/open-edx/openedx-translations-redwood/dashboard/
+
+
+.. _Tutor nightly: https://docs.tutor.edly.io/tutorials/nightly.html
+.. _edx-platform "master" branch: https://github.com/openedx/edx-platform
+.. _Tutor Redwood v18: https://docs.tutor.edly.io/
+.. _edx-platform "open-release/redwood.master" branch: https://github.com/openedx/edx-platform/tree/open-release/redwood.master
+
+.. _GitHub Actions workflows: https://github.com/openedx/openedx-translations/tree/main/.github/workflows
+.. _Makefile programs: https://github.com/openedx/openedx-translations/blob/main/Makefile