diff --git a/README.md b/README.md index cbdc116..f33e2ab 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,11 @@ Each feature's NOTES.md has the full usage; after each full release, Every feature also takes a `pins_file` option (see below). A download feature also installs upstream's license notice, from the same -verified artifact, under `/usr/local/share/doc//` when the artifact -ships one; each NOTES.md has a License section. +verified artifact, under `/usr/local/share/doc/` when the artifact +ships one; each NOTES.md has a License section and names the directory. +If a feature that installs a notice doesn't find the expected license +file in its pinned artifact, the install warns and continues without the +notice; it doesn't fail. ### Pin channels @@ -253,7 +256,12 @@ library and [`test/README.md`](test/README.md) the scenario tests. plus the `_global` scenarios (see [`test/README.md`](test/README.md)). Merging to `main` only tests; nothing is published. After a full release (below), its `docs` job opens a PR with the regenerated - `src//README.md` files. + `src//README.md` files. That PR is opened with `GITHUB_TOKEN`, + which doesn't trigger workflows, so start its checks by hand (close and + reopen it, or push to its branch) before merging. `features.yml`'s + actions are pinned by full commit SHA with a `# vX.Y.Z` comment (as + GitHub's secure-use reference recommends), stricter than base's + exact-tag rule; keep that form when bumping them. - **Checks.** `prek run --all-files --hook-stage manual` runs shellcheck and the hooks in `scripts/` (install-lib drift, feature options, version bump). @@ -288,10 +296,8 @@ collection tag. Publishing needs, once, in the repository's Actions settings, only the `OCI_REGISTRY` variable set to `ghcr.io`; no secrets. `make publish` then -pushes with the release job's `GITHUB_TOKEN` (as `GITHUB_ACTOR`), which -works once template-sync has brought in a base `release.yml` whose `build` -job grants `packages: write`; until then GHCR denies the push and -`make publish` fails +pushes with the release job's `GITHUB_TOKEN` (as `GITHUB_ACTOR`); the +synced `release.yml`'s `build` job grants it `packages: write` ([ADR 0005](docs/adrs/0005-publish-to-ghcr-with-github-token.md)). `OCI_IMAGE_NAME` is optional and defaults to `craftainer/devcontainer-features`. The `OCI_REGISTRY_USERNAME` and @@ -300,8 +306,17 @@ required), and are needed for any registry other than `ghcr.io`; to move `ghcr.io` from them to `GITHUB_TOKEN`, delete both. A feature package that already exists on GHCR and wasn't first pushed by this repository's workflow needs, once, this repository given the Write role under the -package's "Manage Actions access" settings, or GHCR denies the push. Without -`OCI_REGISTRY`, a full release publishes nothing and warns. +package's "Manage Actions access" settings, or GHCR denies the push. A +new package first pushed by `GITHUB_TOKEN` inherits this repository's +public visibility, so there's no manual "make public" step; a package +created any other way starts private. Without `OCI_REGISTRY`, a full +release publishes nothing and warns. + +The collection is public on GHCR but deliberately not listed in the +containers.dev / VS Code feature index (see issue #21). Listing it later +is a PR adding one entry to `_data/collection-index.yml` on +`devcontainers/devcontainers.github.io`'s `gh-pages` branch, after which +outside users may depend on feature ids and options. To try the targets locally: `make build release-assets release-check`; `RELEASE_TAG=v1.0.0-rc.1 make publish` shows the pre-release skip. diff --git a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md index 9fdeef5..fe2e082 100644 --- a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md +++ b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md @@ -7,7 +7,11 @@ collection is released through base's `release.yml` and `Makefile` contract under a repo-wide `v` tag, and a full release publishes the features with the Dev Container CLI; `features.yml` no longer publishes on `main`. `devcontainers/action` still validates the features -and generates their READMEs. +and generates their READMEs. Corrected by +[0005](0005-publish-to-ghcr-with-github-token.md): a package first pushed +by a workflow's `GITHUB_TOKEN` (as this ADR's `features.yml` publish job +also did) inherits this repository's public visibility, so the "made +public by hand" consequence below was never needed for such a package. ## Context diff --git a/docs/adrs/0004-collection-github-releases.md b/docs/adrs/0004-collection-github-releases.md index a17b928..06771eb 100644 --- a/docs/adrs/0004-collection-github-releases.md +++ b/docs/adrs/0004-collection-github-releases.md @@ -8,7 +8,11 @@ contract, on a full collection release, not by `devcontainers/action` on every push to `main`. Partly superseded by [0005](0005-publish-to-ghcr-with-github-token.md): on `ghcr.io`, `publish` authenticates with the job's `GITHUB_TOKEN` when the registry secrets are -empty, so the secrets are no longer required there. +empty, so the secrets are no longer required there, and a package it +first pushes with `GITHUB_TOKEN` inherits this repository's public +visibility, so the "made public by hand" consequence below no longer +applies to it (a package first pushed with the secrets still starts +private). ## Context diff --git a/docs/adrs/0005-publish-to-ghcr-with-github-token.md b/docs/adrs/0005-publish-to-ghcr-with-github-token.md index b566c99..37045af 100644 --- a/docs/adrs/0005-publish-to-ghcr-with-github-token.md +++ b/docs/adrs/0005-publish-to-ghcr-with-github-token.md @@ -3,7 +3,10 @@ ## Status Accepted. Partly supersedes -[0004](0004-collection-github-releases.md). +[0004](0004-collection-github-releases.md), and corrects the "made public +by hand" consequence of +[0001](0001-one-collection-repo-released-with-devcontainers-action.md) and +0004 (see Consequences). ## Context @@ -45,7 +48,8 @@ other craftainer repo's. - On GHCR, publishing needs only the `OCI_REGISTRY` variable, once this repo's synced `release.yml` carries `packages: write`. Until template-sync brings it in, GHCR denies a full release's push when the - secrets are empty, and `publish` fails naming that cause. + secrets are empty, and `publish` fails naming that cause. (Template-sync + v1.11.6 brought it in before v1.0.0.) - Moving an existing setup from the secrets to `GITHUB_TOKEN` means deleting both secrets; leaving one fails, and leaving both keeps using them. @@ -53,4 +57,10 @@ other craftainer repo's. repository's workflow needs, once, this repository given the Write role under the package's "Manage Actions access" settings, or GHCR denies the push. +- A package first pushed by the release job's `GITHUB_TOKEN` inherits + this repository's visibility and access, so in this public repository a + new feature package is public at once; there's no manual "make public" + step (verified at v1.0.0: all 10 packages pull anonymously). This + corrects the "made public by hand" consequence of ADRs 0001 and 0004. A + package created any other way still starts private. - Any other registry still needs both secrets.