Skip to content

How the Project Works

Jump to bottom
Ng Zhi An edited this page Jul 28, 2014 · 4 revisions

Table of Contents

Project Administration

For more information about how the Ganglia project functions from an administrative perspective, please see the "Project Administration" page.

Software Release Procedure

This section describes how the Ganglia project expects to work within the source code repositories and release future versions of the software. It will address identifying different versions, where to find stable vs. unstable source code and how bug fixes and enhancements are committed to the source code repository for different versions of the software.

Subversion Stable vs. Unstable Repositories

In order to allow for innovation to happen within the project at all times while still allowing the software to stabilize towards an official release, the Ganglia project has adopted the following process. Whenever the project community decides to roll an official major release, the first thing that happens is that a stable branch of the source code is created in the repository. The stable branch is created by taking a snapshot of the SVN TRUNK repository and labeling the branch as "monitor-core-<major.minor></major.minor>". The code in the stable branch is immediately designated as working under the guidelines of the "Current Version Branch" while the TRUNK repository remains as an unstable development repository.

The advantage to this type of process is that it allows for innovation and development to continue in the unstable development branch while providing an environment which allows the stable branch to move towards a release. The project never has to freeze the repository or lock anybody out while preparing a release of the source code. Since all proposed patches to the stable branch must first be committed to the unstable repository (trunk), it also guarantees that no patches are lost between branches. It also gives the entire community an opportunity to review and test patches before they are backported and included in an official release.

Current Version Branch (3.1 Release Branch)

Since the current version branch will be used to produce all current releases, care should be taken to make sure that this branch remains stable. The following guidelines have been provided in order to help ensure that the current version branch remains stable.

  1. All decisions to backport bug fixes or enhancements from the trunk repository to the current version branch are left to the best judgment of each individual developer.
  2. Backport patches should be primarily bug fixes and maintenance patches.
  3. All new features or enhancement should be presented/discussed first on the ganglia-developers mailing list prior to backporting the feature or enhancement to the current version branch.
  4. New feature backport patches or bug fixes must not break compatibility with previous releases within the same version series.
  5. All backport patches should have been committed to trunk first.
  6. All releases must be produced from the current version branch.
  7. All developers, whether currently holding commit rights or not, have the right to object to or question a committed backport based on technical reasons. The reasons for objecting to a committed backport should be for incompatibility issues (ie. the patch would cause the source code to be incompatible with previous releases within the same version series).
  8. All coding style, instability issues, optimizations should be fixed through follow up patches rather than objections.
The over-arching guidelines for the current release branch is to not break backward compatibility with previously released versions within the same version series. Also to avoid introducing bug fixes or features into the current release branch that have not previously been committed to the development branch (ie. trunk). Notice the use of the word "Guidelines" rather than "Rules". In other words, please use common sense and good judgment.

Maintenance Version Branches (All Previous Version Branches Including 3.0)

All maintenance branches must remain in a stable state. This will ensure that if a critical bug is found in a maintenance version of the software, a bug fix patch can be easily applied and a new release quickly produces without having to spend too much time in regression testing. The following guidelines as well as rules apply to all maintenance version branches.

  1. Review-Then-Commit (RTC) rules apply to all maintenance version branches (see CTR vs. RTC below).
  2. All backport patches should have been committed to trunk and/or the current release branch before being proposed for backport.
  3. A brief backport proposal must be entered in the branch's STATUS file for tracking purposes.
  4. A backport proposal should be sent to the ganglia-developers lists for notification and review by the community.
  5. A backport proposal can be backported to the branch repository upon receiving two +1 votes by those holding binding votes.
  6. A backport proposal can be backported to the branch repository if after 14 days from the date of the initial proposal, the proposal has not been reviewed or has not received any constructive feedback (ie. report of potential problems, regressions, bugs, deficiencies, etc.).

Versioning

The Ganglia project has adopted a versioning scheme that should help users to easily identify different versions of the software. The versioning scheme should also allow the Ganglia software to be easily upgradeable.

Every release candidate and official release of the Ganglia software will be marked with a tri-level version number (ie. 3.1.2). The first number is the major version, the second number is the minor version and the third number is the revision. The first official release candidate from the current version branch should be major.minor.0 (ex. 3.1.0) with the revision number increasing as additional release candidates are produced. All snapshots or development tarballs will be marked with a quad-level number (ie. 3.1.2.1234). The first three numbers are the same as was previously described with the third number indicating the official release from which the snapshot was derived. The fourth number is the SVN repository revision number that indicates the exact SVN revision that produced the snapshot. An official release will not be reversioned from the version number of the release candidate that it is associated with. In other words, if release candidate 3.1.2 is tested and accepted as an official release, the version of the official release will also be 3.1.2.

The version number that is established and recorded in the source code will always reflect the current release rather than a future release. All development snapshots will simply append the SVN revision number to the established version number. The minor revision number will only be incremented when a release candidate tarball is produced. At the same time, the SVN revision that was used to produce the tarball, must also be tagged in SVN. Every release candidate will increment the revision number with the official release retaining the version number of the release candidate that it is associated with. This scheme guarantees that the version number used on every tarball whether it is a development snapshot or release candidate, will always be greater than the previous and therefore work with RPM upgrade rules.

Generating a Release Candidate and GA Release

Release candidates of the Ganglia software are always generated from a stable branch (current or maintenance version branch). Once the community decides that it is time for the project to generate a new release of the software, a tag is created within the stable branch that is proposed for release. For example, if a release of Ganglia 3.1.x were proposed by the Ganglia community, a tag would be immediately created in the monitor-core-3.1 branch identifying the release candidate. The tag would be labeled with the project name and the proposed version number (ex. monitor-core-3.1.12). Once the tag has been created, a tarball is generated from the source code contained in the tagged release candidate. The tarball is then posted to the Ganglia web site for download and testing. If after a predetermined period the tagged source code proves to be stable enough for release, the tarball is designated as generally available and released to the community as an official release. If problems are found with the release candidate tarball, the problem is fixed in the stable branch of the SVN repository following the backporting guidelines described above. Then a new tag is created which carries a new version number (ex monitor-core-3.1.13) and the testing and release process is repeated. The process of tagging, rolling a tarball and testing is repeated until a stable release tarball is produced.

Release Manager and Additional Release Information

One of the first things that must happen before any release of the software can be produced is that a Release Manager (hereafter, abbreviated as RM) must be selected. Any given release must be coordinated by an RM. Since this job requires coordination of the development community (and access to subversion), only committers to the Ganglia project can act as an RM. However, there is no set RM and the duties of the RM only extend through a given release cycle. Any committer may perform a release at any time. In order to facilitate communication, it is strongly encouraged to alert the community with your planned release schedule before executing the release. An RM for a given release is determined by simply acknowledging to the development list that you volunteer to be the RM. No voting is required to select an RM unless it becomes necessary to resolve a conflict.

There are no real requirements for being an RM other than being a committer on the Ganglia project and being someone with lots of time to kill. Being an RM is a very important job in our community because it takes a fair amount of time to produce a stable release. In general, our experience has shown that a well-coordinated release fares better than non-coordinated releases.

Regarding what makes it into a release, the RM is the unquestioned authority. No one can contest what makes it into the release. The community will judge the release's quality after it has been issued, but the community can not force the RM to include a feature that he/she feels uncomfortable adding. Remember that this document is only a guideline to the community and future RMs - each RM may run a release in a different way. If you don't like what an RM is doing, then you should seriously consider volunteering to be the RM for the next release.

Freezing the source code repository is not necessary during a release cycle. It is the RM's responsibility to identify what changes should make it into the release. The RM may have an intermediate tag, so the RM can merge in or reject changes as they are committed to the repository's HEAD. Committers may and probably should voluntarily refrain from committing patches if they wish to ease the burden on the RM, but they are under no obligation to do so.

There has been a lot of discussion around what a release should be called. The Ganglia Project has three classifications for its releases:

  • Alpha indicates that the release is not meant for mainstream usage or may have serious problems that prohibits its use. Early snapshots or initial releases may be considered alpha quality.
  • Beta indicates that the development branch is nearing completion and will soon ship as a GA release. This indicates that it is expected to compile and perform basic tasks. However, there may be problems with this release that inhibit its widespread adoption.
  • General Availability (GA) indicates that this release is the best available version and is recommended for all usage. It also indicates that this release replaces all previous GA versions, and it's interfaces should remain stable throughout the life of this x.y version.
Finally, remember version numbers are cheap. If x.y.13 is retracted due to a flaw or prior veto or simply because of 'one more change' to add to this next release, then the RM should designate x.y.14. Don't attempt to overload an earlier tarball with additional changes, simply keep moving.

Once the testing period has expired and/or the RM has determined that the release candidate has been validated by the community, the release can be moved to the distribution directory on the ganglia.info site. Within a reasonable time period after the files have been moved, a public announcement can be made and an email can be sent to the various Ganglia mailing lists. Drafts of the announcement are usually posted on the development list before sending the announcement, to let the community clarify any issues that they feel should be addressed in the announcement.

At this point, the release has been created. No code changes can be made in this release. If a problem is found, it will have to be addressed in the next release or a patch can be made available. No changes can be made between alpha, beta, and GA status. The only difference is the file name that is downloaded by the users. If a tarball is created, but there was an error that can be resolved by re-rolling the tarball, it may be permissible to re-roll the release. But, the code itself may not change from version designation to designation.

As always, if you have any suggestions or comments on our process, please feel free to email our developer mailing list with your comments.

Additional Information

The following is simply addition information to help clarify some of the guidelines above. This additional information is not necessarily enforced by the Ganglia project but should be used to help guide developers when committing patches to the source code repositories or working withing the Ganglia project.

Commit-Then-Review (CTR) vs. Review-Then-Commit (RTC)

This policy is basically a very simple way of reviewing patches and proposals without interrupting innovation or stabilization. How this works is that the SVN TRUNK of the repository is always designated as development or unstable. TRUNK works under the rules of CTR. In other words, those with commit rights are free to commit anything that they feel is necessary to the development branch without any initial discussion or review. After the patch has been committed, the general committership and project community is free to review the change. If there are no objections to the patch by the community, the patch remains in the repository. If there are objections, the patch is discussed on the mailing list, modifications are made and recommitted if necessary or the patch is reverted. This allows for a low barrier to entry for innovation and bug fixes. It also eliminates a lot of unnecessary discussion and lets the code speak for itself.

Stable branch(es) on the other hand, have the option to work under the rules of RTC. In other words, no patches are committed to a stable branch without first being reviewed and voted upon by the project committership. Once a patch or backport proposal has been reviewed and received at least 2 positive votes (including the vote of the proposer if relevant) with no negative votes, the patch is accepted and can be applied to the stable branch. This process allows bug fixes and some enhancements to be applied to a stable branch with minimal impact on the branch's stability. Ensuring that a stable branch remains stable and allows for a much quicker turn around time when a new release of the software is called for or a vulnerability patch release is required.

Proposing a Patch for Backport under CTR/RTC Rules

In order to make sure that no patches or bug fixes are lost between versions, all patches must first be committed to the SVN TRUNK repository. As explained previously, TRUNK will always be considered as the unstable source code repository which works under the rules of CTR. By always committing a patch to TRUNK first, this accomplishes two things. First, it makes sure that TRUNK always contains every patch that has been committed to the repository. Since all official releases of the software are derived from TRUNK, every official release is guaranteed to contain all patches up to the point in which the source code for that release was split from TRUNK into a stable branch. Second, it makes sure that all patches are reviewed by at least one other project committer before the patch is accepted into a stable branch. This helps to ensure that the stable branch continues to stabilize rather than introducing patches which may compromise an official release.

Anybody with commit rights has the right to propose a patch for “backport”. To propose a patch for backport an entry must be made in the STATUS file in the root of the stable release branch. The backport proposal entry should include a brief description of the proposed patch, a reference to the commited source code or source code diff in the TRUNK repository, a reference to a bugzilla bug number (if one exists) and a location for voting. The following is an example of a backport proposal entry: 

   My proposed patch description here&#58; This proposal includes doing this and that.
     &quot;https&#58;//some.server.repository/viewcvs/link_to_the_patch&quot;
     bugzilla&#58; &#35;12345
     +1&#58; bnicholes
      0&#58;
     &#45;1&#58;

Other committers are free to review the backport proposal and cast their vote. Once the proposal has received at least 2 positive votes with no negative votes, the original author of the proposal is free to commit the patch to the stable branch. Any discussion that may be required happens either on the mailing list, in bugzilla or within the STATUS file itself.

Minor non-code changes may not be subject to the RTC rules when being considered for backporting. However, these changes must still be committed to the TRUNK repository first, before being considered for backport to any other repository branch. These types of changes include:

  • minor typo fixes
  • minor rewording for error messages
  • documentation
  • formatting and style fixes
  • other janitorial work which doesn't change logic
[wiki:ganglia_works]
Clone this wiki locally