From 80ac099434730e2380e0aa67351f7ae793cbb01e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jose=CC=81=20Arturo=20Garci=CC=81a?=
 <jose.arturo.garcia@gmail.com>
Date: Tue, 13 Oct 2026 19:07:53 -0400
Subject: [PATCH] docs: document private mirror and recovery operations

---
 docs/custom-repository-operations.md | 76 ++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/custom-repository-operations.md

diff --git a/docs/custom-repository-operations.md b/docs/custom-repository-operations.md
new file mode 100644
index 0000000000..c0c047de5b
--- /dev/null
+++ b/docs/custom-repository-operations.md
@@ -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.