Skip to content

docs(contributing): point contributors to the canonical fork - #92

Merged
Amplify-Logic merged 1 commit into
mainfrom
fm/fm-repo-topology-apply-r2
Aug 23, 2026
Merged

docs(contributing): point contributors to the canonical fork#92
Amplify-Logic merged 1 commit into
mainfrom
fm/fm-repo-topology-apply-r2

Conversation

@Amplify-Logic

Copy link
Copy Markdown
Owner

Intent

Apply the decided repository topology corrections in this public repo. Canonical home is the fork Amplify-Logic/firstmate (origin); the original author's repo kunchenguid/firstmate is upstream. Three bounded surfaces were named, each to be investigated with git grep before editing, and any surface already correct must be documented in the commit message body rather than changed: (1) CONTRIBUTING.md still referenced the pre-fork repository as the project's home - fix references so contributors target Amplify-Logic/firstmate while crediting upstream where genuinely meant as the upstream project; (2) validation-pipeline (no-mistakes-related) configuration tracked in this repo naming the pre-fork repository as push/PR target - investigation found the only tracked config is .no-mistakes.yaml which carries no push/PR target, so this surface was already correct and no change was made; (3) PR compliance marker under .github/ - investigation found the marker in no-mistakes-required.yml references the no-mistakes TOOL project (kunchenguid/no-mistakes), not the pre-fork firstmate repo, and is byte-identical to the signature the installed pipeline writes into this fork's merged PR bodies (verified against PR #91), so changing it would break the compliance check and it was deliberately left unchanged. The one code change: CONTRIBUTING.md step 1 now targets git@github.com:Amplify-Logic/firstmate.git and adds a deliberate upstream-credit line naming kunchenguid/firstmate as the upstream this fork descends from, matching fork-surface.conf's upstream_remote. Acceptance: git grep for the pre-fork repository name over tracked files returns only deliberate upstream-credit references (fork-surface.conf upstream_remote, the new CONTRIBUTING credit line, an upstream-recorded verification transcript in docs/gitlab-merge-watch.md, synthetic test fixtures), no home-repo claims; CI stays green and workflows still run; one sentence per line in touched docs, plain dashes.

What Changed

  • Updated the contributor setup instructions to use Amplify-Logic/firstmate as the repository origin.
  • Added explicit credit to kunchenguid/firstmate as the upstream project from which this fork descends.

Risk Assessment

✅ Low: The change is a narrow documentation-only correction that matches the authoritative repository-topology intent, preserves deliberate upstream references, and introduces no material risk.

Testing

Both focused automated contracts passed, and the CLI evidence demonstrates the corrected contributor topology end to end, including a reachable canonical repository, deliberate upstream-only references, manifest validity, and documentation style; the worktree remained clean, but no remote CI run exists for the target commit.

Evidence: Contributor repository-topology transcript
Contributor-facing repository topology verification
Target commit: a92b6f171517d0fe67c5feccf09da27c41c9bd82

Published workflow excerpt:

## Workflow

1. Fork [`Amplify-Logic/firstmate`](https://github.com/Amplify-Logic/firstmate), then clone the parent repo or set your local `origin` back to the parent (`git@github.com:Amplify-Logic/firstmate.git`).
   That fork is this project's canonical home; [`kunchenguid/firstmate`](https://github.com/kunchenguid/firstmate) is the upstream it descends from, declared as `upstream_remote` in `fork-surface.conf`.
2. Create a branch and make your changes.
3. Initialize the gate with your fork as the push target: `no-mistakes init --fork-url git@github.com:<you>/firstmate.git` (firstmate expects **no-mistakes v1.31.2+**; without a fork, plain `no-mistakes init` still works for maintainers with push access).
4. Commit your changes.

Remote produced by following step 1:
origin	git@github.com:Amplify-Logic/firstmate.git (fetch)
origin	git@github.com:Amplify-Logic/firstmate.git (push)

Canonical GitHub repository HEAD lookup:
3e81ed5f5fa3cce53ce3876198ff1458900802cc	HEAD

Declared upstream in fork-surface.conf:
upstream_remote = https://github.com/kunchenguid/firstmate

Tracked non-fixture references to the original repository:
CONTRIBUTING.md:19:   That fork is this project's canonical home; [`kunchenguid/firstmate`](https://github.com/kunchenguid/firstmate) is the upstream it descends from, declared as `upstream_remote` in `fork-surface.conf`.
docs/gitlab-merge-watch.md:161:$ PATH="$noglab" fm-pr-check.sh e6 https://github.com/kunchenguid/firstmate/pull/750
fork-surface.conf:6:upstream_remote = https://github.com/kunchenguid/firstmate

Fork-surface manifest gate:
FORK_SURFACE OK capabilities=53 owned_paths=166

Touched-document style checks:
PASS: added lines contain no Unicode en/em dashes
PASS: the two added sentences occupy two separate physical lines
- Outcome: ⚠️ 1 warning across 1 run (7m10s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 1 warning
  • ⚠️ No GitHub Actions runs exist for target commit a92b6f1, so remote CI cannot yet be demonstrated green. Push or open a PR for this commit to run the workflows; the focused local workflow contracts pass.
  • Inspected git diff 3e81ed5f5fa3cce53ce3876198ff1458900802cc..a92b6f171517d0fe67c5feccf09da27c41c9bd82 and the target commit message.
  • Ran bin/fm-test-run.sh tests/fm-fork-surface.test.sh.
  • Ran bin/fm-test-run.sh tests/no-mistakes-required-workflow.test.sh.
  • Simulated the documented contributor workflow by extracting the SSH URL, configuring a fresh repository’s origin, checking git remote -v, and resolving the canonical repository with git ls-remote.
  • Ran git grep -n &#39;kunchenguid/firstmate&#39; -- &#39;:!tests/*&#39;, bin/fm-fork-surface.sh check, touched-line dash/sentence checks, and git diff --check.
  • Queried GitHub with gh-axi run list --commit a92b6f171517d0fe67c5feccf09da27c41c9bd82 --limit 20 --fields headSha,number,updatedAt,url; no runs were present.
  • Checked final cleanliness with git status --short --branch.
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Surface 1 (CONTRIBUTING upstream pointer): fixed. Step 1 of the workflow
still told contributors to set origin to the pre-fork
git@github.com:kunchenguid/firstmate.git. It now targets
git@github.com:Amplify-Logic/firstmate.git and credits kunchenguid/firstmate
explicitly as the upstream this fork descends from, matching
fork-surface.conf's upstream_remote declaration.

Surface 2 (validation-pipeline fork target): already correct, no change.
The only tracked no-mistakes configuration is .no-mistakes.yaml, which
carries no push or PR target; the pipeline's push target lives in
gitignored local state. git grep over tracked files finds no
pipeline-target reference to the pre-fork repository.

Surface 3 (PR compliance marker): already correct, no change. The marker in
.github/workflows/no-mistakes-required.yml references the no-mistakes tool
project (kunchenguid/no-mistakes), not the pre-fork firstmate repository,
and is byte-identical to the signature the installed pipeline writes into
this fork's PR bodies (verified against merged PR #91's body). Changing it
would break the compliance check, and tests/no-mistakes-required-workflow.test.sh
asserts the marker contract.

Remaining tracked kunchenguid/firstmate references are deliberate: the new
upstream-credit line in CONTRIBUTING.md, fork-surface.conf's upstream_remote
declaration, an upstream-recorded verification transcript in
docs/gitlab-merge-watch.md, and synthetic test-fixture URLs.
@Amplify-Logic
Amplify-Logic merged commit 84e6297 into main Aug 23, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant