chore(release): add release-please plumbing + curated 0.1.0 baseline (#1137)

[piotrswierzy]

What & why

Installs the product release-line machinery — Axis 1 of ADR-029 (#1137) — without cutting a tag. release-please (root/single-package, node type) opens and maintains a chore: release X.Y.Z PR from the Conventional Commits the repo already writes. Nothing releases until a maintainer merges that Release PR.

Part of #1137 — the issue's remaining acceptance criterion (the actual first v0.1.0 git tag) is a deliberately deferred one-time manual step, so this PR does not auto-close it.

The 0.1.0 model (curated baseline, no tag now)

Per maintainer decision: a hand-curated first changelog + no tag yet. Because release-please auto-generates notes for whatever version it cuts, 0.1.0 is established as a baseline instead:

• CHANGELOG.md — hand-curated ## [0.1.0] listing every integration (PrestaShop, WooCommerce, Allegro, Erli, InPost, DPD Polska, Subiekt, KSeF, inFakt, AI router) with real adapter keys, plus the platform / /v1 API / core-workflow / frontend feature set — sourced from the repo's own README + architecture docs.
• .release-please-manifest.json = {".": "0.1.0"} — declares 0.1.0 as already-released, so release-please manages 0.2.0+ and never rewrites the curated section.
• release-please reads commits after bootstrap-sha (current main) for the next release.

How releasing works afterward

• v0.1.0 — a one-time manual tag of the bootstrap-sha commit + GitHub Release whenever you're ready (exact commands in RELEASING.md). No rush; nothing depends on it now.
• 0.2.0+ — fully automated: merge feat/fix PRs → release-please opens a 0.2.0 Release PR (prepended above the curated 0.1.0) → merging it tags v0.2.0 + creates the Release. No hand-tagging again.

Config (every field schema-verified)

release-type: node · bump-minor-pre-major: true + bump-patch-for-minor-pre-major: false (→ feat→minor, fix→patch, breaking→0.x minor, matching RELEASING.md) · include-component-in-tag: false (→ v0.1.0, not openlinker-v0.1.0).

Review fixes (#1339)

The /pr-review pass found three baseline-calibration issues, fixed in 10dff4f8:

• bootstrap-sha refreshed to the current main tip (e6298374) — the original value (333a39b1) had gone stale as fix(infakt): stop hardcoding payment_method, make it a per-connection setting #1309/feat(ksef): emit FA(3) Platnosc from connection payment config #1317/feat(invoicing): persist issuance-time line snapshot for safe KSeF corrections (#1297) #1329/fix(connections): widen CoreCapability with Invoicing, fix capability panel copy #1320/fix(shared): export ./worker subpath so worker + api health boot #1331 merged, which would have made the first post-merge run open a 0.2.0 Release PR double-crediting work the curated 0.1.0 already describes. ⚠️ If main advances again before this PR merges, re-bump bootstrap-sha in the same push that updates the branch.
• Bump-semantics wording aligned with the config in CHANGELOG.md + RELEASING.md § Versioning policy (pre-1.0: minor = features + breaking, patch = fixes); RELEASING.md now cites the config keys so they can't drift apart silently. PUBLIC_API.md's "patch = additive" convention is intentionally untouched — that's the separate npm-package axis (Changesets, deferred).
• v0.1.0 tag recipe fixed to tag the bootstrap-sha commit explicitly (not the main tip at tag time), with a warning that a v0.1.0 Release moves release-please's parse boundary.
• Bonus: release-please-action pinned by commit SHA (v4.4.1) — the workflow holds contents + pull-requests write.

Also

• ci.yml — drops the stale develop branch ref (ADR-029 cleanup; the repo is trunk-based).
• Workflow runs on GitHub-hosted ubuntu-latest with the default GITHUB_TOKEN (contents + pull-requests: write only).

Why the commit type is chore(release):

Non-releasable on purpose. The squash-merge commit is the only thing on main after bootstrap-sha on first run — a feat:/fix: here would make release-please open a 0.2.0 PR immediately. chore keeps it dormant until real feature work lands.

Caveats (documented, not fixable from the repo)

• If the org sets the default Actions token to read-only, or disables "Allow GitHub Actions to create and approve pull requests," the Release PR won't open — needs an admin toggle in Settings → Actions → Workflow permissions.
• cd.yml deploy wiring + the PAT/App-token for the tag→CD trigger stay deferred (need deploy targets — ADR-029 sequences CD after the tag).

Verification

• pnpm lint + check:invariants ✅ (incl. check-repo-urls) · pnpm type-check ✅ · no source changed → unit tests unaffected · config JSON + workflow YAML validated.
• Post-fix: pnpm lint (full) + check:invariants re-run green at 10dff4f8.

Refs #1137
Closes #1339

🤖 Generated with Claude Code

[piotrswierzy]

PR Review: #1332 — release-please plumbing + curated 0.1.0 baseline

(Review submitted as COMMENT — GitHub doesn't allow approving one's own PR.)

Summary

Solid, well-documented implementation of ADR-029 Axis 1. The config is schema-referenced and the pre-1.0 bump semantics (bump-minor-pre-major: true + bump-patch-for-minor-pre-major: false) match what RELEASING.md promises. The workflow's permissions are minimal (contents + pull-requests: write), concurrency-guarded, and the GitHub-hosted-runner choice is justified in-file. Verified independently that every adapter key named in the curated CHANGELOG (allegro.publicapi.v1, erli.shopapi.v1, infakt.accounting.v1, inpost.shipx.v1, prestashop.webservice.v1, subiekt.invoicing.v1, woocommerce.restapi.v3, ksef.publicapi.v2) matches a real manifest in the repo. The RELEASING.md "cutting the first tag" section and the first-Release-PR sanity-check note are exactly the operational detail a future maintainer needs.

🟡 IMPORTANT — bootstrap-sha is stale; the "stays dormant" claim no longer holds

release-please-config.json pins bootstrap-sha: 333a39b1 (#1319), but main has since advanced by three releasable commits:

• b40902e9 feat(ksef): emit FA(3) Platnosc … (#1317)
• a41a96e4 fix(infakt): stop hardcoding payment_method … (#1309)
• 678041c0 feat(invoicing): persist issuance-time line snapshot … (#1329)

Two consequences on first run after merge:

1. release-please will immediately open a 0.2.0 Release PR containing those three commits — contradicting the PR's "keeps it dormant until real feature work lands" design (the chore(release): commit-type care is bypassed by the pre-existing feats).
2. Those commits' content is arguably already covered by the curated 0.1.0 baseline (it's a snapshot "as of now" describing KSeF issuance/clearance and the inFakt integration), so #1317/#1309/#1329 would be double-attributed — once implicitly in 0.1.0, again explicitly in the generated 0.2.0 notes.

Fix: immediately before merging, bump bootstrap-sha to the then-current main tip (today 678041c0). Since main keeps moving, treat this as a merge-time checklist item rather than a one-off edit — worth a sentence in the PR body/RELEASING.md so whoever merges knows to refresh it.

🟢 Optional

• The ci.yml develop cleanup is correct for a trunk-based repo and safely scoped.
• googleapis/release-please-action@v4 is tag-pinned, matching the repo's existing convention (actions/checkout@v4) — fine; SHA-pinning is the stricter option if supply-chain hardening ever becomes a goal.

Verdict

🔄 Ready after one fix — refresh bootstrap-sha to main's tip at merge time; everything else is mergeable as-is.

[piotrswierzy]

/pr-review — systematic review (self-authored PR, so posting as comment; cannot self-approve)

Verdict: 🔄 would-approve with changes — machinery is installed cleanly; three IMPORTANT fixes needed, all sharing one root: the time-sensitivity of the bootstrap-sha anchor.

🟡 IMPORTANT

1. release-please-config.json:6 — bootstrap-sha is already stale, defeating the dormancy claim. 333a39b1 is a valid ancestor of origin/main, but three releasable commits now sit after it (b40902e9 feat #1317, a41a96e4 fix #1309, 678041c0 feat #1329) — and this PR is behind main. On first post-merge run, release-please will immediately open a 0.2.0 Release PR crediting those KSeF/inFakt commits, which the curated 0.1.0 section already describes as baseline → double-crediting. Not catastrophic (nothing tags without a maintainer merge), but it falsifies the PR body's "only the squash commit sits after bootstrap-sha" claim. Fix: bump bootstrap-sha to the then-current main tip in the same push that updates the branch for merge — must be done at merge time, not earlier.

2. CHANGELOG.md:7-8 — the header's bump-semantics statement contradicts the shipped config. It says pre-1.0 "minor carries breaking changes, patch carries additive ones", but bump-patch-for-minor-pre-major: false means feat: bumps minor — so minor carries breaking and additive; only fix: lands on patch. RELEASING.md § Versioning policy carries the same internal contradiction (line ~36 vs ~39) — this PR copies the wrong half into a brand-new file. Fix: reword both to "minor carries features and breaking changes, patch carries fixes" (matches the config and the PR body's own stated mapping), or flip the config flag if minor-is-breaking-only was the real intent.

3. RELEASING.md:~76-81 — the manual v0.1.0 tag recipe tags whatever main is at tag time, silently shrinking the next release's commit window. bootstrap-sha is only release-please's fallback; once a v0.1.0 tag + Release exist, it parses from that tag's commit instead. git checkout main && git pull && git tag -a v0.1.0 tags the current tip — any feat:/fix: merged between bootstrap-sha and tag day drops out of the generated 0.2.0 changelog without appearing in the curated 0.1.0 notes. Fix: tag the bootstrap-sha commit explicitly (git tag -a v0.1.0 <bootstrap-sha>), or warn that tagging later moves the parse boundary and requires re-checking the pending Release PR.

🟢 SUGGESTIONS

• .github/workflows/release-please.yml:37 — pin googleapis/release-please-action by commit SHA (@<full-sha> # v4.x.y); the workflow holds contents: write + pull-requests: write, and mutable tags on third-party actions are the classic supply-chain seam.
• CHANGELOG.md:121 — the [0.1.0] reference link 404s until the manual tag lands (deliberate, self-healing); consider a note or omitting until then.

✅ Verified positives

• Workflow hygiene exactly right: push on main only; documented-minimum permissions; concurrency queues rather than kills mid-flight runs; GITHUB_TOKEN-won't-retrigger-CD caveat accurately documented in both places.
• All config keys are real, schema-valid release-please fields and semantically coherent; include-component-in-tag: false correctly yields v0.1.0.
• Manifest ↔ root package.json (openlinker@0.1.0) consistent, keeping /v1/health truthful.
• CHANGELOG accuracy is excellent — all nine adapter keys spot-checked against the local manifests match exactly, as do the role names, OL Dynamic Carrier, and ShippingProviderManagerPort claims.
• ci.yml cleanup is complete and safe: exactly three develop refs existed, all removed, nothing else references it.

[piotrswierzy]

The three pre-merge fixes from the review (stale bootstrap-sha, bump-semantics wording in CHANGELOG/RELEASING, tag recipe targeting the wrong commit) are now tracked in #1339 — including the merge-time sequencing constraint (bootstrap-sha must be refreshed in the same push that updates the branch, immediately before merging).

[piotrswierzy]

#1339 implemented and pushed as 10dff4f8 (branch also merged current main, tip e6298374):

• bootstrap-sha → e6298374 (current main tip; re-bump if main advances again before merge)
• CHANGELOG.md + RELEASING.md § Versioning policy reworded to match the config (minor = features + breaking, patch = fixes), with the config keys cited inline
• v0.1.0 recipe now tags the bootstrap-sha commit explicitly + warns about the parse-boundary effect
• release-please-action pinned by commit SHA (5c625bfb # v4.4.1)

pnpm lint + check:invariants green at the new head. PR body updated (Closes #1339). Ready to merge once CI confirms.