Maintainer notes

For our main contributing page covering license agreements, code of conduct and more, see Contributing. This page is for maintainers only.

Publishing a release

These notes are WIP for creating a release from a local copy of the repo. These instructions assume the release is 0.14.2, if not adjust accordingly.

1. Change directory to your local Docsy repo.

2. Create or update a changelog entry for 0.14.2.

   • The section should provide a brief summary of breaking changes using the section template at the end of the file.
   • Ensure to remove the UNRELEASED note, if still present.
   • You’ll create a new section for the next release in a later step.

3. Update the release report blog post for 0.14.2, if any.

   • Remove draft status.
   • Set date (or lastmod if already published) to today’s date.

4. Run npm run fix.

   Note

   This command might update the version in package.json via fix:version, but you can ignore this change since you’ll be setting the version explicitly in the next step.

5. Update Docsy version to 0.14.2 using the following from a (bash or zsh) terminal.

   • First set the VERSION variable; we use it throughout the steps below.

     VERSION=0.14.2
     

   • Then run the set:version script.

     Docsy is probably already at 0.14.2-dev, so you can run:

     npm run set:version
     

     Otherwise, set the version explicitly:

     npm run set:version -- --version $VERSION
     

     Both forms update the version related fields in package.json and docsy.dev/hugo.yaml.

6. Run npm run ci:test, 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.

   • Commit any changes accumulated from the previous steps using this title:

     Release 0.14.2 preparation
     

   • Create a PR (with version-checks disabled) using the following command that will open a PR-creation page in your browser:

     export SKIP_VERSION_CHECK=1
     gh pr create --web --title "Release $VERSION preparation" \
       --body "- Contributes to #<ADD-RELEASE-PREP-ISSUE-HERE>"
     

   • Use the web interface to fill in the PR details.

   • Submit the PR.

8. Test the PR branch from selected sites, and push any required adjustments.

   • If the test site uses Docsy as a Git submodule:

     cd themes/docs
     git fetch
     git switch -t REPO/BRANCH-NAME # e.g. chalin/chalin-m24-0.14.0-pre-release
     

9. Get PR approved and merged.

10. Pull in main to get the last PR.

11. Test Docsy from main, from the docsy-example repository for example.

12. Ensure that you’re:

    • On the default branch, main
    • At the commit that you want to tag as 0.14.2

13. Create the new tag for 0.14.2.

    • Set the REL variable to the release version or use the VERSION variable if you set it in the previous step.

      REL=v${VERSION:-0.14.2}
      echo "REL=$REL"
      

    • Create the new tag.

      git tag $REL
      

    • Double check:

      git tag --sort=-creatordate | head -3
      

14. Push the new tag: either to all remotes at once, or one at a time.

    Push to all remotes

    • List the remotes so you know what you’ll be pushing to:

      git remote
      

    • Check that the push-all-remotes alias is defined, and if not, define it:

      git config --global --list | grep alias.push-all-remotes
      

      Define a `push-all-remotes` alias

      First check if the push-all-remotes alias is already defined:

      git config --global --list | grep alias.push-all-remotes
      

      If not, define the alias:

      git config --global alias.push-all-remotes \
        '!f() { for r in $(git remote); do (set -x; git push "$r" "$1"); done; }; f'
      

      Note

      You only need to define the alias once. Omit --global from the command above to make the alias available only in the current repository rather than all repositories.

    • If you have git hooks enabled that auto-update the Docsy package version, disable the hook check for now:

      export SKIP_VERSION_CHECK=1
      

    • Push the tag to the remotes:

      $ git push-all-remotes $REL
      + git push origin v0.14.2
      * [new tag]         v0.14.2 -> v0.14.2
      + git push upstream v0.14.2
      * [new tag]         v0.14.2 -> v0.14.2
      ...
      

    • Sanity check over upstream for example:

      git ls-remote --tags upstream | grep $REL
      

    • Unset the SKIP_VERSION_CHECK variable when you’re done:

      unset SKIP_VERSION_CHECK
      

    Push to a single remote

    • Push to a single remote at a time, such as upstream:

    git push upstream $REL
    

    • Sanity check over upstream for example:

      git ls-remote --tags upstream | grep $REL
      

15. Fast-forward the deploy/prod branch so that it points to the same commit as main:

    git checkout deploy/prod && \
    git merge --ff-only main
    git push-all-remotes deploy/prod
    

    This 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.

    • Tag: select new release tag v0.14.2

    • Release title: use the release version.

      v0.14.2
      

    • Click Generate release notes to get the release details inserted into the release notes text area.

    • Add the following text atop the generated release notes:

      ## Release summary
      
      - [Release 0.14.0 report and upgrade guide][blog-post]
      - [Changelog v0.14.2][changelog] entry
      
      [blog-post]: <https://www.docsy.dev/blog/2026/0.14.0/>
      [changelog]: <https://www.docsy.dev/project/about/changelog/#v0.14.2>
      

    • Select Create a discussion for this release.

18. Publish the release: click Publish release.

19. Test the release with a downstream project and/or the docsy-example site.

20. If you find issues, determine whether they need to be fixed immediately. If so, get fixes submitted, reviewed and approved. Go back to step 1 to publish a dot release.

If all is well, release the Docsy example as detailed next.

Docsy example release

The steps you follow are similar to the ones above for the Docsy release, but with the following modifications:

1. Update the version of the example to 0.14.2:

   VERSION=0.14.2
   npm run set:version:example -- --version $VERSION
   

2. Perform step 6 onwards as above to test, create a PR, create a release and publish it with one difference:

   • To create a new release draft, visit Docsy-example release draft.
   • Once the deploy/prod branch has been updated, wait for the production deploy to complete and check that example.docsy.dev has been updated to the new release.

Post Docsy-release followup

Assuming that both the Docsy and Docsy-example releases v0.14.2 have been successfully deployed, and that at least one other project has been successfully tested with the new release, then perform the following actions before any further changes are merged into the main branch:

1. Update the package version to a dev ID for Docsy and Docsy-example:

   $ npm run -s fix:version
   ✓ Updated package.json version: 0.14.3 → 0.14.3-dev+003-over-main-cf4f514b
   ✓ Updated docsy.dev/config/_default/params.yaml version: 0.14.3 → 0.14.3-dev
   ✓ Updated docsy.dev/config/_default/params.yaml tdBuildId: (none) → 003-over-main-cf4f514b
   ...
   $ npm run -s fix:version:example
   ...
   

2. In the Changelog:

   • Create a new entry for the next release by copying the ENTRY TEMPLATE at the end of the file.

   • Fix the new release URL, which ends with latest?FIXME=..., so that it refers to the actual release, now that it exists.

3. Submit a PR with your changes, using a title like:

   Set version to 0.14.2
   

4. Get PR approved and merged.

Release helper scripts

• NPM scripts: fix:version, fix:version:example, and set:version.
• scripts/get-build-id.sh: Generates build ID from git describe (empty on tags).
• scripts/set-package-version/index.mjs: Low-level version manager. See script help for usage.