tryton/docs/custom-repository-operations.md

# 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 Tryton server owns the `es_DO` language and declares `es_419` as its
fallback. Dominican translations live beside each package in its regular
`locale/es_DO.po` catalog. Weblate writes only terms which differ from the
Latin American fallback, so there is no duplicated localization module and no
need to copy every `es_419.po` catalog.

Weblate must push through a dedicated `translation/weblate-8.0` branch and a
reviewed pull request to `integration/8.0`; it must never push directly to a
protected branch. Gitea sends push notifications to
`https://translate.tryton.org.do/hooks/gitea/` so Weblate can pull source
changes promptly. CI validates every PO catalog and the server package before
the pull request can be merged.

When a catalog changes, update the database with:

```console
trytond-admin -d DATABASE --all --activate-dependencies
```

Activate Spanish, Spanish (Latin American), and Spanish (Dominican Republic)
as translatable languages in that order. Then update the activated modules to
import any new `es_DO.po` catalogs delivered by Weblate.

## 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.