Release process

This page describes the current status of the release process.

Since 6.30.0, the automated release process is usingGithub Actions.

Since 7.0.0-rc4, the release happens in two phases: First pmd-core with all the languages are released.This allows to release then pmd-designer or any other project, that just depends on pmd-core and thelanguages. And in the second phase, pmd-cli and pmd-dist are released. These include e.g. pmd-designer.

Since 7.15.0, the release scripts changed again, seeGitHub Actions Workflows.Only a full release is supported now, the two phases are gone. If a new pmd-designer is needed, it has to be releasedbefore.

While the release is mostly automated, there are still a few steps, that need manual examination.

Overview

This page gives an overview which tasks are automated to do a full release of PMD. This knowledge isrequired in order to verify that the release was successful or in case the automated process fails forsome reason. Then individual steps need to be executed manually. Because the build is reproducible, thesesteps can be repeated if the same tag is used.

The three main steps are:

• Preparations (which sets the versions and creates the tags) - usedo-release.sh for that
• The actual release (which is automated) - GitHub Actions will build the tags when they have been pushed.
• Prepare the next release (make sure the current main branch is ready for further development)

Preparations

This is the first step. It is always manual and is executed locally. It creates in the end the tag from whichthe release is created.

Make sure code is up-to-date and everything is committed and pushed with git:

$ ./mvnw clean$ git pull$ git status

As a help for the preparation task, the scriptdo-release.sh guides you through the preparation tasksand the whole release process. The script requires a specific source code folder and additional checkouts locally,e.g. it requires that the repopmd.github.io is checked out aside the main pmd repo:

• https://github.com/pmd/pmd ➡️/home/joe/source/pmd
• https://github.com/pmd/pmd.github.io ➡️/home/joe/source/pmd.github.io

The scriptdo-release.sh is called in the directory/home/joe/source/pmd and searches for../pmd.github.io.

Also make sure, that the repo “pmd.github.io” is locally up-to-date and has no local changes.

The Release Notes and docs

Before the release, you need to verify the release notes: Does it contain all the relevant changes for therelease? Is it formatted properly? Are there any typos? Does it render properly?

As the release notes are part of the source code, it is not that simple to change it afterward. While the sourcecode for a tag cannot be changed anymore, the published release notes on the GitHub Releases pages or thenews posts can be changed afterward (although that’s an entirely manual process).

You can find the release notes here:docs/pages/release_notes.md.

The date (date +%Y-%m-%d) and the version (remove the SNAPSHOT) must be updated indocs/_config.yml, e.g.in order to release version “7.2.0”, the configuration should look like this:

pmd:version:7.15.0previous_version:7.14.0date:2025-06-27release_type:minor

The release type could be one of “bugfix” (e.g. 7.15.x), “minor” (7.x.0), or “major” (x.0.0).

The release notes usually mention any new rules that have been added since the last release.

Add the new rules as comments to the quickstart rulesets:

• pmd-apex/src/main/resources/rulesets/apex/quickstart.xml
• pmd-java/src/main/resources/rulesets/java/quickstart.xml

The designer lives atpmd/pmd-designer.Update propertypmd-designer.version inpom.xml to reference a possible new version.Note: This version must exist already. If it doesn’t, a release is not possible.
Usually the version should have been updated before the release already, so that it could be tested.In case, there is no newer pmd-designer version, we simply stick to the latest already available version.

Starting with PMD 7.5.0 we use Dependabot to update dependencies. Dependabot will create pull requestslabeled withdependencies. When we merge such a pull request, we should assign it to the correctmilestone. It is important, that the due date of the milestone is set correctly, otherwise the query won’t findthe milestone number.Then we can query which PRs have been merged and generate automatically a section for the release notes.This is done by the script.ci/tools/release-notes-generate.sh. It needs to be called with theLAST_VERSION and RELEASE_VERSION as parameters, e.g.

.ci/tool/release-notes-generate.sh 7.14.0 7.15.0

This script will directly modify the filedocs/pages/release_notes.md. It can be called multiple timeswithout issues. However, there is activerate limitingof the GitHub API, which might cause issues. If that happens, you need to set the env varGITHUB_TOKEN withyour personal access token. The script will pick it up automatically.A fine-grained token with only “Public Repositories (read-only)” access is enough.

Starting with PMD 6.23.0 we’ll provide small statistics for every release. This needs to be addedto the release notes as the last section (after “Dependency updates”). To count the closed issues and pull requests, the milestoneon GitHub with the title of the new release is searched. It is important, that the due date of the milestoneis correctly set, as the returned milestones in the API call are sorted by due date.Make sure, there is such a milestone onhttps://github.com/pmd/pmd/milestones.This section is updated automatically by.ci/tools/release-notes-generate.sh as well.

Note: the call to “release-notes-generate.sh” is also integrated intodo-release.sh.

Check in all (version) changes to branch main or any other branch, from which the release takes place:

$ git commit -a -m "Prepare pmd release <version>"$ git push

The Homepage

The GitHub repopmd.github.io hosts the homepage forhttps://pmd.github.io.All the following tasks are to be done in this repo.

The new version needs to be entered into_config.yml, e.g.:

pmd:latestVersion:7.15.0latestVersionDate:27-June-2025

Also move the previous version down into the “downloads” section. We usually keep only the last 3 versionsin this list, so remove the oldest version.

Then create a new page for the new release, e.g._posts/2025-06-27-PMD-7.15.0.md and copythe release notes into this page. This will appear under the news section.

Note: The release notes typically contain some Jekyll macros for linking to the rule pages. These macros won’twork in a plain markdown version. Therefore, you need to render the release notes first:

# install bundles needed for rendering release notes and execute renderingcddocsbundle configset--local path vendor/bundlebundleinstallNEW_RELEASE_NOTES=$(bundleexecrender_release_notes.rb pages/release_notes.md |tail-n +6)cd ..RELEASE_NOTES_POST="_posts/$(date-u +%Y-%m-%d)-PMD-${RELEASE_VERSION}.md"echo"Generating ../pmd.github.io/${RELEASE_NOTES_POST}..."cat>"../pmd.github.io/${RELEASE_NOTES_POST}"<<EOF---layout: posttitle: PMD${RELEASE_VERSION} released---${NEW_RELEASE_NOTES}EOF

Check in all (version, blog post) changes to branch main:

$ git commit -a -m "Prepare pmd release <version>"$ git push

The actual release

The actual release is done by changing the versions, creating a tag and pushing this tag. Previously this was doneby callingmaven-release-plugin, but these steps are done without the plugin to have more control.

We first change the version of PMD and all modules by basically removing the “-SNAPSHOT” suffix, building the changedproject locally with tests in order to be sure, everything is in workingorder. Then the version changes are committed and a new release tag is created. Then, the versions are changed tothe next snapshot. As last step, everything is pushed.

RELEASE_VERSION is the version of the release. It is reused for the tag.DEVELOPMENT_VERSION is thenext snapshot version after the release.

RELEASE_VERSION=7.15.0DEVELOPMENT_VERSION=7.16.0-SNAPSHOT# Change version in the POMs to ${RELEASE_VERSION} and update build timestamp./mvnw--quiet versions:set-DnewVersion="${RELEASE_VERSION}"-DgenerateBackupPoms=false-DupdateBuildOutputTimestampPolicy=always# Transform the SCM information in the POMsed-i"s|<tag>.\+</tag>|<tag>pmd_releases/${RELEASE_VERSION}</tag>|" pom.xml# Run the project tests against the changed POMs to confirm everything is in running order./mvnw clean verify-Pgenerate-rule-docs# Commit and create taggit commit-a-m"[release] prepare release pmd_releases/${RELEASE_VERSION}"git tag-m"[release] copy for tag pmd_releases/${RELEASE_VERSION}""pmd_releases/${RELEASE_VERSION}"# Update POMs to set the new development version ${DEVELOPMENT_VERSION}./mvnw--quiet versions:set-DnewVersion="${DEVELOPMENT_VERSION}"-DgenerateBackupPoms=false-DupdateBuildOutputTimestampPolicy=neversed-i"s|<tag>.\+</tag>|<tag>HEAD</tag>|" pom.xmlgit commit-a-m"[release] prepare for next development iteration"# Push branch and tag pmd_releases/${RELEASE_VERSION}git push origin"${CURRENT_BRANCH}"git push origin tag"pmd_releases/${RELEASE_VERSION}"

Once we have pushed the tag, GitHub Actions take over and build a new version from this tag. Sinceit is a tag build and a release version (version without SNAPSHOT), eventually the workflow “Publish Release”will be triggered which will upload the release at the various places. This is all automated inGitHub Actions Workflows.

Here is, what happens:

• Deploy and release the build to maven central, so that it can be downloaded fromhttps://repo.maven.apache.org/maven2/net/sourceforge/pmd/pmd/. This is done automatically, ifthe build doesn’t fail for any reason. Note, that unit tests are not executed anymore, since they have beenrun already locally before pushing the tag.
• Render the documentation indocs/ withbundle exec jekyll build and create a zip file from it.
• Create a release on GitHub and upload the release notes fromdocs/pages/pmd_release_notes.md.Note: The release is directly published and marked as the latest release.
• Upload all artifacts (binary dist) tohttps://sourceforge.net/projects/pmd/files/pmd/.And select the new binary as the new default for PMD.
• Upload the documentation tohttps://docs.pmd-code.org, e.g.https://docs.pmd-code.org/pmd-doc-7.15.0/ andcreate a symlink, so thathttps://docs.pmd-code.org/latest/ points to the new version.
• Remove the old snapshot documentation, e.g. so thathttps://docs.pmd-code.org/pmd-doc-7.15.0-SNAPSHOT/ is gone.Also create a symlink from pmd-doc-7.15.0-SNAPSHOT to pmd-doc-7.15.0, so that old references still work, e.g.https://docs.pmd-code.org/pmd-doc-7.15.0-SNAPSHOT/ points to the released version.
• Deploy javadoc to “https://docs.pmd-code.org/apidocs/*/RELEASE_VERSION/”, e.g.https://docs.pmd-code.org/apidocs/pmd-core/7.15.0/. Also create/update symlinks to that the latest javadocis available athttps://docs.pmd-code.org/apidocs/pmd-core/latest/ and redirect old SNAPSHOT to the new version,so that old references still work, e.g.https://docs.pmd-code.org/apidocs/pmd-core/7.15.0-SNAPSHOT/.
  This is done for all modules.
• Create a news post onhttps://sourceforge.net/p/pmd/news/ for the new release. This contains therendered release notes.
• Copy the documentation to sourceforge’s web space, so that it is available ashttps://pmd.sourceforge.io/pmd-7.15.0/. All previously copied versions are automatically listedunderhttps://pmd.sourceforge.io/archive.phtml.
• As a last step, a new baseline for theregression testeris created and uploaded tohttps://pmd-code.org/pmd-regression-tester.
• After that, the workflow inhttps://github.com/pmd/docker/actions/workflows/publish-docker-image.yamlis triggered to create and publish a new docker image for the new PMD version.

Once the GitHub Action run is done, you can spread additional news:

• Write an email to the mailing list

  To: PMD Developers Listpmd-devel@lists.sourceforge.net Subject: [ANNOUNCE] PMD released

  • Downloads: https://github.com/pmd/pmd/releases/tag/pmd_releases%2F
  • Documentation: https://docs.pmd-code.org/pmd-doc-/

  And Copy-Paste the release notes

• Tweet about the new release

Tweet onhttps://x.com/pmd_analyzer, eg.:

PMD 7.15.0 released: https://github.com/pmd/pmd/releases/tag/pmd_releases/7.15.0 #PMD

• Post the same twitter message into the gitter chat athttps://matrix.to/#/#pmd_pmd:gitter.im

Checklist

Prepare the next release

There are a couple of manual steps needed to prepare the current main branch for further development.

• Move any open issues to the next milestone, close the current milestoneonhttps://github.com/pmd/pmd/milestones and create a new one for the nextversion (if one doesn’t exist already).

• Update version indocs/_config.yml. Note - the next version needs to have a SNAPSHOTin it otherwise the javadoc links won’t work during development.

  pmd:version:7.16.0-SNAPSHOTprevious_version:7.15.0date:2025-??-??release_type:minor

• Prepare a new empty release notes. Note, this is done bydo-release.sh already.
  • Move version/release info fromdocs/pages/release_notes.md todocs/pages/release_notes_old.md.
  • Update version/release info indocs/pages/release_notes.md. Use the following template:

---title: PMD Release Notespermalink: pmd_release_notes.htmlkeywords: changelog, release notes---{% if is_release_notes_processor %}{% comment %}This allows to use links e.g. [Basic CLI usage]({{ baseurl }}pmd_userdocs_installation.html) that work bothin the release notes on GitHub (as an absolute url) and on the rendered documentation page (as a relative url). {% endcomment %}{% capture baseurl %}https://docs.pmd-code.org/pmd-doc-{{ site.pmd.version }}/{% endcapture %}{% else %}{% assign baseurl = "" %}{% endif %}## {{ site.pmd.date | date: "%d-%B-%Y" }} - {{ site.pmd.version }}The PMD team is pleased to announce PMD {{ site.pmd.version }}.This is a {{ site.pmd.release_type }} release.{% tocmaker %}### 🚀 New and noteworthy### 🐛 Fixed Issues### 🚨 API Changes### ✨ Merged pull requests<!-- content will be automatically generated, see /do-release.sh -->### 📦 Dependency updates<!-- content will be automatically generated, see /do-release.sh -->### 📈 Stats<!-- content will be automatically generated, see /do-release.sh -->{% endtocmaker %}

Finally, commit and push the changes:

$ git commit -m "Prepare next development version"$ git push origin main

Branches

Merging

If the release was done on a maintenance branch, such aspmd/5.4.x, then this branch should bemerged into the next “higher” branches, such aspmd/5.5.x andmain.

This ensures, that all fixes done on the maintenance branch, finally end up in the other branches.In theory, the fixes should already be there, but you never now.

Multiple releases

If releases from multiple branches are being done, the order matters. You should start from the “oldest” branch,e.g.pmd/5.4.x, release from there. Then merge (see above) into the next branch, e.g.pmd/5.5.x and releasefrom there. Then merge into themain branch and release from there. This way, the last release done, becomesautomatically the latest release onhttps://docs.pmd-code.org/latest/ and on sourceforge.

(Optional) Create a new maintenance branch

At some point, it might be time for a new maintenance branch. Such a branch is usually created fromthe tag. Here are the steps:

• Create a new branch:git branch pmd/7.1.x pmd_releases/7.1.0
• Update the version in both the new branch, e.g.mvn versions:set -DnewVersion=7.1.1-SNAPSHOT.
• Update the release notes on both the new branch