Git repository information

Monorepo

The Docsy repository is effectively a monorepo containing the Docsy:

• Theme at the repo root
• Website in the docsy.dev directory

Branch model

The repo has two main branches:

• main: development branch

  • All feature work and doc updates land here first.
  • Source of leading-edge theme version for downstream sites.

• release branch

  • Published & supported line of the theme and website.
  • Website production builds are deployed from this branch via Netlify.
  • An ancestor of main most of the time, diverged due to hotfixes on occasion.

No rebases and no history rewriting for either branch.

Tags

• Tags are used for official theme releases
• Tags are attached to main commits, which are shared by release since the two branches sync on releases.

Release flow

1. Work merges into main.
2. At release:
   • Tag the release commit on main.
   • Fast-forward release to that same commit.
3. Netlify deploys from release.

This keeps history mostly linear.

Hotfixes (rare)

• If a fix lands on release, it must be forward-merged or cherry-picked to main.
• Next promotion fast-forwards release to main again.

Invariant: release should converge back to main ASAP.

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.