elastic / elastic/docs-builder
Late changelog notes on S3 never appear on CDN changelog pages
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
A `changelog note` for Elastic Cloud Enterprise 4.2.0 landed in S3 but never appeared on `{changelog}` pages that use `:cdn:`.
### What happened?
I created a changelog note for Cloud Enterprise 4.2.0 after the parent bundle had already shipped. The scrubber wrote `bundle/cloud-enterprise/cloud-4.2.0.amend-notes.yaml` in the public bucket `elastic-docs-v3-changelog-bundles`.
The ECE release-notes page already uses `:cdn: cloud-enterprise`. `docset.yml` already lists that product under `release_notes:`. I expected the note to be published here: https://www.elastic.co/docs/release-notes/cloud-enterprise
#### AI analysis
I think the problem is that the `{changelog}` directive does not list objects in S3. At startup it only fetches files named in the product registry. The live registry in this case (`generated_at`: `2026-08-25T13:56:49.9548117+00:00`) lists `cloud-4.2.0.yaml`, `cloud-4.1.1.yaml`, `cloud-4.1.0.yaml`, and `cloud-ui-4.1.0.yaml`. It does not list `cloud-4.2.0.amend-notes.yaml`.
`ScrubberProcessor.ProcessAsync` rebuilds `bundle/{product}/registry.json` only for private-bucket bundle keys. A note upload is a changelog-pool key, so that rebuild never runs. `NoteAmendReconciler` then writes `{parent}.amend-notes.yaml` to the public bucket. Public-bucket writes do not retrigger the Lambda. The sidecar can exist while the registry stays stale. The shallow map `bundle/registry.json` is also patched before that write.
`NoteAmendReconcilerTests.LateNote_NoBundleAmendYet_WritesAmendNotesSidecar` asserts the sidecar write. It does not assert that `registry.json` lists the file.
A second bug remains after the registry lists the sidecar. `BundleAmendMerger` treats `.amend-notes.yaml` as an amend sidecar. `BundleLoader.GetParentBundlePath` uses a private regex `\.amend-\d+\.ya?ml$` that only matches numbered amends such as `.amend-1.yaml`. That regex does not match `.amend-notes.yaml`. Parent resolution then treats `cloud-4.2.0.amend-notes.yaml` as its own parent. The loader does not merge the sidecar into `cloud-4.2.0.yaml`. `BundleLoaderFromContentTests` only covers `.amend-1.yaml`.
Default `:type:` still hides `known-issue`, `breaking-change`, and `deprecation`. Check the note type after discovery works.
The scrubber should rebuild the product registry and the shallow map after it writes or deletes an amend-notes sidecar. `BundleLoader` should reuse `BundleAmendMerger.GetParentBundlePath`.
Related, not a duplicate: [elastic/docs-builder#4072](https://github.com/elastic/docs-builder/issues/4072) is about unpublishing a note that already shipped.
### How can we reproduce it?
1. Publish a parent bundle so `bundle/{product}/registry.json` lists it. Here that file is `cloud-4.2.0.yaml` for `cloud-enterprise`.
2. After that bundle exists, run `docs-builder changelog note` for the same product and version. Upload so the scrubber runs.
3. Confirm the public object `bundle/{product}/{parent}.amend-notes.yaml` exists.
4. Fetch the product registry from the CDN. The sidecar file name is absent.
5. Serve a docset whose `{changelog}` block uses `:cdn:` for that product. The note does not appear.
Any private-bucket event under `bundle/{product}/` rebuilds the registry from the public listing. That would pick up a sidecar that is already there. It does not fix the next note upload.
### Version or commit
Observed against docs-builder from source at `deff47cd7aa878e6c6d2507735644d72fc104f7d` while serving `elastic/cloud`. The live CDN registry is dated `2026-08-25`.
Contributor guide
Research direction
Start with ScrubberProcessor.ProcessAsync, NoteAmendReconciler, BundleAmendMerger.GetParentBundlePath, and BundleLoader.GetParentBundlePath. Run NoteAmendReconcilerTests.LateNote_NoBundleAmendYet_WritesAmendNotesSidecar and inspect BundleLoaderFromContentTests; add coverage for registry discovery and amend-notes parent resolution. Done means late notes appear through CDN changelog pages, including supported note types, and sidecar writes or deletes keep registries current.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, csharp
- Domain
- backend, cloud, release
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100