Jump to: navigation, search

Difference between revisions of "DTP Plug-in Versioning Policy"

(Qualifier Field Format)
 
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Back To|name=DTP Main Page|href=Data Tools Platform Project}}
 
==Status==
 
==Status==
[10/29/07]: This document is a ''draft.'' It has not been approved by the DTP PMC and should not be taken as DTP policy.
+
[3/6/08]: Updated the qualifier tag format following decision in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=221541 BZ221541].
 +
 
 +
[3/4/08]: Updated for the new qualifier tag format in the PDE build.
 +
 
 +
[11/5/07]: This document has been reviewed and approved: it now represents DTP policy.
 
==Introduction==
 
==Introduction==
This document specifies plug-in versioning rules for DTP. That is, a policy for changing plug-in version numbers based on the types of changes made to the plug-in is specified below. We follow generally accepted Eclipse rules in this area, for example the [[Version Numbering | versioning policy for the Eclipse platform]]. It is important that all DTP committers adhere to this policy so tools (such as Eclipse Update Manager) and DTP users can determine the types of changes present between two versions of a given plug-in.
+
This document specifies plug-in versioning rules for DTP. That is, a policy for changing plug-in version numbers based on the types of changes made to the plug-in is specified below. We follow generally accepted Eclipse rules in this area, for example the [[Version Numbering | versioning policy for the Eclipse platform]], and we deviate only slightly as described below in the "Qualifier Field Format" section. It is important that all DTP committers adhere to this policy so tools (such as Eclipse Update Manager) and DTP users can determine the types of changes present between two versions of a given plug-in.
 
==Definitions==
 
==Definitions==
 
*A DTP plug-in version number has four fields, separated by a ".": '''Major.Minor.Service.Qualifier'''
 
*A DTP plug-in version number has four fields, separated by a ".": '''Major.Minor.Service.Qualifier'''
Line 9: Line 14:
 
*A '''service''' change indicates bug fixes.
 
*A '''service''' change indicates bug fixes.
 
*A '''qualifier''' change indicates the plug-in has changed.
 
*A '''qualifier''' change indicates the plug-in has changed.
 +
 +
As with any specification, there is room for interpretation, and each committer's best judgment is required. When in doubt, ask the DTP team/community by creating a bug or message to the [mailto:dtp-dev@eclipse.org DTP dev] mailing list.
 
==Fundamental Constraint==
 
==Fundamental Constraint==
Whatever is done to plug-in version numbers following this policy, each update '''must''' result in a number that is monotonically increasing. Otherwise, the Eclipse Update Manager will not detect the newer version of the plug-in, and users' DTP installations will be rendered inconsistent. If you believe that the policy expressed herein requires breaking this fundamental constraint, immediately notify the [mailto:dtp-pmc@eclipse.org DTP PMC] for direction.
+
Whatever is done to plug-in version numbers following this policy, each update '''must''' result in a number that ismonotonically increasing. Otherwise, the Eclipse Update Manager will not detect the newer version of the plug-in, and users' DTP installations will be rendered inconsistent. If you believe that the policy expressed herein requires breaking this fundamental constraint, immediately notify the [mailto:dtp-pmc@eclipse.org DTP PMC] for direction.
 
==Policy==
 
==Policy==
 
* The major, minor, and service fields respectively are to be ''incremented'' only once per DTP stream release cycle, depending on the type of change as described above. For example, "1.5.0" can go to "1.5.1" during a release cycle, but not "1.5.2" or higher.  
 
* The major, minor, and service fields respectively are to be ''incremented'' only once per DTP stream release cycle, depending on the type of change as described above. For example, "1.5.0" can go to "1.5.1" during a release cycle, but not "1.5.2" or higher.  
* The qualifier field is to be updated whenever anything in CVS for the plug-in is changed.
+
* The qualifier field is to be updated whenever anything delivered in DTP builds for the plug-in is changed.
* The precendence of the fields is major > minor > service. When a higher precedece field is updated, fields of lower precendence should be reset to 0 ("zero"). '''Note:'''  
+
* The precedence of the fields is major > minor > service. When a higher precedence field is updated, fields of lower precedence should be reset to 0 ("zero"). '''Note:'''  
* The precedence rules mean that the major field can not be reset to 0.
+
** The precedence rules mean that the major field can not be reset to 0.
* The qualifier field is updated separately, and is not simply incremented nor reset to zero (see below).
+
** The qualifier field is updated separately, and is not simply incremented nor reset to zero (see below).
 
* If a field is reset to 0, then it may be incremented again during a release cycle.
 
* If a field is reset to 0, then it may be incremented again during a release cycle.
 
==Qualifier Field Format==
 
==Qualifier Field Format==
The qualifier field must be "YearMonthDateIteration." For example, if the last update to a plug-in were on October 29, 2007, then the qualifier field would show "200710291." If that same plug-in were updated again on the same calendar day, then the qualifier field would show "200710292."
+
The qualifier field must be "vYearMonthDayHourMinute" (that is: "vYYYYMMDDHHMM"). Further the value '''must''' reflect the date in Shanghai. Since DTP now uses a PDE based system with map files, only source code specified in the map files (by tag) will be used for DTP builds. Thus, when you wish to update a plug-in for the build:
 +
 
 +
*Commit any changes for the plug-in as usual to CVS HEAD
 +
*Create a Qualifier field date stamp
 +
**Determine the current date and time in Shanghai. You can use [http://www.worldtimeserver.com/current_time_in_CN.aspx this site] to do so.
 +
**Use a "v" followed by the four digit year, two digit month, two digit day, two digit hour, and two digit minute
 +
*Create a CVS tag on HEAD for the plug-in using the Qualifier value.
 +
*Update the appropriate map file to use the new CVS tag for that plug-in.
 +
There are 5 map projects since Galileo M5. Please choose the correct map project to release your tags:
 +
  Connectivity plugins - org.eclipse.datatools.connectivity.releng
 +
  Enablement plugins - org.eclipse.datatools.enablement.releng
 +
  Modelbase plugins - org.eclipse.datatools.modelbase.releng
 +
  SQLTools plugins - org.eclipse.datatools.sqltools.releng
 +
  Incubator plugins - org.eclipse.datatools.incubator.releng
 +
  Features and doc plugins - org.eclipse.datatools.releng
 +
 
 +
*Commit the changes to the map file.
 +
  '''Note:''' Use the Release tool, described [[Releng_Map_File_Tool |here]], to help with tagging the source and updating map file(s).
 +
 
 +
'''Qualifier Example:'''
 +
 
 +
Suppose it is 11:40am on March 6, 2008 in Boston, MA (ET). First, I check the [http://www.worldtimeserver.com/current_time_in_CN.aspx time clock] to get the date/time for Shanghai, which happens to be 12:40am on March 7, 2008. So, the format of the Qualifier is:
 +
 
 +
* v200803071240
 +
 
 +
Next, I take this value and create a tag in CVS HEAD for the updated plug-in. Finally, I check out and update the map file using the exact same Qualifier value for that plug-in.
 +
 
 +
'''Historical Note:'''
 +
 
 +
When DTP 1.6 was tagged for map files the first time, we continued the previous Qualifier format that used an iteration count rather than hour-minute. Based on the proposal in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=221541 BZ221541] and  PMC approval, '''all qualifier updates must follow the format including hour-minute described above.''' At this time there is no need to update plug-ins having the former qualifier format.
 +
 
 +
==Initial Version for New Plug-ins==
 +
Plug-ins newly added to a DTP release cycle normally will start with a "1.0.0.Qualifier" version number, unless the plug-in is considered to be a "tech preview" version for that release. Committers adding new plug-ins to a DTP release should confirm the initial version with their project lead.
 +
 
 +
[[Category:Data Tools Platform]]

Latest revision as of 03:09, 12 March 2009

Back to DTP Main Page

Status

[3/6/08]: Updated the qualifier tag format following decision in BZ221541.

[3/4/08]: Updated for the new qualifier tag format in the PDE build.

[11/5/07]: This document has been reviewed and approved: it now represents DTP policy.

Introduction

This document specifies plug-in versioning rules for DTP. That is, a policy for changing plug-in version numbers based on the types of changes made to the plug-in is specified below. We follow generally accepted Eclipse rules in this area, for example the versioning policy for the Eclipse platform, and we deviate only slightly as described below in the "Qualifier Field Format" section. It is important that all DTP committers adhere to this policy so tools (such as Eclipse Update Manager) and DTP users can determine the types of changes present between two versions of a given plug-in.

Definitions

  • A DTP plug-in version number has four fields, separated by a ".": Major.Minor.Service.Qualifier
  • A major change indicates breakage in API or significant new/reorganization of functionality.
  • A minor change indicates changes visible to users or extenders of DTP.
  • A service change indicates bug fixes.
  • A qualifier change indicates the plug-in has changed.

As with any specification, there is room for interpretation, and each committer's best judgment is required. When in doubt, ask the DTP team/community by creating a bug or message to the DTP dev mailing list.

Fundamental Constraint

Whatever is done to plug-in version numbers following this policy, each update must result in a number that ismonotonically increasing. Otherwise, the Eclipse Update Manager will not detect the newer version of the plug-in, and users' DTP installations will be rendered inconsistent. If you believe that the policy expressed herein requires breaking this fundamental constraint, immediately notify the DTP PMC for direction.

Policy

  • The major, minor, and service fields respectively are to be incremented only once per DTP stream release cycle, depending on the type of change as described above. For example, "1.5.0" can go to "1.5.1" during a release cycle, but not "1.5.2" or higher.
  • The qualifier field is to be updated whenever anything delivered in DTP builds for the plug-in is changed.
  • The precedence of the fields is major > minor > service. When a higher precedence field is updated, fields of lower precedence should be reset to 0 ("zero"). Note:
    • The precedence rules mean that the major field can not be reset to 0.
    • The qualifier field is updated separately, and is not simply incremented nor reset to zero (see below).
  • If a field is reset to 0, then it may be incremented again during a release cycle.

Qualifier Field Format

The qualifier field must be "vYearMonthDayHourMinute" (that is: "vYYYYMMDDHHMM"). Further the value must reflect the date in Shanghai. Since DTP now uses a PDE based system with map files, only source code specified in the map files (by tag) will be used for DTP builds. Thus, when you wish to update a plug-in for the build:

  • Commit any changes for the plug-in as usual to CVS HEAD
  • Create a Qualifier field date stamp
    • Determine the current date and time in Shanghai. You can use this site to do so.
    • Use a "v" followed by the four digit year, two digit month, two digit day, two digit hour, and two digit minute
  • Create a CVS tag on HEAD for the plug-in using the Qualifier value.
  • Update the appropriate map file to use the new CVS tag for that plug-in.

There are 5 map projects since Galileo M5. Please choose the correct map project to release your tags:

 Connectivity plugins - org.eclipse.datatools.connectivity.releng
 Enablement plugins - org.eclipse.datatools.enablement.releng
 Modelbase plugins - org.eclipse.datatools.modelbase.releng
 SQLTools plugins - org.eclipse.datatools.sqltools.releng
 Incubator plugins - org.eclipse.datatools.incubator.releng
 Features and doc plugins - org.eclipse.datatools.releng 
  • Commit the changes to the map file.
 Note: Use the Release tool, described here, to help with tagging the source and updating map file(s).

Qualifier Example:

Suppose it is 11:40am on March 6, 2008 in Boston, MA (ET). First, I check the time clock to get the date/time for Shanghai, which happens to be 12:40am on March 7, 2008. So, the format of the Qualifier is:

  • v200803071240

Next, I take this value and create a tag in CVS HEAD for the updated plug-in. Finally, I check out and update the map file using the exact same Qualifier value for that plug-in.

Historical Note:

When DTP 1.6 was tagged for map files the first time, we continued the previous Qualifier format that used an iteration count rather than hour-minute. Based on the proposal in BZ221541 and PMC approval, all qualifier updates must follow the format including hour-minute described above. At this time there is no need to update plug-ins having the former qualifier format.

Initial Version for New Plug-ins

Plug-ins newly added to a DTP release cycle normally will start with a "1.0.0.Qualifier" version number, unless the plug-in is considered to be a "tech preview" version for that release. Committers adding new plug-ins to a DTP release should confirm the initial version with their project lead.