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 `es_DO` as a standalone language; its database record
does not declare `es_419` (or any other locale) as parent. Complete Dominican
translations live beside each package in its regular `locale/es_DO.po`
catalog. The initial catalogs were bootstrapped from `es_419`, but they are now
independent and Dominican terminology is maintained directly in them. There is
no duplicated localization module or runtime dependency on one.

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 (Dominican Republic) as a translatable language, then update
the activated modules to import any new `es_DO.po` catalogs delivered by
Weblate. Activating Spanish (Latin American) is not required for `es_DO`.

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