From e6194aee63ff2da9c1a697a6334a40baa269ae07 Mon Sep 17 00:00:00 2001 From: Tester Date: Mon, 13 Jul 2026 11:36:49 +0200 Subject: [PATCH] docs(release): document source-package contents; ship root .gitignore MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/source-release-contents.md describing which repository-root metadata/config files ship in apache-magpie--source.zip and why, and which are export-ignored — following the 0.1.0-rc2 [VOTE] review discussion on dev@magpie.apache.org. Reference it from README. Also stop export-ignoring the repository-root .gitignore so it ships again as development-environment config (useful for a from-source dev checkout), and update the .gitattributes rationale comments to match. --- .gitattributes | 18 +++++---- README.md | 1 + docs/source-release-contents.md | 66 +++++++++++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 8 deletions(-) create mode 100644 docs/source-release-contents.md diff --git a/.gitattributes b/.gitattributes index 06c767a9..87c9c434 100644 --- a/.gitattributes +++ b/.gitattributes @@ -35,16 +35,18 @@ # too would strip the one resolvable view and orphan those links. # # `.github/ISSUE_TEMPLATE/` and `.github/PULL_REQUEST_TEMPLATE.md` are -# linked by skills, and `projects/_template/.gitignore` is example -# content, so only the true CI/dev entries under `.github/` are stripped -# and `.gitignore` is anchored to the repo root. `release-verify-rc` -# re-checks the unpacked tarball (symlink-lint + validators + no-.pyc) so -# a regression here fails the RC before the [VOTE]. +# linked by skills, so only the true CI/dev entries under `.github/` are +# stripped. The `.gitignore` files ship as development-environment config +# — the repo-root one (useful for a from-source dev checkout) and the +# nested examples (e.g. `projects/_template/.gitignore`) alike. +# `release-verify-rc` re-checks the unpacked tarball (symlink-lint + +# validators + no-.pyc) so a regression here fails the RC before the [VOTE]. -# Root-only VCS / dev-tool metadata (anchored so identically-named files -# deeper in the tree — e.g. projects/_template/.gitignore — still ship). +# Root-only VCS / dev-tool metadata. Anchored with a leading `/` so an +# identically-named file deeper in the tree is unaffected. The repo-root +# `.gitignore` is intentionally NOT listed here — it ships as +# development-environment config (see the note above). /.gitattributes export-ignore -/.gitignore export-ignore /.pre-commit-config.yaml export-ignore /.lychee.toml export-ignore /.lycheecache export-ignore diff --git a/README.md b/README.md index 29b932d4..31f5fd64 100644 --- a/README.md +++ b/README.md @@ -231,5 +231,6 @@ files are reproduced in [`NOTICE`](NOTICE). - [`MISSION.md`](MISSION.md) — **draft** project-establishment proposal: motivation, scope, design commitments, initial PMC composition target. - [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md) — the contract between adopters who write overrides and framework skills that read them. - [`docs/prerequisites.md`](docs/prerequisites.md) — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, `uv`, etc.). +- [`docs/source-release-contents.md`](docs/source-release-contents.md) — what ships in the signed `apache-magpie--source.zip` (and what is excluded), with the rationale for the repository-root metadata/config files it keeps. - [`AGENTS.md`](AGENTS.md) — agent instructions, placeholder convention, framework conventions. - [`CONTRIBUTING.md`](CONTRIBUTING.md) — for framework contributors. diff --git a/docs/source-release-contents.md b/docs/source-release-contents.md new file mode 100644 index 00000000..4dafaaff --- /dev/null +++ b/docs/source-release-contents.md @@ -0,0 +1,66 @@ + + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Source release contents](#source-release-contents) + - [Files kept in the source archive](#files-kept-in-the-source-archive) + - [Files deliberately excluded](#files-deliberately-excluded) + + + +# Source release contents + +The signed source artefact — `apache-magpie--source.zip`, the +file the `[VOTE]` thread votes on — is produced with `git archive`, +which honours the `export-ignore` attributes declared in +[`.gitattributes`](../.gitattributes). Alongside the framework source +(`skills/`, `tools/`, `docs/`, `projects/`, the Python packaging, and +`LICENSE`/`NOTICE`) the archive deliberately keeps a small set of +repository-root metadata and configuration files. + +Those files are **part of the development and release environment**, not +stray artefacts: a from-source checkout of Magpie needs them to build the +project, run its licence audit, and drive the framework's own skills. To a +reviewer scanning the archive they can look like "developer-only" noise, +so this note records what each one is and why it ships. It follows the +review discussion on the `0.1.0-rc2` `[VOTE]` thread on +`dev@magpie.apache.org`. + +`release-verify-rc` re-checks the unpacked archive (symlink-lint, +validators, no `.pyc`), so a regression in what ships fails the RC before +the vote. + +## Files kept in the source archive + +| Path | Why it ships | +|---|---| +| `.rat-excludes` | Input to Apache RAT, passed via `--input-exclude-file` in `.github/workflows/rat.yml`. Declares the paths that legitimately carry no Apache licence header (lock files, generated markers, licence-detection test fixtures). Anyone re-running the licence audit on the source tree — including `release-verify-rc` — needs it. | +| `.asf.yaml` | ASF self-service repository configuration consumed by ASF infrastructure (GitHub settings, notifications, branch protections). Standard ASF project metadata. | +| `doap_Magpie.rdf` | The project's DOAP ("Description Of A Project") RDF descriptor — the machine-readable project record that `projects.apache.org` and ASF tooling consume. Standard ASF project metadata. | +| `.apache-magpie.lock` | The committed self-adoption pin (Magpie adopts itself: `method: local`, `source: skills/`). Part of the framework's own adoption wiring, read by `/magpie-setup`. | +| `.claude/settings.json` | Agent development-environment configuration for working on the framework from source. Part of the dev environment rather than a personal preference; more agent configs may be added over time. | +| `.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md` | Not just GitHub chrome — these are referenced by shipped GitHub-vendor skills (PR / issue triage tooling) and cross-checked by validation hooks that verify inter-file links resolve. Stripping them would break those skills and fail the validators. (The genuinely CI/bot-only parts of `.github/` are excluded — see below.) | +| `.gitignore` files — the repository root one plus the nested ones (`projects/_template/.gitignore`, `tools/*/.gitignore`, `.apache-magpie-overrides/.gitignore`) | Development-environment configuration. The repository-root `.gitignore` keeps a from-source dev checkout of the framework clean; `projects/_template/.gitignore` is example content shipped for adopters to copy; the `tools/*` ones keep a from-source dev checkout of each tool package clean. | +| `.agents/skills/*` (symlinks) | The canonical agent skill view — single-hop symlinks that resolve straight to the real `skills/*` directories — kept so the shipped agent view resolves out of the box. The relay chains other agent dirs use (`.claude/skills/`, `.github/skills/`, `.kiro/skills/`) are excluded because they chain symlink → symlink, which a safe archive extractor rejects. | + +## Files deliberately excluded + +The following are stripped from the archive via `export-ignore` in +[`.gitattributes`](../.gitattributes) — VCS / CI / editor metadata that a +source consumer never needs: + +- **Repository-root VCS / dev metadata:** `.gitattributes`, + `.pre-commit-config.yaml`, the linter configs (`.lychee.toml`, + `.markdownlint.json`, `.typos.toml`, `.zizmor.yml`), and + `.apache-magpie.session-state.json`. (The repository-root `.gitignore` + is **not** excluded — it ships as dev-environment config, above.) +- **Editor metadata:** `.idea/`. +- **CI / bot config:** `.github/workflows/`, `.github/dependabot.yml`. +- **Relay symlink dirs:** `.claude/skills/`, `.github/skills/`, + `.kiro/skills/` (the symlink-chaining views described above). + +[`.gitattributes`](../.gitattributes) is the authoritative list and +carries the per-entry rationale.