docs: record close-out decisions (DF16)

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/<tool>/` 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/<id>/README.md` files.
+  `src/<id>/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.

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<x.y.z>` 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
 

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
 

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,12 +48,19 @@ 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.
 - A feature package that already exists 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.
+- 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.