This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 01d4760 docs: replace stale submodule references with snapshot model
(#56)
01d4760 is described below
commit 01d4760a64ffa5cfd116e6d377518794c2a8b638
Author: Jarek Potiuk <[email protected]>
AuthorDate: Tue May 5 11:53:54 2026 +0200
docs: replace stale submodule references with snapshot model (#56)
The framework's adoption mechanism pivoted from git-submodule to
gitignored-snapshot (managed by setup-steward) on 2026-05-03;
~10 files still carried stale "submodule" framing from the older
design. This PR aligns the prose with what the code already does.
Files updated:
- AGENTS.md
- Repository purpose: "Adopting projects pull this repository in
as a submodule" → "fetch this repository as a gitignored
snapshot (managed by setup-steward)".
- Per-project layout sketch: drop the nested `apache-steward/`
submodule line; relocate the project-config tree under the
`<project-config>/` placeholder (which adopters resolve to a
path of their choice, alongside the gitignored snapshot).
- `<framework>` placeholder description: snapshot path, not
submodule path.
- "Always run `git submodule update --init --recursive`"
paragraph: replaced with the snapshot/lock-file model
(committed `.apache-steward.lock` is the project pin; every
skill drift-checks it against the gitignored
`.apache-steward.local.lock`; `/setup-steward upgrade`
refreshes the snapshot). Explicitly notes there is no
`git submodule update` step.
- README.md: "every clone URL, git-submodule reference, and CI
integration still uses the legacy slug" → drop the
git-submodule line (no submodule references exist after this
PR).
- CONTRIBUTING.md: "consume this framework as a submodule" →
"consume this framework as a gitignored snapshot managed by
the setup-steward skill".
- docs/setup/secure-agent-setup.md (3 hits): consume-as-submodule
framing replaced; the example settings.json copy path updated
from `.apache-steward/apache-steward/.claude/settings.json`
(nested submodule layout) to `.apache-steward/.claude/settings.json`
(snapshot layout); the `claude-iso.sh` source path likewise
flattened.
- tools/vulnogram/generate-cve-json/README.md and
tools/gmail/oauth-draft/README.md: "the
`.apache-steward/apache-steward/` submodule path" →
"the `.apache-steward/` snapshot path".
- .claude/skills/setup-isolated-setup-update/SKILL.md: dropped a
stale reference to "the parent-tracker submodule pointer" in
the framework-update follow-up; the snapshot model has no
parent-tracker pointer to bump.
- .claude/skills/security-issue-sync/SKILL.md: "the framework
lives in a submodule that does not render through the
parent-repo viewer" → "the framework lives in the gitignored
snapshot at `<adopter-tracker>/.apache-steward/` that does not
render through the parent-repo viewer". The absolute-URL rule
it justifies is unchanged.
Three "no submodules" *design assertions* are kept verbatim —
README.md ("No git submodules. No marketplace."),
.claude/skills/setup-steward/SKILL.md ("snapshot + agentic
overrides … not submodule, not marketplace, not vendored
copy"), and a new sentence in AGENTS.md ("There is no
`git submodule update` step — the snapshot mechanism replaces
that entirely"). These are load-bearing context, not stale
references.
Generated-by: Claude Code (Claude Opus 4.7)
---
.claude/skills/security-issue-sync/SKILL.md | 7 +-
.../skills/setup-isolated-setup-update/SKILL.md | 10 +--
AGENTS.md | 84 +++++++++++-----------
CONTRIBUTING.md | 6 +-
README.md | 12 ++--
docs/setup/secure-agent-setup.md | 18 ++---
tools/gmail/oauth-draft/README.md | 3 +-
tools/vulnogram/generate-cve-json/README.md | 3 +-
8 files changed, 74 insertions(+), 69 deletions(-)
diff --git a/.claude/skills/security-issue-sync/SKILL.md
b/.claude/skills/security-issue-sync/SKILL.md
index 4ff9049..6c0f2ff 100644
--- a/.claude/skills/security-issue-sync/SKILL.md
+++ b/.claude/skills/security-issue-sync/SKILL.md
@@ -1564,9 +1564,10 @@ will change and *why*. Group them by category:
parameterised with the CVE ID.
- `FRAMEWORK_RECORD_MD_URL`, `FRAMEWORK_SYNC_SKILL_URL`,
`FRAMEWORK_README_URL` — absolute GitHub URLs into
- `apache/airflow-steward` `main`, since the framework lives in a
- submodule that does not render through the parent-repo viewer
- (per the absolute-URL rule used elsewhere in this repo).
+ `apache/airflow-steward` `main`, since the framework lives in
+ the gitignored snapshot at `<adopter-tracker>/.apache-steward/`
+ that does not render through the parent-repo viewer (per the
+ absolute-URL rule used elsewhere in this repo).
- `CANNED_RESPONSES_URL` — absolute GitHub URL into the tracker
repo's `<project-config>/canned-responses.md`.
diff --git a/.claude/skills/setup-isolated-setup-update/SKILL.md
b/.claude/skills/setup-isolated-setup-update/SKILL.md
index 49ec8db..5442463 100644
--- a/.claude/skills/setup-isolated-setup-update/SKILL.md
+++ b/.claude/skills/setup-isolated-setup-update/SKILL.md
@@ -155,11 +155,11 @@ If something is out-of-date or has drifted, name the
concrete
follow-up:
- Framework checkout behind → run
- [`setup-steward-upgrade`](../setup-steward-upgrade/SKILL.md),
- which performs the `git pull --ff-only` after the same
- pre-flight checks this skill recommends, surfaces what
- arrived, and reminds the user to handle the parent-tracker
- submodule pointer if applicable.
+ [`/setup-steward upgrade`](../setup-steward/upgrade.md),
+ which refreshes the gitignored snapshot per the committed
+ `.apache-steward.lock` after the same pre-flight checks this
+ skill recommends and surfaces what arrived in the new
+ snapshot.
- Pinned-tool upgrade candidate worth adopting → manifest bump PR
per [Bumping a pinned
version](../../../docs/setup/secure-agent-setup.md#bumping-a-pinned-version).
- User-scope script drift → re-`cp` from the framework checkout,
diff --git a/AGENTS.md b/AGENTS.md
index 015dd8f..5e99efc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -60,10 +60,12 @@ top of [`README.md`](README.md) for the candidate list and
timeline) is the **generic, project-agnostic framework**.
It contains skills, tool adapters, generic process documentation,
and a project-template scaffold — and **no project-specific
-content**. Adopting projects pull this repository in as a submodule
-of their tracker repo (under
`<adopter-tracker>/.apache-steward/apache-steward/`)
-and configure their project-specific bits in
`<adopter-tracker>/.apache-steward/`
-alongside the submodule. The framework refers to that adopter-side
+content**. Adopting projects fetch this repository as a gitignored
+**snapshot** at `<adopter-tracker>/.apache-steward/` (managed by
+the [`setup-steward`](.claude/skills/setup-steward/SKILL.md) skill —
+see [`docs/setup/install-recipes.md`](docs/setup/install-recipes.md))
+and configure their project-specific bits alongside the snapshot
+in their adopter repo. The framework refers to that adopter-side
configuration as `<project-config>`.
The framework has two layers:
@@ -231,28 +233,30 @@ Two configuration layers tell the skills how this working
tree is set
up.
**Project layer — shared, checked in.** Each adopting project keeps
-its project-specific configuration in a `.apache-steward/` directory
-at the root of its tracker repository. The framework refers to this
-directory via the placeholder `<project-config>`. Concretely, an
-adopting project lays out:
+its project-specific configuration in a `<project-config>/` directory
+in their tracker repository, alongside the gitignored framework
+snapshot at `.apache-steward/` (which `setup-steward` manages and
+which carries no adopter-specific content). The framework refers
+to the project-config directory via the `<project-config>`
+placeholder; the concrete path is the adopter's choice (the
+[`projects/_template/`](projects/_template/) scaffold is the
+starting point an adopter copies in). The directory contains:
```text
-<adopter-tracker-repo>/
-└── .apache-steward/
- ├── apache-steward/ # (submodule) clone of this framework
- ├── project.md # project manifest — identity, repos,
- │ # mailing lists, CVE tooling, links to
- │ # the sibling files below
- ├── canned-responses.md # reporter-facing reply templates
- ├── release-trains.md # release-manager + security-team rosters
- ├── security-model.md # project's security policy
- ├── milestones.md # milestone-format conventions
- ├── scope-labels.md # scope label set + CVE product mapping
- ├── naming-conventions.md
- ├── title-normalization.md
- ├── fix-workflow.md
- ├── user.md.example # template for the user layer below
- └── user.md # gitignored — per-user
+<project-config>/ # adopter chooses path; committed
+├── project.md # project manifest — identity, repos,
+│ # mailing lists, CVE tooling, links to
+│ # the sibling files below
+├── canned-responses.md # reporter-facing reply templates
+├── release-trains.md # release-manager + security-team rosters
+├── security-model.md # project's security policy
+├── milestones.md # milestone-format conventions
+├── scope-labels.md # scope label set + CVE product mapping
+├── naming-conventions.md
+├── title-normalization.md
+├── fix-workflow.md
+├── user.md.example # template for the user layer below
+└── user.md # gitignored — per-user
```
The project manifest (`<project-config>/project.md`) is the load-bearing
@@ -290,7 +294,7 @@ the active configuration before executing any command:
| Placeholder | Resolves to | Source |
|---|---|---|
| `<project-config>` | The adopting project's `.apache-steward/` directory in
its tracker repo. | Filesystem convention. |
-| `<framework>` | The framework's root — i.e. this repository. In adopting
projects, `<project-config>/apache-steward/` (the submodule path); in framework
standalone, `.` (the repository root). Used in `uv run` and other invocations
that need to address the framework's `tools/<name>/` subtrees from a path the
agent can resolve at the agent's current `cwd`. | Filesystem convention. |
+| `<framework>` | The framework's root — i.e. this repository. In adopting
projects, `.apache-steward/` (the gitignored snapshot path managed by
`setup-steward`); in framework standalone, `.` (the repository root). Used in
`uv run` and other invocations that need to address the framework's
`tools/<name>/` subtrees from a path the agent can resolve at the agent's
current `cwd`. | Filesystem convention. |
| `<tracker>` | The GitHub slug of the tracker repo (example:
`airflow-s/airflow-s` for the Apache Airflow security team). |
`<project-config>/project.md` → `tracker_repo` |
| `<upstream>` | The GitHub slug of the upstream codebase the fixes land in
(example: `apache/airflow`). | `<project-config>/project.md` → `upstream_repo` |
| `<security-list>` | The project's security mailing list (example:
`[email protected]`). | `<project-config>/project.md` →
`mailing_lists.security` |
@@ -358,22 +362,20 @@ commit again. **Do not bypass the hooks with
`--no-verify`** —
if a hook is failing, fix the underlying issue or update the
hook configuration in the same PR.
-**Always run `git submodule update --init --recursive` after pulling
-the adopter tracker repository.** The framework lives at
-`<adopter-tracker>/.apache-steward/apache-steward/` as a git
-submodule (see [Repository purpose](#repository-purpose) above);
-plain `git pull` on the tracker advances the submodule *pointer*
-in the tracker's index but does **not** update the working tree
-of the submodule itself. Skills then run against the previous
-version of the framework — same skill names, stale skill bodies —
-and the failure mode is silent. Make `git submodule update --init
---recursive` part of muscle memory after every pull, or wire it
-into a post-merge hook (`.git/hooks/post-merge` →
-`#!/bin/sh\nexec git submodule update --init --recursive`). Same
-rule applies to the framework's own
-[`setup-steward upgrade`](.claude/skills/setup-steward/upgrade.md)
-skill: when invoked from inside an adopter tracker, it reminds
-the user to follow up with submodule update on the parent.
+**Keep the framework snapshot in sync with the project's pin.**
+The framework lives at `<adopter-tracker>/.apache-steward/` as a
+**gitignored snapshot** that
+[`setup-steward`](.claude/skills/setup-steward/SKILL.md) manages
+(see [Repository purpose](#repository-purpose) above). The
+project's pinned framework version is recorded in the committed
+`.apache-steward.lock`; the snapshot itself is fetched on first
+adoption and refreshed by `/setup-steward upgrade`. Every
+framework skill compares the gitignored `.apache-steward.local.lock`
+(per-machine fetch) against the committed `.apache-steward.lock`
+(project pin) at the top of its run; on drift, the skill surfaces
+the gap and proposes `/setup-steward upgrade`. There is **no**
+`git submodule update` step — the snapshot mechanism replaces
+that entirely.
**Run the agent in the credential-isolation setup.** The skills
operate against pre-disclosure CVE content; running Claude Code (or
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c97f6fd..80ed2ba 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,8 +23,10 @@ Thanks for helping improve this repository. It is a reusable
framework
for running the ASF security-disclosure process as a set of agent-driven
skills. Adopting projects ship a per-project configuration layer
(`<project-config>/`) in their own tracker repo and consume this
-framework as a submodule — see [`projects/_template/`](projects/_template/)
-for the scaffold an adopter copies and fills in.
+framework as a gitignored snapshot managed by the
+[`setup-steward`](.claude/skills/setup-steward/SKILL.md) skill —
+see [`projects/_template/`](projects/_template/) for the scaffold
+an adopter copies and fills in.
Before sending a patch, please skim this file end-to-end: it lays out
the layering the repository depends on, and a patch that ignores the
diff --git a/README.md b/README.md
index 1423a45..3530bdb 100644
--- a/README.md
+++ b/README.md
@@ -44,12 +44,12 @@
> - Apache Lexicon
> - Apache Polyglot
>
-> Until the rename lands on the GitHub side, every clone URL,
-> git-submodule reference, and CI integration still uses the
-> legacy `apache/airflow-steward` slug — all path examples in
-> this README and the linked docs use that slug verbatim. The
-> rename will only change the GitHub repository slug; existing
-> checkouts will keep working with a single `git remote set-url`.
+> Until the rename lands on the GitHub side, every clone URL and
+> CI integration still uses the legacy `apache/airflow-steward`
+> slug — all path examples in this README and the linked docs use
+> that slug verbatim. The rename will only change the GitHub
+> repository slug; existing checkouts will keep working with a
+> single `git remote set-url`.
A reusable, project-agnostic framework for ASF-project automation.
Currently in development for ASF projects + Python Core team
diff --git a/docs/setup/secure-agent-setup.md b/docs/setup/secure-agent-setup.md
index a1b8899..82373f5 100644
--- a/docs/setup/secure-agent-setup.md
+++ b/docs/setup/secure-agent-setup.md
@@ -89,10 +89,11 @@ privilege-elevating runs without you saying so.
```text
1. Open Claude Code in your tracker repo (or any directory).
-2. If you consume the framework as a submodule of your tracker
- (the canonical adopter pattern), run `/setup-steward verify`
- to confirm `.apache-steward/`, the submodule, and the
- project-config under it are wired correctly. Read-only —
+2. If you consume the framework as a gitignored snapshot managed
+ by `setup-steward` (the canonical adopter pattern), run
+ `/setup-steward verify` to confirm the snapshot at
+ `.apache-steward/`, the committed `.apache-steward.lock`, and
+ the project-config files are wired correctly. Read-only —
surfaces gaps, never auto-fixes.
3. Run /setup-isolated-setup-install — guided first-time install of
the secure-agent setup (sandbox, hooks, status line,
@@ -841,7 +842,8 @@ sub-section that follows.
above.
2. Copy
[`.claude/settings.json`](../../.claude/settings.json) from the framework
- submodule into `<your-tracker>/.claude/settings.json`. Adjust:
+ snapshot at `<your-tracker>/.apache-steward/.claude/settings.json`
+ into `<your-tracker>/.claude/settings.json`. Adjust:
- The `sandbox.network.allowedDomains` list — drop the framework
domains you don't actually use, add any project-specific hosts.
- The `sandbox.filesystem.allowRead` list — same: drop the
@@ -851,13 +853,13 @@ sub-section that follows.
write-side commands you want to confirm explicitly (e.g. a
custom release-publishing CLI).
3. Make `claude-iso` available on your shell — either per-repo
- (sourcing the script from the framework checkout) or globally
+ (sourcing the script from the framework snapshot) or globally
(copying the script to `~/.claude/agent-isolation/` and
sourcing from there). Both options are documented in
[The clean-env wrapper](#the-clean-env-wrapper). When the
- framework is consumed via the standard submodule path, the
+ framework is consumed via the standard snapshot path, the
per-repo source path is
-
`<your-tracker>/.apache-steward/apache-steward/tools/agent-isolation/claude-iso.sh`.
+ `<your-tracker>/.apache-steward/tools/agent-isolation/claude-iso.sh`.
4. Decide whether to gitignore `.claude/settings.local.json` in your
tracker repo — Claude Code does this by default; verify with
`git check-ignore .claude/settings.local.json`.
diff --git a/tools/gmail/oauth-draft/README.md
b/tools/gmail/oauth-draft/README.md
index 5604ca6..9511536 100644
--- a/tools/gmail/oauth-draft/README.md
+++ b/tools/gmail/oauth-draft/README.md
@@ -49,8 +49,7 @@ invocation, and the project's own test/lint workflow.
## Run
From the framework's root (this repository when running standalone;
-the `.apache-steward/apache-steward/` submodule path inside an
-adopting tracker repo):
+the `.apache-steward/` snapshot path inside an adopting tracker repo):
```bash
uv run --project tools/gmail/oauth-draft oauth-draft-create \
diff --git a/tools/vulnogram/generate-cve-json/README.md
b/tools/vulnogram/generate-cve-json/README.md
index cd030d0..5ba2acb 100644
--- a/tools/vulnogram/generate-cve-json/README.md
+++ b/tools/vulnogram/generate-cve-json/README.md
@@ -39,8 +39,7 @@ workflow for the project itself.
## Run
From the framework's root (this repository when running standalone;
-the `.apache-steward/apache-steward/` submodule path inside an
-adopting tracker repo):
+the `.apache-steward/` snapshot path inside an adopting tracker repo):
```bash
uv run --project tools/vulnogram/generate-cve-json generate-cve-json
<ISSUE-NUMBER> [options]
