docs: document private mirror and recovery operations

2026-10-13 19:07:53 -04:00
parent 9a16786c2d
commit 80ac099434
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Tryton private mirror and customization operations
+
+## Repository roles
+
+- `tryton-do/tryton-mirror` is a private pull mirror of
+  `https://github.com/tryton/tryton`. Never develop or create custom references
+  in this repository.
+- `tryton-do/tryton` preserves the upstream history and contains reviewed local
+  changes.
+
+## Branches
+
+- `8.0`: protected production branch for the 8.0 LTS series.
+- `integration/8.0`: protected target for automated upstream proposals.
+- `feature/*`: short-lived application changes.
+- `translation/*`: short-lived translation changes.
+- `8.2`: evaluation branch for the current non-LTS series; it is not deployed.
+- `automation/upstream-8.0`: bot-managed, fast-forward-only proposal branch.
+
+Production changes flow through `translation/*` or `feature/*` into
+`integration/8.0`, then through a second reviewed pull request into `8.0`.
+Direct pushes and force pushes to the protected branches are forbidden.
+
+## Remotes for developers
+
+```console
+git remote add origin https://code.unpaismejor.org.do/tryton-do/tryton.git
+git remote add mirror https://code.unpaismejor.org.do/tryton-do/tryton-mirror.git
+git remote add upstream https://github.com/tryton/tryton.git
+```
+
+Gitea Actions uses its short-lived, repository-scoped `GITEA_TOKEN`. The
+organization grants that token read-only cross-repository access to
+`tryton-mirror`; no long-lived personal access token is stored. The GitHub
+`upstream` remote is for diagnostics and disaster recovery.
+
+## Translation workflow
+
+The `translation_do` module owns the `es_DO` language and declares `es_419` as
+its fallback. Add Dominican terms to
+`modules/translation_do/locale/override/es_DO.po`; do not edit official PO
+files. Use a `translation/<topic>` branch, validate the catalogs, and open a
+pull request to `integration/8.0`.
+
+When a catalog changes, update the database with:
+
+```console
+trytond-admin -d DATABASE --all --activate-dependencies -u translation_do
+```
+
+Activate Spanish, Spanish (Latin American), and Spanish (Dominican Republic)
+as translatable languages in that order.
+
+## Resolving an upstream conflict
+
+1. Fetch `mirror/8.0` and the target branch.
+2. Create a new `feature/upstream-conflict-YYYYMMDD` branch from
+   `integration/8.0`.
+3. Merge `mirror/8.0` without rebasing published custom commits.
+4. Resolve only the reported paths, run CI locally, and push the branch.
+5. Open a reviewed pull request into `integration/8.0`.
+6. Close the automation conflict issue only after the pull request is merged.
+
+Never force-push an integration, production, or automation branch.
+
+## Recovery
+
+If the native mirror stops updating, keep `tryton` unchanged, inspect the
+mirror synchronization error, and trigger a manual mirror update. If the
+mirror repository is unrecoverable, create a new private pull mirror under a
+temporary name, verify branches and tags against GitHub, and only then update
+the workflow repository URL and cross-repository allowlist. Do not delete the
+previous mirror until the replacement is verified.
+
+If an integration proposal is wrong, close its pull request and delete only
+its `automation/*` branch. Protected branches and their history remain intact.