Skip to content

Update changelog docs for CDN TTL details#3679

Open
lcawl wants to merge 7 commits into
mainfrom
changelog-ttl
Open

Update changelog docs for CDN TTL details#3679
lcawl wants to merge 7 commits into
mainfrom
changelog-ttl

Conversation

@lcawl

@lcawl lcawl commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

This PR updates the changelog documentation (e.g. https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/changelog) related to issues I've hit when doing recent Serverless releases.
In particular, it adds more details about:

  • The amount of time you need to wait between uploading a file to the CDN and using it in a bundle.
  • The ways you can force the bundle to use local files instead of CDN files
  • The reasons why you might choose to have your changelogs in both the repo and the CDN

@lcawl lcawl added the documentation Improvements or additions to documentation label Jul 21, 2026
@lcawl
lcawl marked this pull request as ready for review July 21, 2026 18:36
@lcawl
lcawl requested review from a team as code owners July 21, 2026 18:36
@lcawl
lcawl requested a review from reakaleek July 21, 2026 18:36

If you're making last-minute changes and ad hoc releases with changelog files that aren't uploaded to the public CDN yet, pass the `--force-local` command option to `changelog bundle`.

If you rely on CDN sourcing, wait at least an hour after your final changelog updates before you create the bundle.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why is this an hour @cotti ?

You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file.
:::

## Upload changelog files [upload]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't document folks manually uploading changelogs on the command line.

Everything should be automated through our github actions and the timing of publishing these should not be arbitrary.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the need for that will persist for the ad hoc releases and things like known issues, security issues, feature announcements, etc that aren't ncessary tied to a PR or release. AFAIK those aren't uploaded automatically yet.

Changelog entries are uploaded into `changelog/{org}/{repo}/{branch}/{filename}`.

:::{note}
It can take between 60 seconds to an hour before updates appear in the public CDN.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bug, lets zoom in

@cotti

cotti commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Heads up: the "wait up to an hour" behavior this PR documents is being removed at the source. elastic/docs-infra#355 disables CloudFront caching entirely for the changelog-bundles CDN (the 1-hour default TTL was the whole delay — the scrubber Lambda sets no Cache-Control, so every object, including registry.json and entry YAML, was cached for the full hour).

Once that lands, the only delay between upload and public visibility is the private-bucket → SQS → scrubber-Lambda pipeline, which is seconds — so the TTL notes here ("minimum 60 seconds", "wait at least an hour after last-minute changelog updates before bundling") will be obsolete and worth rewording to describe just the scrubber pipeline delay. The entry-sourcing / --force-local documentation is unaffected and still useful for not-yet-uploaded local files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants