Proposal: Managing deployments with `draft` contents

[Aryex]

Summary

Adopt a trunk-based deployment process for this repo: main becomes the single source of truth that auto-deploys on every merge, and unreleased content is hidden by draft flags instead of long-lived staging/release branches.

Goal

The aim is to create a simple deployment management process allow as minimal friction as possible when merging.

• The current two branch process, public and main, creates complication when merging main into public.
• A multi branch approach, where staged changes are kept on their branch, would result in merge conflicts when managing different branches.

Proposal: Continuous integration with draft contents.

The basic flow:

Write docs → PR to main → CI: build + checks → merge →  deploy

Changes are deployed as soon as they land on main.

Truth branch: main

• The source of truth. Auto-deploys on merge.
• Direct pushes disabled; PR-only, with required CI checks (build + link validation).

Unreleased contents:

1. New page: Use Starlight's built-in draft: true frontmatter. Blocks rendering of the page in production build but still visible in pnpm dev. When releasing, create a new PR to flip to draft: false.
2. New subsection of page (e.g., one language tab): Use the new <Draft> component (src/components/Draft.astro). Similar to draft frontmatter, it blocks rendering the section in production build.

All draft contents should be marked with a note on when to release them. This allow maintainer to keep track and release changes accordingly.

Proposed Process

For changes ready to be deployed:

1. Create PR onto main for doc changes.
2. Merge when ready.
3. Auto deploy once merge.

For changes not yet ready (ex: waiting for a release):

1. Create a PR onto main.
2. Use the draft of <Draft> on appropriate contents
3. Leave a comment on why they are in draft so they we know later to reveal them.

Examples

1. Adding Client Side Caching Docs

• Core clients add Client Side Caching support .
• Docs page created and merged onto main with draft: true with a comment For release 2.5.
• Once valkey-glide 2.5 has been release, create a new docs PR to release all 2.5 docs.

2. Updating Ruby CSC Docs

• The ruby client add CSC support.
• Add Ruby code examples to existing page.
• Wrap Ruby code examples in <Draft> element with a comment For release 1.2.
• Once Ruby release 1.2 is out, create a new docs PR to release their docs.

3. Hot fix Ruby docs

• We found an issue with ruby docs
• Create a PR and fix the issue.
• Merge and changes are deployed immidiately.

Trade-offs

• Unreleased content is visible in the repo (hidden from the site, not secret).

Todo

• We need to implement <Draft> element which should be simple.
• Change existing github workflows.
• Update CONTRIBUTING with the new process.

[Aryex]

After some discussions, it was mentioned that GLIDE clients aim to release at the same time thus we don't need to worry about managing contents on different release schedules. This simplify our needs and we agreed on a hybrid model. The agreed process added to the PR.