Skip to content

docs: add guide for keeping derived private repositories current - #10

Merged
Nickfost merged 16 commits into
mainfrom
docs/updating-guide
Jul 27, 2026
Merged

docs: add guide for keeping derived private repositories current#10
Nickfost merged 16 commits into
mainfrom
docs/updating-guide

Conversation

@Nickfost

Copy link
Copy Markdown
Member

Part of RandomDevelopment/ci-fleet#24.

What changed

New docs/UPDATING.md documenting, for repositories created from this template:

  • schema_version vs template version as distinct numbers;
  • versioned template releases and deliberate vendored updates;
  • the fact that GitHub template-created repositories retain no fork ancestry (with the explicit remote/tag update procedure);
  • validation pinned to immutable 40-hex releases;
  • Dependabot update PRs for SHA-pinned actions/reusable workflows;
  • explicit schema migration tooling;
  • optional ADOPTERS.md/registration issue forms, and no mandatory telemetry.

README file table links the new guide. Docs-only.

Covers schema_version vs template version, versioned template releases,
explicit migration tooling, validation pinned to immutable releases,
Dependabot update PRs for SHA-pinned actions, the absence of fork
ancestry in GitHub template-created repositories, optional ADOPTERS.md
or registration issue forms, and no mandatory telemetry.

Part of RandomDevelopment/ci-fleet#24.
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1af344cb8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
- unrelated-history merge flag or old..new tag range; no lone-tag
  cherry-pick
- clarify vendored validator does not resolve the engine pin; update
  vendored schema/validator with the matching release

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1f1dce800

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f7d76f13f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

Please review the exact current head 2f7d76f13fcb8fca9e84d5acc2464618204887f1, focusing on executable unrelated-history/tag update commands, strict-validation claims, preservation of private fleet.json, and secret-safe immutable pin guidance.

@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

Please review the exact current head b1f0bc0bb6df965050f3ce089283db9942febcbc, focusing on tag-namespace collision safety, preservation of private fleet.json, merge-result completeness, disabled-controller migration gating, strict validation, and immutable-pin guidance.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1f0bc0bb6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

Retry: please review the exact current head b1f0bc0bb6df965050f3ce089283db9942febcbc, focusing on tag-namespace collision safety, preservation of private fleet.json, merge-result completeness, disabled-controller migration gating, strict validation, and immutable-pin guidance.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1f0bc0bb6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 832b531573

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md
Comment thread docs/UPDATING.md
- require a clean tree before restoring fleet.json from ADOPTER_HEAD
- verify previously fetched tag object IDs; refs/remotes updates do not
  fail closed on retargeted tags
- review staged validator/migration changes before executing any
  tooling introduced by the merge

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 188f62d364

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/test_policy.py Outdated
Comment thread docs/UPDATING.md Outdated
- policy test assertion now matches the guide's actual migration wording
- template remote creation documented as one-time setup

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0cacdf69dc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
- preserve and compare the prior tag object BEFORE fetching, since
  refs/remotes/* updates do not fail closed on retargeted tags
- two-phase schema rollout: advance engine_ref under the old schema
  first, migrate configuration once all controllers run the new engine

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f5d4e137c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
- fetch tags into a temporary ref and promote only after comparison, so
  a failed rewrite check never leaves the rewritten object trusted
- same-change validator update instruction now applies only to releases
  with an unchanged schema_version; schema upgrades happen in phase 2

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d093b1b370

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
- capture NEW_TAG as data, validate format, quote expansions
- trusted tag OIDs moved to refs/adopter/* (immune to fetch --prune)
- delete stale temporary ref before fetch; promotion requires fetch
  success
- verify the existing template remote's URL on subsequent updates

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dceec93d15

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Local refs are not shared by clones, so rewrite detection now uses the
committed TEMPLATE_RELEASE file as its baseline; the verified tag/OID
line is appended in the same commit that merges the release.

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 726bc0b4ef

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
Comment thread docs/UPDATING.md Outdated
- clean-tree requirement now aborts instead of only printing status
- existing template remote with a wrong URL fails closed
- schema migrations always arrive with a template/engine release

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5653d9bca4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
rev-parse on a tag ref returns the tag object OID for annotated tags;
merge and TEMPLATE_RELEASE need the commit.

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c89bd7a1dd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/UPDATING.md Outdated
An annotated tag re-created with a new signature or message but the same
target commit would pass a peeled-only comparison; the recorded baseline
is the tag object, and MERGE_SOURCE is the peeled commit.

Signed-off-by: Hermes Agent <hermes@nousresearch.com>
@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@Nickfost

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 5178748f97

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@Nickfost
Nickfost merged commit e483998 into main Jul 27, 2026
1 check passed
@Nickfost
Nickfost deleted the docs/updating-guide branch July 27, 2026 07:16
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.

2 participants