Skip to content

docs(operations): document the RD deployment branch and its upstream freeze - #616

Open
mrivas00 wants to merge 4 commits into
feat/mati/rd-activity-catalogfrom
docs/mati/rd-branch-freeze
Open

docs(operations): document the RD deployment branch and its upstream freeze#616
mrivas00 wants to merge 4 commits into
feat/mati/rd-activity-catalogfrom
docs/mati/rd-branch-freeze

Conversation

@mrivas00

@mrivas00 mrivas00 commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

Why

rd/integration is a long-lived branch that never merges back into Huella Latam, and nothing in the repository says so. Anyone who finds it — including whoever maintains it after this stack lands — needs to know that a routine rebase onto main is the wrong move, and why.

Docs-only · base feat/mati/rd-activity-catalog (PR 6).

What

docs/operations/rd-deployment-branch.md, linked from the operations index:

  • what the branch carries (country identity, the national activity catalog, Ley 187-17 tiers, the territorial hierarchy of Ley 345-22, Dominican terminology and factors) and why it is edited in place rather than parameterized per country;
  • the upstream policy: only security fixes are cherry-picked, no periodic rebase, no scheduled merge from main — upstream edits to tools/seed/src/data/base/*.json conflict with the Dominican catalogs indefinitely, so a routine rebase means re-resolving the whole catalog every sync with a real risk of silently reintroducing demo data into a national registry;
  • reseeding is destructive: seed.ts skips when country.count() > 0, so replacing a catalog needs pnpm db:reset and loses every inventory captured against the previous one. Coordinate the window with MMARN.
  • what should go the other way: open dumps, cable cars, isolated grids and ride-hailing describe most of the region and are worth upstreaming as a separate change against main.

Review notes

This is task 10.3 of the change. Splitting it out of PR 6 keeps that PR's diff to the catalog.

The one thing worth a second opinion is the escalation path for non-security upstream work (item 2 in the policy): cherry-pick deliberately, with an owner, keeping the Dominican side of every conflicting file. If the intended process differs — say, a quarterly review of main instead of purely on-demand — that paragraph is the place to correct it.

Verification

pnpm format clean. No code touched.

@mrivas00 mrivas00 added priority: high High priority type: docs documentation only area: docs docs/ and root docs labels Aug 21, 2026
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch from a7ec780 to 47929a9 Compare August 24, 2026 12:25
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch 2 times, most recently from 24da206 to 90dedd8 Compare August 24, 2026 15:10
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch 2 times, most recently from e55a856 to bf84bb0 Compare August 24, 2026 17:58
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch 2 times, most recently from a46f61a to 7bfcbc8 Compare August 24, 2026 19:11
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch from e9955bc to b83456b Compare August 25, 2026 18:50
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch from 7bfcbc8 to 3f0cade Compare August 25, 2026 18:50
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch from b83456b to 9b4acdb Compare August 26, 2026 12:12
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch from 82adb94 to f65c708 Compare August 26, 2026 12:12
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch from 9b4acdb to eab5475 Compare August 26, 2026 12:36
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch from f65c708 to 719052a Compare August 26, 2026 12:36
…freeze

The Dominican deployment runs rd/integration, not main, and the branch
never merges back. Records what it carries, that only security fixes are
cherry-picked (no periodic rebase — upstream seed edits conflict with the
Dominican catalogs indefinitely), and that replacing a catalog needs a
full database reset that discards captured inventories.
Section 1 is external, PRs 7 and 8 wait on MMARN and the ONE, every
database-dependent verification task went unrun for want of a Postgres,
the catalog shipped 18 sectors instead of 17, and CI does not trigger for
a PR based outside main.
The branch carries the hierarchy of Ley 345-22, not a catalog obtained from
the ONE — whose role here is corroborating the counts. Whoever maintains
this branch needs to know which source to re-check the catalog against.
The upstream policy said cherry-pick, never rebase. That framing was wrong for
this stack: anything landing on `rd/integration` moves the root, and moving
the root rebases all ten branches anyway — so a cherry-pick costs a chain
rebase plus its own conflicts, not less.

Records the 2026-08-26 sync onto `34f66c3b` and the two defects it caught,
both of which this branch would otherwise have shipped: industrial-process
factors understated a thousandfold for steel and zinc, and `Otro` sorting
ahead of `SENI` in the Scope 2 dropdown because both capture endpoints order
dimension values alphabetically.

Adds the rule the second one teaches: verify a `methodologies.json` merge by
diffing factors against main programmatically, not by reading it.
@mrivas00
mrivas00 force-pushed the feat/mati/rd-activity-catalog branch from eab5475 to 75b74c7 Compare August 26, 2026 20:21
@mrivas00
mrivas00 force-pushed the docs/mati/rd-branch-freeze branch from 719052a to c42391b Compare August 26, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs docs/ and root docs priority: high High priority type: docs documentation only

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant