docs(adr): propose git history strategy for folding repos into ui-kit

[alexprudhomme]

Problem

When folding @coveo/relay and coveo.analytics.js into ui-kit, each source repo carries hundreds of commits (relay ~300+). We need a documented, agreed strategy for what happens to that history in ui-kit — balancing a clean main against access to git blame, while respecting ui-kit's squash-only merge policy.

Solution

Adds a repo-level ADR at docs/adr/0001-git-history-strategy-for-folded-repos.md (establishing a cross-cutting docs/adr/ location; existing ADRs are package-scoped).

The ADR (status: Proposed) lays out three options and, following team review, selects Option B (KISS): squash-merge the integration PR for a clean main, and preserve history by keeping the original repos archived (read-only) on GitHub rather than importing it into ui-kit.

• B — Squash + archived old repo (selected): clean main, no branch-protection exception, no new long-term git concepts; deep git blame for the folded code lives in the archived repos. Deep blame on these libs is rare, so this is good enough.
• A — Squash + archive ref + graft: clean main with in-repo opt-in blame via a published git replace graft — but adds a new long-term archive/* ref + graft; for daily work it's barely different from B, so the extra machinery isn't justified.
• C — Merge commit: automatic blame but 300+ commits on main permanently and needs a branch-protection exception.

Appendix — the graft approach (Option A), for the curious

A public throwaway repo reproduces the Option A graft technique we evaluated (kept here as reference, even though we're going with B):

Repo: https://github.com/alexprudhomme/uikit-git-history-graft-demo

git clone https://github.com/alexprudhomme/uikit-git-history-graft-demo.git
cd uikit-git-history-graft-demo

git log --oneline | head                                   # main = 1 squash commit (B and A both look like this)
git blame packages/relay/src/emit.ts                       # blame stops at the squash commit (this is Option B)

# Option A only: opt into deep blame with a published graft
git fetch origin 'refs/replace/*:refs/replace/*'
git blame packages/relay/src/emit.ts                       # now shows real authors (Edsger, ...)
git log --oneline --follow -- packages/relay/src/emit.ts   # full file history
git replace -d "$(git replace -l)"                         # deactivate

Related: RFC – Unify JS libraries under UI-KIT, DRAFT Technical implementation steps.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 810d4f2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[svcsnykcoveo]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[Copilot]

Pull request overview

Adds a repo-level Architecture Decision Record (ADR) documenting the proposed Git history strategy for folding external repos (e.g., @coveo/relay, coveo.analytics.js) into ui-kit while keeping main clean under the squash-only merge policy.

Changes:

• Introduces a new ADR under docs/adr/ to centralize cross-cutting decisions at the repo level.
• Compares three history-preservation strategies and recommends Option A (squash + permanent archive/<lib>-history branch + published git replace graft).
• Documents operational rollout steps (migration, publishing archive refs and replace refs, CI impact, rollback).

[pkg-pr-new]

• @coveo/pkg-new-template

@coveo/atomic

npm i https://pkg.pr.new/@coveo/atomic@7910

@coveo/atomic-hosted-page

npm i https://pkg.pr.new/@coveo/atomic-hosted-page@7910

@coveo/atomic-legacy

npm i https://pkg.pr.new/@coveo/atomic-legacy@7910

@coveo/atomic-react

npm i https://pkg.pr.new/@coveo/atomic-react@7910

@coveo/auth

npm i https://pkg.pr.new/@coveo/auth@7910

@coveo/bueno

npm i https://pkg.pr.new/@coveo/bueno@7910

@coveo/create-atomic

npm i https://pkg.pr.new/@coveo/create-atomic@7910

@coveo/create-atomic-component

npm i https://pkg.pr.new/@coveo/create-atomic-component@7910

@coveo/create-atomic-component-project

npm i https://pkg.pr.new/@coveo/create-atomic-component-project@7910

@coveo/create-atomic-result-component

npm i https://pkg.pr.new/@coveo/create-atomic-result-component@7910

@coveo/create-atomic-rollup-plugin

npm i https://pkg.pr.new/@coveo/create-atomic-rollup-plugin@7910

@coveo/headless

npm i https://pkg.pr.new/@coveo/headless@7910

@coveo/headless-react

npm i https://pkg.pr.new/@coveo/headless-react@7910

@coveo/shopify

npm i https://pkg.pr.new/@coveo/shopify@7910

commit: 810d4f2

[louis-bompart]

I am wondering whether enough git blame occured in the last couple of years be it on Relay or CAJS to be worth the hassle of going any further than B.
My issue with A is that it adds a new "snowflake" concept with the archive branchs, that may get lost overtime.

IMO, we might want to go with a KISS approach here and hence select B.