Clarify release process and branch model

Author: chalin

docsy.dev/config/_default/params.yaml

@@ -7,7 +7,7 @@
 #   status: archived # Then fetch include
 
 version: &docsyVersion 0.14.3-dev
-tdBuildId: 012-over-main-bb43d873
+tdBuildId: 013-over-main-38978ffc
 versionLatest: &versionLatest v0.14.2
 version_menu: *docsyVersion
 version_menu_pagelinks: true

docsy.dev/content/en/project/about/maintainer-notes.md

@@ -57,13 +57,20 @@ accordingly.
       ```
 
       Both forms update the `version` related fields in [package.json][] and
-      [docsy.dev/hugo.yaml][].
+      [docsy.dev/config][] files.
 
 6.  <a id="ci-test-step">Run `npm run ci:test`</a>, which runs `ci:prepare` and
     more to ensure that, e.g., vendor assets and [go.mod] dependencies are
     up-to-date, etc.
 
 7.  **Submit a PR with your changes**.
+    - Set the `BASE` variable to the target branch: `main` if this is a stable
+      release, and `release` for patch releases.
+
+      ```sh
+      BASE=main
+      ```
+
     - Commit any changes accumulated from the previous steps using this title:
 
       ```text
@@ -76,6 +83,7 @@ accordingly.
       ```sh
       export SKIP_VERSION_CHECK=1
       gh pr create --web --title "Release $VERSION preparation" \
+        --base $BASE \
         --body "- Contributes to #<ADD-RELEASE-PREP-ISSUE-HERE>"
       ```
 
@@ -94,12 +102,12 @@ accordingly.
 
 9.  **Get PR approved and merged**.
 
-10. **Pull in `main`** to get the last PR.
+10. **Pull the PR** to get the last changes.
 
-11. **Test Docsy from main**, from the [docsy-example][] repository for example.
+11. **Test Docsy** from [docsy-example][], for example.
 
 12. **Ensure** that you're:
-    - On the default branch, `main`
+    - On the target `$BASE` branch
     - At the commit that you want to tag as {{% param version %}}
 
 13. **Create the new tag** for {{% param version %}}.
@@ -215,24 +223,28 @@ accordingly.
 
     </details>
 
-15. Fast-forward the [deploy/prod][] branch so that it points to the same commit
-    as `main`:
+15. Update the [deploy/prod][] branch from `$BASE`.
+
+    For stable releases from `main`, use:
 
     ```sh
-    git checkout deploy/prod && \
+    git checkout deploy/prod
     git merge --ff-only main
     git push-all-remotes deploy/prod
     ```
 
-    This will trigger a production deploy of the website.
+    For patch releases from `release`, selectively merge from `$BASE`.
+
+    The branch update will trigger a production deploy of the website.
 
 16. Wait for the production deploy to complete and check that [docsy.dev][] has
     been updated to the new release.
 
 17. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
-    - **Target**: select the `deploy/prod` branch.
+    - Visit [tags][] to find the new release tag v{{% param version %}}.
 
-    - **Tag**: select new release tag v{{% param version %}}
+    - Select Create a new release from the v{{% param version %}} tag dropdown
+      menu
 
     - **Release title**: use the release version.
 
@@ -332,7 +344,8 @@ before any further changes are merged into the `main` branch:
 [deploy/prod]: <{{% param github_repo %}}/tree/deploy/prod>
 [docsy-example]: <{{% param github_repo %}}-example>
 [docsy.dev]: <{{% _param baseURL %}}>
-[docsy.dev/hugo.yaml]: <{{% param github_repo %}}/blob/main/docsy.dev/hugo.yaml>
+[docsy.dev/config]: <{{% param github_repo %}}/blob/main/docsy.dev/config/>
 [Draft a new release]: <{{% param github_repo %}}/releases/new>
 [go.mod]: <{{% param github_repo %}}/blob/main/go.mod>
 [package.json]: <{{% param github_repo %}}/blob/main/package.json>
+[tags]: <{{% param github_repo %}}/tags>

docsy.dev/content/en/project/build/git-repo.md

@@ -1,6 +1,6 @@
 ---
-title: Git repository information
-linkTitle: Git repos
+title: Git repo info and branch model
+linkTitle: Git repos and branches
 cSpell:ignore: hotfixes
 ---
 
@@ -13,54 +13,91 @@ Docsy:
 - **Website** in the `docsy.dev` directory. The website uses the Docsy theme, of
   course, with extra styling.
 
+These two projects are kept in sync at release points, but they may diverge
+between releases, usually to allow the website to ship doc content and UX
+improvements without forcing a theme release.
+
 The main Docsy example site is [Goldydocs], located in the [Docsy example site
 repository][].
 
 ## Branch model
 
-Both the Docsy and Goldydocs repositories use the same branch model:
+This repository's branch model is as follows:
 
-- `main`: development branch
-  - All feature work and documentation updates land here first.
-  - Source of the _leading-edge_ theme and website versions.
+- `main`: development branch for the next theme release and next site content.
+- `release`: release and maintenance branch for the current stable theme version
+- Publishing branches used by Netlify:
+  - `deploy/prod`: production site for the current stable release docs.
+  - `doc-rooted`: production branch for the doc-rooted site variant.
+  - These branches determine what is published. They are not feature development
+    branches.
 
-- `deploy/*`: publishing branches used by Netlify
-  - `deploy/prod`: production site
-  - `deploy/docs-only`: docs-only site variant
-  - These branches determine what is published. They are not development
-    branches. Changes must originate from `main` and are typically
-    fast-forwarded here.
+The Goldydocs repo has the same model, except for `doc-rooted` which is not
+used.
 
 ### Tags
 
-- Tags are used for **official theme releases**
-- Tags are attached to `main` commits, which are shared by `deploy/prod` since
-  the two branches sync on releases.
+- Tags are used for **official theme releases**.
+- Tags are created from `release`.
+
+### Workflow
+
+#### General workflow
+
+1. Theme and site work is done on `main`.
+
+2. When ready to release:
+   - Stable release: fast-forward merge from `main` to `release`.
+   - Patch release: create and merge a release PR from `main` to `release`,
+     e.g., by cherry-picking relevant commits.
+
+3. Publish site updates:
+   - Fast-forward `deploy/prod` from `main` when possible.
+   - Otherwise (usually because of `release` was patched),
+
+   - Bring release-facing site updates (for example changelog and release blog
+     updates) onto `main` from `release`.
+
+4. Netlify deploys from `deploy/prod` and `doc-rooted`.
+
+This keeps theme releases and site deploys coordinated, but not tightly coupled.
+
+#### Patch release workflow
+
+For patches to the theme or website, generally prefer making the changes to
+`main` first, though you can apply them to `release` then merge back to `main`.
+Assuming the former, the patch-release workflow is as follows:
 
-### Release flow
+1. Cherry-pick relevant commits from `main` to `release`.
+2. Create a and merge a release PR from `main` to `release`.
+3. Bring release-facing site updates (for example changelog and release blog
+   updates) back onto `main` from `release`.
+4. Update `deploy/prod` from `main` by fast-forward merging if possible, if not
+   then selectively bring in release relevant changes.
 
-1. Work merges into `main`.
-2. At release:
-   - Tag the release commit on `main`.
-   - Fast-forward `deploy/prod` to that same commit.
-3. Netlify deploys from `deploy/prod`.
+### Branch sync and invariants
 
-This keeps history mostly linear.
+`release`:
 
-### Hotfixes (rare)
+- The theme release and maintenance branch.
+- Theme tags come from this branch.
+- Flow is usually from `main` to `release` via fast-forward merge, when
+  possible, cherry-picking otherwise (on patch releases)
+- Periodically, after a patch release, record branch ancestry without taking
+  content by periodically running `git merge -s ours release` on `main`.
 
-- If a fix lands on `deploy/prod`, it must be forward-merged or cherry-picked to
-  `main`.
-- Next promotion fast-forwards `deploy/prod` to `main` again.
+`deploy/prod`:
 
-Invariant: `deploy/prod` should converge back to `main` ASAP.
+- Reflects the current release docs baseline
+- Can include site-only improvements that are compatible with the current
+  release
 
 ## Why this model?
 
-- Preserves a clean, mostly linear history.
-- Allows website production deploys on release commits (and a rare hotfix).
-- Keeps `main` free for ongoing theme + site development.
-- Maintains clear, immutable release points for theme consumers via tags.
+- Keeps stable theme releases predictable while `main` moves quickly.
+- Lets the website ship docs UX improvements without forcing a theme release.
+- Preserves clear release tags for theme consumers.
+- Keeps branch responsibilities explicit for a small maintainer team.
 
 [Goldydocs]: <{{% param example_site_url %}}>
 [Docsy example site repository]: <{{% param github_repo %}}-example>

docsy.dev/static/refcache.json

@@ -763,6 +763,10 @@
     "StatusCode": 206,
     "LastSeen": "2026-02-11T11:19:01.944819-05:00"
   },
+  "https://github.com/google/docsy/blob/main/docsy.dev/config/": {
+    "StatusCode": 206,
+    "LastSeen": "2026-02-18T03:26:03.119227-05:00"
+  },
   "https://github.com/google/docsy/blob/main/docsy.dev/content/en/_index.md": {
     "StatusCode": 206,
     "LastSeen": "2026-02-11T11:18:49.8453-05:00"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.14.3-dev+012-over-main-bb43d873",
+  "version": "0.14.3-dev+013-over-main-38978ffc",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",