[doc] Release schedule, version policies, support lifecycle

do-release.sh

@@ -254,7 +254,7 @@ permalink: pmd_release_notes.html
 keywords: changelog, release notes
 ---
 
-## {{ site.pmd.date }} - {{ site.pmd.version }}
+## {{ site.pmd.date | date: "%d-%B-%Y" }} - {{ site.pmd.version }}
 
 The PMD team is pleased to announce PMD {{ site.pmd.version }}.
 

docs/_config.yml

@@ -3,14 +3,15 @@ repository: pmd/pmd
 pmd:
     version: 7.3.0-SNAPSHOT
     previous_version: 7.2.0
-    date: 28-June-2024
+    date: 2024-06-28
+    # release types: major, minor, bugfix
     release_type: minor
 
-# release types: major, minor, bugfix
-
 output: web
 # this property is useful for conditional filtering of content that is separate from the PDF.
 
+sidebar_title: PMD
+
 topnav_title: PMD Source Code Analyzer Project
 # this appears on the top navigation bar next to the home button
 

docs/_data/sidebars/pmd_sidebar.yml

@@ -1,7 +1,5 @@
 entries:
 - title: sidebar
-  product: PMD
-  version: '!PMD_VERSION!'
   folders:
   - title: null
     output: pdf
@@ -31,6 +29,12 @@ entries:
     - title: Getting help
       url: /pmd_about_help.html
       output: web, pdf
+    - title: Release policies
+      url: /pmd_about_release_policies.html
+      output: web, pdf
+    - title: Support lifecycle
+      url: /pmd_about_support_lifecycle.html
+      output: web, pdf
   - title: User Documentation
     output: web, pdf
     folderitems:

docs/_includes/sidebar.html

@@ -1,8 +1,8 @@
 {% include custom/sidebarconfigs.html %}
 
 <ul id="mysidebar" class="nav">
-    <li class="sidebarTitle">{{sidebar[0].product}} {{sidebar[0].version | replace: '!PMD_VERSION!', site.pmd.version}}</li>
+    <li class="sidebarTitle">{{site.sidebar_title}} {{site.pmd.version}}</li>
-    <div class="sidebarTitleDate">Release date: {{site.pmd.date}}</div>
+    <div class="sidebarTitleDate">Release date: {{site.pmd.date | date: "%d-%B-%Y" }}</div>
     {% for entry in sidebar %}
     {% for folder in entry.folders %}
     {% if folder.output contains "web" %}

docs/pages/pmd/about/release_policies.md

@@ -0,0 +1,55 @@
+---
+title: Release schedule and version policies
+permalink: pmd_about_release_policies.html
+author: Andreas Dangel <andreas.dangel@pmd-code.org>
+last_updated: June 2024 (PMD 7.3.0)
+---
+
+## Release schedule
+
+PMD uses a time-based release schedule.
+
+We release a new minor version **every month**, usually on the last Friday of the month.
+A patch release will only be done if necessary (e.g. blocker bugs).
+
+## Version policy
+
+PMD aims to follow [SemVer](https://semver.org/), that means, versions are numbered in the form MAJOR.MINOR.PATCH.
+
+A **major** release can break any compatibility, and it means more effort to upgrade to the next major version (like
+it was from 6.x to 7.x, see [Migration Guide for PMD 7](pmd_userdocs_migrating_to_pmd7.html).
+
+A **minor** release tries to be compatible so that an effortless (aka "drop-in replacement") upgrade is possible
+with some exceptions.
+
+Such releases might contain:
+
+* fixed false-positive (FP) issues for rules
+* fixed false-negative (FN) issues for rules: These fixes might break your builds, as new violations might be found.
+* new rules: these new rules are not used by default _if_ you use custom rulesets, so they shouldn't affect your builds.
+* deprecations of existing functionality
+
+In summary: we only guarantee stability on how you integrate / use the tool, but builds may start failing because
+we fixed FNs, or introduced a new rule (ie: for people referencing whole categories).
+We stick to our current approach when moving / renaming rules of deprecating them, and referencing
+the new one until the next major.
+
+A **patch** release absolutely is a drop-in replacement. So only bugs (ie: crashes or obviously broken stuff,
+like rules not being applied at all), or security issues (dependency updates, hardening, etc.) are part of
+a patch release.
+
+See also
+
+* [ADR 3 - API evolution principles](pmd_projectdocs_decisions_adr_3.html)
+* [Rule deprecation policy](pmd_devdocs_rule_deprecation_policy.html)
+
+## Git branches/tags policy
+
+* Main development happens on the main branch (currently called `master`).
+* PR and enhancements are done on the main branch.
+* Release are usually done directly from the main branch, we don't create release branches.
+* Each release has its own tag named `pmd_releases/MAJOR.MINOR.PATCH`.
+* In case of a patch release, we either do it from the main branch (if there was no development ongoing)
+  or create a separate branch off the last release tag.
+* See also [Release process](pmd_projectdocs_committers_releasing.html).
+

docs/pages/pmd/about/support_lifecycle.md

@@ -0,0 +1,25 @@
+---
+title: Support lifecycle
+permalink: pmd_about_support_lifecycle.html
+author: Andreas Dangel <andreas.dangel@pmd-code.org>
+last_updated: June 2024 (PMD 7.3.0)
+---
+
+{% capture latest_release %}{{site.pmd.version}} ({{site.pmd.date | date: "%Y-%m-%d" }}){% endcapture %}
+
+| Major version | Initial release    | Latest Release       | Required Java Version | In development / still supported? |
+|---------------|--------------------|----------------------|-----------------------|-----------------------------------|
+| 7.x           | 7.0.0 (2024-03-22) | {{ latest_release }} | 8                     | ✔ yes                             |
+| 6.x           | 6.0.0 (2017-12-15) | 6.55.0 (2023-02-25)  | 7                     | ❌ no                              |
+| 5.x           | 5.0.0 (2012-05-01) | 5.8.1 (2017-07-01)   | 7                     | ❌ no                              |
+| 4.x           | 4.0 (2007-07-20)   | 4.3 (2011-11-04)     | 5                     | ❌ no                              |
+| 3.x           | 3.0 (2005-03-23)   | 3.9 (2006-12-19)     | 4                     | ❌ no                              |
+| 2.x           | 2.0 (2004-10-19)   | 2.3 (2005-02-01)     |                       | ❌ no                              |
+| 1.x           | 1.0 (2002-11-04)   | 1.9 (2004-07-14)     |                       | ❌ no                              |
+
+In general, only the latest major version is in active development and regularly will receive new features
+and bug fixes etc.
+Once a new version is released, the previous version becomes unsupported.
+We recommend to always update to the latest version to benefit from new features and bug fixes.
+
+See also [Release process and version policies](pmd_about_release_policies.html).

docs/pages/pmd/projectdocs/committers/releasing.md

@@ -74,7 +74,7 @@ in order to release version "6.34.0", the configuration should look like this:
 pmd:
     version: 7.2.0
     previous_version: 7.1.0
-    date: 31-May-2024
+    date: 2024-05-31
     release_type: minor
 ```
 
@@ -307,7 +307,7 @@ There are a couple of manual steps needed to prepare the current main branch for
     pmd:
         version: 7.3.0-SNAPSHOT
         previous_version: 7.2.0
-        date: ??-??-2024
+        date: 2024-??-??
         release_type: minor
     ```
 
@@ -324,7 +324,7 @@ permalink: pmd_release_notes.html
 keywords: changelog, release notes
 ---
 
-## {{ site.pmd.date }} - {{ site.pmd.version }}
+## {{ site.pmd.date | date: "%d-%B-%Y" }} - {{ site.pmd.version }}
 
 The PMD team is pleased to announce PMD {{ site.pmd.version }}.
 

docs/pages/release_notes.md

@@ -4,7 +4,7 @@ permalink: pmd_release_notes.html
 keywords: changelog, release notes
 ---
 
-## {{ site.pmd.date }} - {{ site.pmd.version }}
+## {{ site.pmd.date | date: "%d-%B-%Y" }} - {{ site.pmd.version }}
 
 The PMD team is pleased to announce PMD {{ site.pmd.version }}.