Release preparation

Checklist of steps to follow when preparing a new release of the DITA-OT documentation.

High-Level Process

1. Finalize docs content.

2. Use Git Flow to finish the release branch in the docs repo:

    git flow release finish RELEASE
   

   This performs the following steps automatically:

   • merges the release branch back to master
   • tags the merge commit on the master branch
   • merges the release tag into develop

3. Update the docsrc submodule pointer in the main dita-ot repo.

4. Use Git Flow to finish the release branch in the main dita-ot repo:

   git flow release finish RELEASE
   

5. Edit release on https://github.com/dita-ot/dita-ot/releases.

   For _Release Notes_, see [dita-ot.org/3.7/release-notes/#v3.7](https://www.dita-ot.org/3.7/release-notes/#v3.7).

6. Update project website (see Release preparation in the project website wiki).

7. Publish artifacts to Sonatype.

Docs Release Process

1. Update Release Notes based on the list of resolved issues in the release milestone.

2. Increment (verify/update) version numbers in key-definitions.ditamap
   (compare w/ version setting in dita-ot build.gradle):

   • version &
   • release keys
   • version number in samples/docker/Dockerfile

3. Update the list of contributors for the target release based on git-extras output from dita-ot repo:

   git summary 3.7..
   

4. Run the docs build via the Gradle wrapper to generate/update the messages & parameters topics, HTML & PDF output:

   ./gradlew
   

5. Run the site build task in the docs repo, output to dita-ot-website/dev.

   ./gradlew site -PoutputDir=~/dita-ot-website/dev
   

   (For more information, see Building site output in the project website README.)

Post-Release Tasks

1. Close release milestone and related project.

2. Move any remaining unresolved issues to new milestone/project.

3. Remove remote release branch.
   ⚠️ This will close any remaining PRs that target the branch — consider rebasing on develop.

4. Update Wikipedia page with latest release info (at least for major releases)

5. Add release date to Release Notes on develop branch.

6. Manually run the GitHub Action to update the dita-ot Homebrew formula and open a pull request in homebrew-core.

   

7. Manually run the GitHub Action to generate the website release PR.

   

8. Increment the Docker image version in the GitHub Action:

   • dita-ot-action/Dockerfile

   Note

   These steps should now be performed automatically via GitHub Actions

9. Announce the new release via GitHub Discussions.