Release Naming Conventions

Canonical Name Forms

Product Name:            vtigercrm

Package Name:            vtigercrm-x.y.z[-][suffix#]

Unix Archive Name:       vtigercrm-x.y.z[-][suffix#].tar.gz

Windows Archive Name:    vtigercrm-x.y.z[-][suffix#].zip

Windows Installer Name:  vtigercrm-x.y.z[-][suffix#].exe

Subversion Tag Name:     /vtigercrm/tags/x.y.z[-][suffix#]

Display Name

For marketing purposes, a brand spelling of vtiger CRM is needed. This display name form would be preferred in text written for non technical users, headlines, etc.

Consistency is still important and an asset to any codebase. Searching documents for vtiger CRM and knowing you will retrieve all instances of the display name of the product can be very useful.

Using similar formatting conventions will improve the accuracy of documentation, search engine discoverability, and most importantly search-replace capability. These attributes are invaluable when trying to whip documentation into shape in the hours before a release. Committers are encouraged to replace name references throughout the documentation with spellings of the above package name or following display name formats. 

Marketing Display Name:               vtiger CRM x
 * for use in generalized contexts

Product Display Name:                 vtiger CRM x.y                          
 * for use in press releases,etc

Product Package Display Name:         vtiger CRM x.y.z[-][suffix#]
 * for use in release-specific documentation
 * use as many parts of the version number as relevant to your context; e.g. if talking about a fixed bug, x.y.z, etc.

Naming objectives

  • Consistent package name spelling vtigercrm helps packagers reuse packages among multiple linux distributions
  • Consistent version number spelling helps distros manage vtigercrm upgrades in their packaging system.
  • Every version number spelling should be easy for a package managing system to sort as 'greater than' a previous version number.
  • Always number prerelease suffixes (e.g. alpha1, beta1, etc.), since you never know when you'll need another alpha, beta or rc.
  • Always use one of the ordinals vtigercrm-X.Y.Z to indicate the scope of changes in a release. Increment as appropriate:
    • X: major version
      • Completely new system. Forward migration supported, but perhaps only from latest previous version.
    • Y: new features added
      • New features should have at least a ticket describing them, referenced in changelog
    • Z: bugs fixed
      • Diffable. Bugfixes are through visible changes in source code.
    • Suffix: for prerelease status levels only
      • One of {alpha|beta|rc|none}
      • Always appended by a number, e.g. alpha1
      • Omit suffix for final releases
      • Do not create special suffixes for fix/patch releases, e.g. vtigercrm-4.2.0p2 would be bad. Increment the appropriate x.y.z instead, and release a new version.

Named Releases vs. Patches

Previous vtigercrm release and maintenance cycles resulted in post-release Patches and the term GA (General Availability) being applied to the final versions of releases, e.g. vtigerCRM_4_0_Patch_1.zip. On occasion patches were made available on the community forum, mailing list, etc. These nonstandard release terms, distribution methods and release filenames are historical artifacts of the development process. It is intended that each future vtigercrm release will be made in the canonical format described on this page, and available from the download location described in ReleaseProcedure.

Going forward, the vtigercrm community's future use of the term Patches by convention refers to for inbound unified diffs against a branch of the subversion repository. Code contributors post Patches to tickets in this trac instance. The vtigercrm project no longer produces Patches for distribution, instead maintaining subversion branches for the same testing-developer audience.

ReleaseProcedure

Specific procedures to follow when making any release are documented in ReleaseProcedure. No vtiger releases should be made that do not follow the full ReleaseProcedure process, for reasons outlined in that page.

Relationship Of Tags To Releases

  • Objective should be to fully prepare the repository branch from which a release will be made.
  • When branch is ready, a single svn copy is made to tag that branch/revision.
  • svn tags are by convention not altered (no commits to that URL), only created, and if necessary, deleted.
  • svn export URL on an appropriate tag should give you precisely the same result as unzipping or untarring the release archives. This is to ensure that the repository consains the complete reconstruction necessary to run or examine the software at those specific historical revisions (the rev number of the svn cp that makes the tag). This is essential to people working on forward-migration code.
  • It is undesirable to perform postprocessing outside the repository to make sources conform to a special release format.
  • If release changes would hinder an active development branch (e.g. trunk), then make a release branch and tag from that URL.

Release Archive Files

  • Source archives must be made with 'svn export' on a repository tag.
  • Prepare your branch for tagging to reflect the way you want your source archives, no undocumented post-processing, please.
  • Source archives for each platform: file extension (.tar.gz|.zip) indicates native line endings:
    • .tar.gz source files will be unix newlines, unix permissions, etc.
    • .zip source files will be windows newlines+linefeeds, etc.
    • use windows to make .zip, unix to make .tar.gz, to get proper line-endings. 'svn export' client tricks may allow control over eol regardless of platform, please document here if technique known.

Sample Package Name Sequences

The following table is a sample of two release branches, 4.x and trunk, and how they might optimally name packages: 

Package Name           Release Filenames          Note
                      (both .tar.gz and .zip)
---------------------------------------------------------------------------------------------------
vtigercrm-4.2.5        vtigercrm-4.2.5.tar.gz         ('stable recommended release')

vtigercrm-4.2.6        vtigercrm-4.2.6.tar.gz         (next stable bugfix release, no new features)

vtigercrm-4.3.0        vtigercrm-4.3.0.tar.gz         (next stable feature release, new features)

vtigercrm-5.0.0-alpha1 vtigercrm-5.0.0-alpha1.tar.gz  ('december release')

vtigercrm-5.0.0-alpha2 vtigercrm-5.0.0-alpha2.tar.gz  (if needed)

vtigercrm-5.0.0-beta1  vtigercrm-5.0.0-beta1.tar.gz   (feature freeze)

vtigercrm-5.0.0-beta2  vtigercrm-5.0.0-beta2.tar.gz   (if needed)

vtigercrm-5.0.0-rc1    vtigercrm-5.0.0-rc1.tar.gz     (code freeze, bugfix only)

vtigercrm-5.0.0-rc2    vtigercrm-5.0.0-rc2.tar.gz     (if needed)

vtigercrm-5.0.0        vtigercrm-5.0.0.tar.gz         (final release, announce)

vtigercrm-5.0.1        vtigercrm-5.0.1.tar.gz         (e.g. bugfix, no new features)

vtigercrm-5.1.0        vtigercrm-5.1.0.tar.gz         (new features)

vtigercrm-5.1.1        vtigercrm-5.1.1.tar.gz         (e.g. 5.1 bugfix, no new features)

Linux Distribution Package Names

Each linux distro is free to package vtigercrm according to their conventions. Typically, they will append their special info after our canonical package name. Depending on local conventions, they may alter our canonical name a bit, which is OK. Local renaming does not affect our procedures. vtigercrm strives to keep its package naming consistent so third-party alterations can remain consistent within their own system.

For example, on Gentoo Linux, the first and second attempts at making ebuild packages for vtigercrm-5.0.0-rc1 would be:

  1. vtigercrm-5.0.0_rc1.ebuild1
  2. vtigercrm-5.0.0_rc1-r1.ebuild

This because Gentoo specifies an underscore between the version number and the version suffix, and appends -r# for its own Gentoo (re)packaging revisions. See http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=1#doc_chap2