Versioning Proposal#

This page contains the current proposal for JSPWiki versioning.

As of JSPWiki entering Apache, we'll adopt the following versioning system:

major.minor.revision[-identifier-build]

Where

• major = Major release, which breaks compatibility (binary or source) with previous versions of the public API.
  • Custom plugins / filters / page providers will need some work to run on the new version, from reimporting a class to completely rewritting them.
• minor = Update with new major functionality, which breaks compatibility (binary or source) with previous versions, on any place except the public API.
  • These backwards incompatible changes, *may* be translated on *some* plugins / filters / page providers but, generally speaking, you shouldn't worry too much, as they should continue to work. Worst case, they at least be loaded by JSPWiki.
  • F.ex., deprecated code might disappear on this kind of releases.
  • Always refer to the appropriate NewIn page to see the scope of changes brought in by these kind of releases.
• revision = Bug fixes or minor functionality updates. Forward and backward compatibility within the same major.minor revision is retained.
  • You might need to add / delete / modify properties on your jspwiki-[custom].properties file.
• identifier = Identifies the type of this release. Following types are known:
  • git = identifies the Git # build. No release gets this tag.
  • alpha = Release which has been tagged as "alpha" grade.
  • beta = Release which has been tagged as "beta" grade.
  • incubating = Release which has been released out of Apache Incubator
• build = Build number. This must be incremented every time when a committer checks in code.

Milestone releases#

As noted above, a minor release upgrade from (say) 2.10.0 to 2.10.3 ought to be be transparent. However, a major release upgrade from (say) 2.10.3 to 2.11.0 is very likely to break compatibility with the earlier release. This might be something like requiring a higher release of java to compile or execute the code. You should always refer to the appropriate NewIn page in this wiki to familiarise yourself with the change as part of planning for an upgrade to a new major release.

That said, while a new major release is under development, it might prove appropriate to break compatibility in some way, without releasing a new major version. In such a case, this new milestone (intermediate) release will be given an M# identification such as 2.10.0.M1.

M# releases are as production-ready as any other JSPWiki release, so the label does not mean the release is incomplete, or only for the brave, or in beta, or something along those lines. Often an M# release will change an internal API, which will affect associated code such as plugins, or it might alter some configuration parameters. You should check the NewIn page before upgrading to an M# release, but not be concerned about its stability.

Release Train#

As the master branch should be always deliverable, JSPWiki tries to follow a release train schedule, with stops on -roughly- February, May, August and November (one month after each Board Report).

The progression#

Development process#

The git tag always denotes unstable code from the branch. The version number always denotes which version this development is going to.

• 2.10.0-git-1 = "This is the first development build for 2.10.0"
• 2.10.0-git-2 = "This is the second development build for 2.10.0"
• 2.10.1-git-1 = "This is the first development build for 2.10.1"

etc.