From 1e41d98b30b3e63468ebe4cd5fd5c82463c8ec8c Mon Sep 17 00:00:00 2001 From: Johan Carlin Date: Thu, 2 Apr 2026 21:35:25 +0200 Subject: [PATCH] docs: plan upstream submodule cutover and workflow --- AGENTS.md | 23 +++++++++++++++++++++++ README.md | 25 +++++++++++++++++++++++++ TODO.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..afcf40881 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# AGENTS.md + +## Scope +These instructions apply to the entire repository tree rooted at this directory. + +## Upstream submodule policy +- The `upstream/` directory is the canonical location for upstream `devcontainers/cli` TypeScript sources. +- Do **not** introduce new copies of upstream-owned files at repository root. +- Keep project-owned implementation and migration work outside `upstream/` unless explicitly updating the submodule pointer. + +## Compatibility baseline +- Treat the pinned `upstream/` submodule commit as the compatibility target. +- When changing compatibility-sensitive behavior, prefer tests/logging that make the current upstream commit easy to identify. + +## Updating upstream +When asked to update upstream: +1. Update the submodule pointer in `upstream/`. +2. Run/adjust parity tests and related fixtures against the new upstream revision. +3. Keep changes reviewable (submodule bump + project-owned compatibility fixes). + +## Pathing expectations +- Tests, scripts, and docs that need upstream assets should reference paths under `upstream/...` explicitly. +- Avoid hardcoded assumptions that upstream files exist at repository root. diff --git a/README.md b/README.md index 52276f289..599cab02d 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,25 @@ This repository is a Rust port of [devcontainer](https://github.com/devcontainers/cli) CLI. Work in progress, use at own risk. +## Repository layout and upstream compatibility + +This repo now tracks the upstream TypeScript implementation as a git submodule at [`upstream/`](./upstream). The pinned submodule commit is the compatibility baseline for this project: when we say we are compatible with upstream, we mean compatible with that exact revision. + +- `upstream/`: unmodified upstream devcontainers/cli sources (baseline under test). +- repository root: project-owned Rust port, migration tooling, compatibility tests, and docs. + +When updating upstream, prefer an explicit workflow: +1. Bump the `upstream/` submodule commit. +2. Run parity/compatibility tests against the new pinned revision. +3. Fix regressions in project-owned code. +4. Merge once CI is green. + +If you clone this repository without submodules, initialize them before building/testing: + +```bash +git submodule update --init --recursive +``` + ## Context A development container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud. @@ -144,6 +163,12 @@ The [example-usage](./example-usage) folder contains some simple shell scripts t This repository has a [dev container configuration](https://github.com/devcontainers/cli/tree/main/.devcontainer), which you can use to ensure you have the right dependencies installed. +If you have not initialized submodules yet, run: + +```sh +git submodule update --init --recursive +``` + Compile the CLI with yarn: ```sh yarn diff --git a/TODO.md b/TODO.md index b3758fc4b..143e18a4f 100644 --- a/TODO.md +++ b/TODO.md @@ -173,3 +173,55 @@ This balances near-term user value with long-term maintainability. - [x] Create a short decision memo: SEA viability vs packager alternatives. - [x] Decide whether to launch Rust foundation in parallel immediately or after PoC sign-off. - Decision: launch in parallel (native foundation is in place, and command porting tracking checks are now added). + +--- + +## Phase: Upstream submodule cutover (`upstream/`) + +### Objective +Move all vendored upstream TypeScript CLI sources out of repo root and treat `upstream/` (git submodule) as the canonical upstream baseline we target for compatibility. + +### 1) Repository layout and ownership +- [ ] Confirm `upstream/` is the only place where upstream devcontainers/cli code lives. +- [ ] Remove duplicated upstream-owned files currently checked in at repository root once replacements are wired. +- [ ] Keep only project-owned integration/porting assets at repository root (Rust code, migration docs, compatibility harness, and project-specific tests). +- [ ] Add/refresh `.gitmodules` and contributor guidance so updating upstream is intentional and reviewable. + +### 2) Build/test path migration +- [ ] Audit all test fixtures, scripts, and build commands that currently reference root-level upstream paths. +- [ ] Rewrite references to point at `upstream/...` explicitly (including npm/yarn commands, fixture paths, and script helpers). +- [ ] Introduce shared path helpers (where practical) to avoid hardcoded duplicate path strings in tests. +- [ ] Ensure CI jobs execute against `upstream/` sources and fail fast when submodule is missing/uninitialized. + +### 3) Compatibility target versioning +- [ ] Define the compatibility contract as: “this repo targets the exact commit pinned in `upstream/`.” +- [ ] Expose the pinned upstream commit in test output/logging for traceability. +- [ ] Add a dedicated CI check that reports diffs/regressions when submodule commit changes. +- [ ] Create an “update upstream” workflow (bump submodule -> run parity suite -> fix breakages -> merge). + +### 4) Documentation updates +- [ ] Update `README.md` with: + - [ ] why `upstream/` exists, + - [ ] how to clone/init submodules, + - [ ] what to run when submodule is not initialized, + - [ ] how compatibility testing maps to the pinned upstream revision. +- [ ] Add/update root `AGENTS.md` with contributor/agent rules for: + - [ ] where upstream code must live (`upstream/` only), + - [ ] where project-owned changes should be made, + - [ ] how to perform/validate submodule bumps. +- [ ] Add a short migration note in changelog or docs index once root-level upstream code is removed. + +### 5) Execution plan and rollout +- [ ] Land this as staged PRs to reduce risk: + 1. [ ] docs + guardrails (`README.md`, `AGENTS.md`, CI checks), + 2. [ ] path rewrites in tests/scripts, + 3. [ ] removal of duplicated root upstream code, + 4. [ ] final parity + cleanup. +- [ ] Run full parity/integration suite before and after each stage to isolate regressions. +- [ ] Gate final removal behind green CI across at least one Linux x64 lane. + +### Exit criteria +- [ ] No tests/build scripts depend on root-level upstream copies. +- [ ] `upstream/` submodule commit is the declared compatibility baseline. +- [ ] Docs clearly explain contributor workflow for submodule init/update. +- [ ] CI protects against accidental drift or missing submodule checkout.