CloudHost/zonemaster.es
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
816a4757c0dffc68fe1849ff29de3da91cb81813
zonemaster.es/zonemaster/docs/internal/maintenance/ReleaseProcess-release.md
Malin 8d4eaa1489 feat: add full Zonemaster stack with Docker and Spanish UI 
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI)
- Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend
- Dockerfile.gui: Astro static build served via nginx
- docker-compose.yml: backend (internal) + frontend (port 5353)
- nginx.conf: root redirects to /es/, /api/ proxied to backend
- zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-21 08:19:24 +02:00

21 KiB
Raw Blame History

Release process - Release

Table of contents

1. Overview

The steps in this document executes the actual release. They assume that development, the preparation steps and the QA testing have been concluded. To run the steps below a build system is needed. See Build Environment Preparation for how to set it up.

Note: Normally, the develop branch version of this document should be used.

(Top)

2. Applicable components

Every applicable step below should be run for each component. If there are no changes in a component (no release) it should be skipped. The main component (Zonemaster/Zonemaster) can never be skipped and should always be released. The components should be released in the following order:

  • zonemaster-ldns
  • zonemaster-engine
  • zonemaster-cli
  • zonemaster-backend
  • zonemaster-gui
  • Zonemaster/Zonemaster

(Top)

3. Updates to repositories

All updates to develop branch and master branch should go via pull requests following the usual process. That is just assumed here.

(Top)

4. Determine the new version number

The version number of the new release should be chosen according to Versions and Releases document.

Each component listed above should have its version number. The Zonemaster Product (Zonemaster/Zonemaster) version number also refer to the version of the other components.

(Top)

5. Update the Changes files

Any changes since the last release must be documented in the Changes files. Refer to any GitHub issues or pull requests related to the change by the issue number or pull request number or both.

The updates to the Changes file are done to the develop branch.

(Top)

6. Set version number for Perl modules

This step does not apply to Zonemaster/Zonemaster and Zonemaster-GUI

The version numbers is to be set in these Perl modules in the develop branch:

(Top)

7. Set version number for GUI

This step applies to Zonemaster-GUI only

Update the following files in the develop branch of Zonemaster-GUI:

  • package.json
    • In the top of the file, the version is given after "version".
    • The file package-lock.json is ignored

Update the following file in the develop branch of Zonemaster/Zonemaster:

The update of the installation document can preferably be done in the same pull request as the update of the Changes file for Zonemaster/Zonemaster

(Top)

8. Update Makefile.PL with required version

This section is relevant for Zonemaster-Engine, Zonemaster-CLI and Zonemaster-Backend.

If needed, update Makefile.PL in the develop branch. See Appendix A for how the version number should be specified in Makefile.PL.

Usually let Zonemaster-Engine, Zonemaster-CLI and Zonemaster-Backend, respectively, require the version of other the Zonemaster components (see below) included in this release, because that is what has been tested.

If a component will not be updated by this release, then it can continue to require the previous version unless it must be change to resolve some issue, and then the version of the requiring component must also be updated.

In Zonemaster-Engine Makefile.PL set the lowest version of Zonemaster-LDNS that Zonemaster-Engine requires. E.g.

requires 'Zonemaster::LDNS'   => 2.001;

In Zonemaster-CLI Makefile.PL and Zonemaster-Backend Makefile.PL, set the minimum required versions of Zonemaster-LDNS and Zonemaster-Engine. E.g.

requires 'Zonemaster::Engine' => 4.000;
requires 'Zonemaster::LDNS'   => 2.001;

(Top)

9. Create a clean Git working area of develop branch

Make sure that you have checked out the develop branch and that your clone is up-to-date.

git fetch --all
git branch

Empty the submodule area (LDNS). Zonemaster-LDNS only.

git submodule deinit -f ldns

Make sure your working directory is clean.

git status --ignored

Or clean it.

git clean -dfx
git reset --hard

(Top)

10. Produce distribution tarballs

This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster

See Release process - Create Test Distribution, sections 4-6 for more details and what warnings that could be ignored.

perl Makefile.PL --no-ed25519 # For Zonemaster-LDNS:

perl Makefile.PL              # For other components

make all                      # For all
make distcheck
make dist

(Top)

11. Produce distribution zip file

This section is relevant for Zonemaster-GUI only.

For this you need a build environment for Node.js, on which you create the zip file. See Release process - Create Test Distribution, sections 7 for more details

Build the distribution zip file:

npm install
npm run build
npm run release

If you get building errors, repeat the nvm commands in build environment for Node.js first.

You can ignore warnings and security fixes at this stage, and do not run any npm audit fix.

The distribution zip file is in the root level of the zonemaster-gui folder. Its name is zonemaster_web_gui_v0.0.0.zip with correct version.

(Top)

12. Update Zonemaster repository main README.md

This section is relevant for Zonemaster/Zonemaster only.

If needed, update the following section of the Zonemaster repository main README.md file in develop branch:

  • Notable bugs and issues

(Top)

13. Generate documents and check public documents

The two sub-sections here are relevant for Zonemaster/Zonemaster only.

13.1. Generate documents

If no files in neither Zonemaster/Zonemaster nor Zonemaster-Engine have been updated this section can be skipped.

  1. On a computer install Zonemaster-LDNS and Zonemaster-Engine using the distribution packages created for this release.
  2. Clone Zonemaster/Zonemaster and check out the develop branch. The working area should be clean (git status --ignore).
  3. Go to the utils directory and create the files as documented in the README.pm file in that directory.
  4. If any of the created files has been updated (git status) then it should be added to the develop branch via a pull request.
  5. No reviewer or approval is required for this change.

13.2 Check public documents

The step above, 13.1, should be completed (merged to develop branch) before this step is run to avoid double errors.

Prior to this step mdbook-linkcheck must be installed (see Build environment preparation). Run from the Zonemaster/Zonemaster repository (develop branch checked out):

mdbook-linkcheck -s docs/public/
  1. If any error is reported, correct the file or files.
  2. Add changes to the develop branch via a pull request.
  3. No reviewer or approval is required for this change.
  4. Repeat the command after merging the changes to verify that the found errors have been resolved.

(Top)

14. Upload to CPAN

This section is not relevant for Zonemaster-GUI or Zonemaster/Zonemaster.

For each component that is to be updated in this release, publish the distribution tarball created following this document on CPAN. Currently we use the organizational account ZNMSTR on PAUSE for doing this.

(Top)

15. Merge develop branch into master

For the steps in this section, it is assumed that the git "remote" which is called "origin" points at "zonemaster/zonemaster.git", "zonemaster/zonemaster-ldns.git" etc. This is default when making a git clone. Use git remote -v to verify that.

Make sure you're up to date and your working directory is completely clean:

git fetch origin
git status --ignored

Note: To throw away any and all changes to tracked and untracked files you can run git clean -dfx ; git reset --hard.

Verify if there are commits on master since last release:

TAG=$( git tag --list --sort=-creatordate | head -n 1 )
# count the number of commits in master since last release and
# if the count is not 0, look for commits belonging to master and develop
[ $(git rev-list --count $TAG..master) -ne 0 ] && cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d

If commits are returned by this previous command, some additional work is needed. See Appendix B for that.

Finally once master branch is ready, create a pull request from develop into master and merge it. No reviewer or approval is required for this update.

(Top)

16. Create Docker images and upload image to Docker Hub

  1. Follow the instructions in Create Docker Image to build a Docker images.
  2. Upload the Zonemaster-CLI image to Docker Hub for Zonemaster using the instructions in Create Docker Image.

(Top)

17. Tag the release with git

For each repository, go to "releases" in GitHub and select "draft a new release". Use the version number as tag and create a new release description. Use the section of Changes file for the relevant release and make links of everything that can have meaningful links, especially make links to issues and PRs.

For Zonemaster-GUI, add the distribution zip file as attached file to the release description in GitHub.

Always release the Zonemaster Product (Zonemaster/Zonemaster) as the last step.

The releases pages:

(Top)

18. Announce the release

  1. Send emails to the mailing lists zonemaster-users and zonemaster-announce (the same email content will usually work fine). Always refer to the Github release page, but the URL with the version.
  2. Forward the zonemaster-users email to the mailing list zonemaster-group.
  3. Create an announcement on the Zonemaster discussion forum on GitHub.
    1. Choose "New discussion"
    2. Select "Announcements"
    3. Use Zonemaster version as title
    4. Use the body of the Github release page for the version as the body of the announcement.

(Top)

19. Merge master into develop

Create a pull request from master on github back into develop and merge it. No review or approval is required for this update.

(Top)

20. Clean-up on discussion forum

On the Zonemaster discussion forum on GitHub, close the announcement of the previous version. Also close discussions that are not relevant to keep open, i.e. resolved issues and other questions that have been answered and some time has passed with no further follow-up questions.

(Top)

21. Clean-up on Github related to the release

For each repository:

  • Zonemaster/Zonemaster
  • zonemaster-ldns
  • zonemaster-engine
  • zonemaster-cli
  • zonemaster-backend
  • zonemaster-gui

Do the following steps related to the release:

  1. Check the issues with the release as milestone.
    1. Close if completed or irrelevant.
    2. Else move to a new milestone.
  2. Verify that the milestone of the release is 100% complete.
    1. Close if completed.
    2. Else make it complete and then close it.
  3. Verify that there are milestones for at least two of the next standard releases.
    1. If not, create the appropriate vYYYY.x milestones (e.g v2025.1)
    2. Also, if no due date has been chosen, set YYYY-06-15 for the .1 release and YYYY-12-15 for the .2 release.

(Top)

Appendix A on version number in Makefile.PL

As described above, Makefile.PL of Zonemaster-CLI and Zonemaster-Backend, respectively, must be specified with the lowest supported version of Zonemaster::LDNS and Zonemaster::Engine, respectively. Zonemaster-Engine must have that of Zonemaster::LDNS.

The versions of Zonemaster::LDNS and Zonemaster::Engine are defined in the format vX.Y.Z and it is important how this is written in Makefile.PL.

For lowest risk of error follow the following steps:

  1. Expand the version number with leading zeros on second ("Y") and third ("Z") level. Remove the leading v and the second and third dots. E.g. v2.1.2 = 2.001002.
  2. Decide if the third level can be skipped, e.g. v2.1.2 > 2.001.
  3. Please note that if the version in Makefile.PL is set to 2.1 then the interpretation is that the "v" version is v2.100.0 or greater.

When specifying the version of Zonemaster::LDNS and Zonemaster::Engine in Makefile.PL always use the expanded format, e.g. 2.001002 or 2.001 depending on the need.

For other libraries, other formats may be correct. If the version of the library only has two levels ("X.Y") then other rules apply. Also note that the version in Zonemaster::Backend is specified as X.Y.Z without the "v", which may affect the version comparison.

(Top)

Appendix B on reverting commits

When merging develop into master a merge conflict could occur. This is due to the fact that some commits belongs to both branches. Usually this is the result of a merge request in master branch instead of develop during development. Once this happens, the faulty merge is reverted on master and merged into develop. Depending on the steps chosen, this could lead to having the same commit in both branches.

To avoid merge conflict, it is necessary to revert the revert commits on master (yes revert of the revert) before merging develop into master.

How would the release officer find the commit to revert?

Usually a revert commit contains a predefined subject (or title) looking like: Revert "subject of the reverted commit".

One can looks for commits with this string using a command like:

TAG=$( git tag --list --sort=-creatordate | head -n 1 )
for c in $(cat <( git rev-list $TAG^2..develop ) <( git rev-list $TAG..master ) | sort | uniq -d); \
    do git log --oneline --grep="Revert \"$(git show -s --pretty=%s $c)\"" $c~..master ^$TAG ; \
    done

Or look for them visually with:

git log --oneline --graph $TAG..master

Once found, either revert each commits (git revert <commit> ...) or the merge commit.

How would the release officer know the parent number to revert?

In case one reverts the merge commit, since it was merged into master, the parent number is 1.

git revert -m 1 <merge commit>

(Top)

Reference in New Issue View Git Blame Copy Permalink