From 4fb0be8919e7aa13977e3dac8171b3a3402c0cca Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:01:55 -0500 Subject: [PATCH] Add ROADMAP.md for planned work, and make public text stand on its own --- .cursor/environment.json | 2 +- .github/ISSUE_TEMPLATE/feature.yml | 3 ++- AGENTS.md | 3 +-- CONTRIBUTING.md | 5 +++++ README.md | 11 ++++++----- ROADMAP.md | 11 +++++++++++ docs/github-presence.md | 5 ++++- docs/operations-runbook.md | 11 ++++------- docs/publishing-automation.md | 2 +- docs/repo-layout.md | 10 +++++++--- 10 files changed, 42 insertions(+), 21 deletions(-) create mode 100644 ROADMAP.md diff --git a/.cursor/environment.json b/.cursor/environment.json index 6e013dd..e1d2a7e 100644 --- a/.cursor/environment.json +++ b/.cursor/environment.json @@ -1,5 +1,5 @@ { - "_comment": "Repositories Cursor's cloud environment checks out beside this one. The reference list is REPOS in the private workspace anchor's bootstrap.sh (PyDevices/workspace), which never lists the anchor itself. This file is static JSON consumed by Cursor's cloud environment setup before 'install' runs, so it cannot be generated at environment-init time -- keep it converged by hand when REPOS changes.", + "_comment": "Repositories Cursor's cloud environment checks out beside this one. This file is static JSON consumed by Cursor's cloud environment setup before 'install' runs, so it cannot be generated at environment-init time -- keep it converged by hand when a public repository is added or retired.", "install": "bash scripts/cloud-workspace-install.sh && bash scripts/cloud-python-deps.sh && bash scripts/cloud-pydevices-examples-dev-env.sh", "start": "true", "repositoryDependencies": [ diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index 38515f0..021c71e 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -5,7 +5,8 @@ body: - type: markdown attributes: value: | - Thanks for the suggestion! For open-ended questions or discussion, + Thanks for the suggestion! Check the repo's ROADMAP.md first: it + may already be planned. For open-ended questions or discussion, consider starting a thread in [pydevices-examples Discussions](https://github.com/PyDevices/pydevices-examples/discussions) instead. diff --git a/AGENTS.md b/AGENTS.md index 3b6b5d9..75f6ea2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,8 +79,7 @@ resolve two levels up from `manifests/`), and the one every build script in the org defaults to: from `micropython/ports/`, upstream's own `make` with `VARIANT_DIR=`, `BOARD_DIR=` and `FROZEN_MANIFEST=` pointing into `micropython-pydevices`; for CircuitPython, each C-carrying repo's -`apply_cp_patches.sh` and then upstream's `make`. The workspace anchor's -`docs/retool-build-draft.md` carries the commands. +`apply_cp_patches.sh` and then upstream's `make`. Upstream trees (`micropython/`, `circuitpython/`) are **read-only clones** in this workspace. The MicroPython one carries a single local commit, the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70f93b3..0da5ea7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,11 @@ Use the issue templates on the relevant repo. Include the interpreter (MicroPython/CircuitPython/CPython), version, and platform/board where applicable — most bugs here are interpreter- or hardware-specific. +Every repository has a `ROADMAP.md` at its root: the planned enhancements and +restructuring, in short bullets for users. Issues are for bugs and for things +you need that don't work yet. A request that becomes planned work moves into +the roadmap and its issue closes with a link to it. + For open-ended questions, ideas, or show-and-tell, use [pydevices Discussions](https://github.com/PyDevices/pydevices/discussions) instead of opening an issue. diff --git a/README.md b/README.md index f90cd67..f643fd2 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,10 @@ the parts they'd otherwise duplicate. from [`release-health/data.json`](release-health/data.json) every time a publishing repository's release chain reports in. Don't hand-edit either file. -- **The multi-repository workspace** is defined by the private `workspace` - anchor repository, whose own `bootstrap.sh` carries the list of every - PyDevices repository and clones them as siblings on disk. The list in - [`.cursor/environment.json`](.cursor/environment.json) is Cursor's cloud - copy of it, kept by hand. +- **Sibling checkouts** — the PyDevices repositories build against each + other checked out side by side on disk. + [`.cursor/environment.json`](.cursor/environment.json) lists the ones + Cursor's cloud environment clones, kept by hand. - **The repository database and site generator** — [`data/repos_db.json`](data/repos_db.json) is the single source of truth for the repository map: tier, description, buttons, and where each repo's @@ -46,6 +45,8 @@ the parts they'd otherwise duplicate. **Edit the database, not the generated markup** — run the generator by hand from a full workspace checkout (`python3 dotgithub/scripts/generate_sites.py`) after editing it; it validates the database first and is idempotent. +- **Roadmap** — [`ROADMAP.md`](ROADMAP.md): what's planned for the shared + automation. Every repository keeps its own. - **History** — [`docs/history.md`](docs/history.md): how the organization came to be, and a dated chronology of every repository. - **Org docs** — [`docs/`](docs/) covers repo layout, doc style and diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..4e96137 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,11 @@ +# Roadmap + +Where the org's shared release automation and community files are heading. +Bugs, and things you need that don't work yet, go to +[issues](https://github.com/PyDevices/.github/issues). + +## Release automation + +- A manual way to tag a release when GitHub drops the merge event. Every + repository that calls the shared tagging workflow gets it by adding one + trigger line, instead of carrying its own copy of the fix. diff --git a/docs/github-presence.md b/docs/github-presence.md index b4ff519..9fbf505 100644 --- a/docs/github-presence.md +++ b/docs/github-presence.md @@ -30,7 +30,10 @@ the answer from scratch. reaching the maintainer. Every other repository has Discussions turned off (2026-09-03) so there is exactly one place to look; SUPPORT.md, CONTRIBUTING.md and the design docs all point there. -- **Issues** are enabled on every owned repo (bug reports / feature requests). +- **Issues** are enabled on every owned repo, for bugs and for things a user + needs that don't work yet. Planned enhancements live in each repo's + `ROADMAP.md` instead; a feature request that becomes planned work moves + there and its issue closes. Default issue *templates* (`bug.yml`, `feature.yml`) live in the org's [`.github`](https://github.com/PyDevices/.github/tree/main/.github/ISSUE_TEMPLATE) repo and apply automatically to any repo that doesn't define its own. diff --git a/docs/operations-runbook.md b/docs/operations-runbook.md index b54309d..e36cdd5 100644 --- a/docs/operations-runbook.md +++ b/docs/operations-runbook.md @@ -49,8 +49,8 @@ history stays. - The release-automation App mints all cross-repo tokens (create-github-app-token in the reusables). Failures name the missing - permission or repo in the log. Brad owns the App's installation and - permissions; agents never hold its key (roadmap rule 3). + permission or repo in the log. The org owner holds the App's installation + and permissions; agents never hold its key (roadmap rule 3). - The dashboard receiver (`release-health.yml`) is repository_dispatch only; a stuck dashboard means the App can't reach this repo. Rows are additive JSON in `release-health/data.json` — safe to hand-edit in a @@ -65,8 +65,5 @@ history stays. - **A human maintainer**: CONTRIBUTING.md here, then the repo they'll touch (every repo states its role, status, and build path in its README), then publishing-automation.md before their first release. -- **An agent**: the private workspace anchor repo holds the agent - contract (`docs/agent-contract.md`), the knowledge modules - (`docs/agent-knowledge/`), and the fleet definitions - (`.claude/agents/`). New agents are forged through `/forge-agent` and - are not trusted until their smoke task has run green. +- **An agent**: [AGENTS.md](../AGENTS.md) here, then the `AGENTS.md` of the + repository it works in. diff --git a/docs/publishing-automation.md b/docs/publishing-automation.md index 44ce6e5..803ccc0 100644 --- a/docs/publishing-automation.md +++ b/docs/publishing-automation.md @@ -366,7 +366,7 @@ whose build and TestPyPI upload succeeded, and the caller uploads: ``` The `pypi` job runs through the repository's `pypi` **GitHub Environment** -(required reviewer Brad, deployment limited to `v*` tags; check with +(a required maintainer review, deployment limited to `v*` tags; check with `gh api repos/PyDevices//environments/pypi`) and authenticates with **Trusted Publishing** (OIDC, no stored PyPI credential). The PyPI project's publisher is owner `PyDevices`, the repository, workflow diff --git a/docs/repo-layout.md b/docs/repo-layout.md index b2f05b2..b82fbfc 100644 --- a/docs/repo-layout.md +++ b/docs/repo-layout.md @@ -30,15 +30,19 @@ Long-form notes and guides belong under `docs/`. | Packaging / build metadata | `pyproject.toml`, `setup.py`, `setup.cfg`, `MANIFEST.in`, `micropython.mk`, `circuitpython.mk` | Yes — tooling discovers these at root | | Docs site config | `mkdocs.yml` | Yes | | Short entry scripts | `apply_*.sh`, `build_*.sh`, `regenerate_*.sh` | Yes when they are the public entry point | -| License / community | `LICENSE`, `README.md`, `AGENTS.md`, `CONTRIBUTING.md` | Yes | +| License / community | `LICENSE`, `README.md`, `ROADMAP.md`, `AGENTS.md`, `CONTRIBUTING.md` | Yes | | Pip requirements | `requirements.txt`, `requirements-dev.txt` | Yes (see below) | | Long-form docs | design notes, build guides, handoffs, publishing write-ups | No — use `docs/` | ### Markdown naming - Reserve all-caps Markdown names for conventional repository and community - control files such as `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, - `SECURITY.md`, and `CHANGELOG.md`. + control files such as `README.md`, `ROADMAP.md`, `AGENTS.md`, + `CONTRIBUTING.md`, `SECURITY.md`, and `CHANGELOG.md`. +- Every repository has a `ROADMAP.md`: planned enhancements and restructuring, + written for users, one bullet of at most three lines each. Bugs and unmet + needs stay in issues. A repository with nothing planned says so in a line, + and its README links the file. - **Do not add `RELEASE_NOTES.md`.** All three that existed carried a bare `## Unreleased` heading, never recorded a shipped version, and were linked from nowhere; they were deleted in August 2026. Releases use `--generate-notes`, so