Version Numbers
Apache Guacamole version numbers consist of three integers separated by periods, in the standard "MAJOR.MINOR.PATCH" form. The "PATCH" number is bumped for patch releases, the "MINOR" number for minor releases, and the "MAJOR" number for major releases. The types of changes that can go into each of these releases is documented below.
At any given time, the Apache Guacamole community supports exactly one release (the latest release) and works to release exactly one release (the upcoming release), but changes will still be reviewed and accepted that are intended for a future patch, minor, or major release, even if a different release is already planned to be released first.
Patch Releases
A patch release consists only of bug fixes and minor improvements, and will be built only from changes that were merged to the patch branch. A patch release will be nearly identical to the previous release except with minor fixes/improvements applied. Changes that require substantial updates to the documentation are never part of patch releases, nor are changes that break backward compatibility at all.
Minor Releases
A minor release consists only of fixes/features/improvements that do not substantially affect compatibility nor drastically alter the behavior/appearance of the application, and will be built only from changes that were merged to the main branch. A main release will contain new features and improvements relative to the latest release, and those changes may well involve substantial changes to the documentation. Changes that substantially affect backward compatibility are never part of major releases, but breaking changes can be included if:
- Previous release notes included deprecation warnings and users have had a reasonable amount time since that release to migrate their deployments, upgrade their extensions, etc.
- The breakage affects only usage of "libguac" and can be addressed by recompiling affected code.
Major Releases
A major release consists of large fixes/features/improvements that are so substantial in scope or so significantly depart from the behavior/appearance of past releases that they cannot be included in a patch or minor release. A major release is free to break compatibility, but must provide a documented migration path for any affected feature that isn't being entirely dropped.
Branch Names
The code and documentation for each release of Apache Guacamole involves three repositories (guacamole-client, guacamole-server, and guacamole-manual), each of which use the branching scheme described here. The fourth Apache Guacamole repository, guacamole-website, houses only the website and is not relevant to the branching scheme we use for the code and documentation of each release.
We use a set of three branches to maintain the code/documentation for current and upcoming releases:
| Branch Name | Description |
|---|---|
patch | Receives only bug fixes and minor improvements. Changes to this branch can be released more quickly via patch releases, but must not require any substantial changes to documentation or established application behavior. After changes have been merged to the patch branch, the patch branch is merged back to main , and the main branch is merged to next . In extreme cases, changes to patch may need to be reimplemented against next . |
main | Receives essentially any changes except huge changes that would reasonably require a full version bump (ie: moving from 1.x all the way to 2.x). Examples of changes that should not go here include compatibility-breaking migrations away from established frameworks and rewrites of the user interface. After changes have been merged to the main branch, the patch branch is merged back to main , and the main branch is merged to next . In extreme cases, changes to patch may need to be reimplemented against next . |
next | Receives any changes that are too large in size or effect to be considered for |
When the scope of a release is frozen to allow the code/documentation to be finalized prior to release, an additional staging branch will be created for that release:
| Branch Name | Description |
|---|---|
staging/X.Y.Z | Receives only changes related to release "X.Y.Z". At the time this branch is created, all issues related to that release are already associated with that release in JIRA using the "Fix version/s" field. |
Merging Changes
Depending on the branch receiving a change, that branch may need to be additionally merged to other branches to ensure a consistent line of development.
Changes to staging/X.Y.Z
When a change for an upcoming release is merged to that release's staging branch, the staging branch needs to be merged back to the base branch that originated that release (ie: If it's a patch release, merge back to patch. If it's a minor release, merge back to main, etc.). The suggested commit messages for these merges are:
- If X.Y.Z is a patch release: "Merge X.Y.Z changes back to patch."
- If X.Y.Z is a minor release: "Merge X.Y.Z changes back to minor."
- If X.Y.Z is a major release: "Merge X.Y.Z changes back to next."
Once those changes have been merged back, follow the same procedures shown below as would be followed if those changes were merged by a direct PR against that branch.
Changes to patch
When a change is merged to patch, the patch branch must be merged back to main, and then the main branch must be merged to next. The suggested commit messages for these merges are:
- "Merge changes from patch branch back to main."
- "Merge changes from main branch to next."
Changes to main
When a change is merged to main, the main branch must be merged to next. The suggested commit message for this merge is:
- "Merge changes from main branch to next."
Changes to next
Do nothing. Changes to next do not get merged to other branches.