eng-standards-versioning.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="eng-standards-versioning" xreflabel="Release Version Numbering">
<title>Release Version Numbering</title>
<authorblurb>
<para><phrase role="cvstag">($Id: eng-standards-versioning.xml,v 1.11.2.1 2020/08/06 13:23:35 gustafn Exp $)</phrase></para>
<para>By Ron Henderson, Revised by Joel Aufrecht</para>
</authorblurb>
<para>
OpenACS version numbers help identify at a high-level what is in a
particular release and what has changed since the last release.
</para>
<para>A "version number" is really just a string of the form:
</para>
<blockquote>
<para><emphasis>major</emphasis>.<emphasis>minor</emphasis>.<emphasis>dot</emphasis>[ <emphasis>milestone</emphasis> ]</para>
</blockquote>
<itemizedlist>
<listitem>
<para>A <emphasis>major</emphasis> number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.</para>
</listitem>
<listitem>
<para>A <emphasis>minor</emphasis> change represents the addition of new functionality or changed UI.</para>
</listitem>
<listitem>
<para>A <emphasis>dot</emphasis> holds only bug fixes and security patches. Dot releases are always recommended and safe.
</para>
</listitem>
<listitem>
<para>A <emphasis>milestone</emphasis> marker indicates the state of the release:</para>
<itemizedlist>
<listitem>
<para><emphasis>d</emphasis>, for development, means the release is in active development and is not in its intended released form.</para>
</listitem>
<listitem>
<para><emphasis>a</emphasis>, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.</para>
</listitem>
<listitem>
<para><emphasis>b</emphasis>, for beta, means most severe bugs are fixed and end users can start trying the release.</para>
</listitem>
<listitem>
<para>Release Candidate builds (<emphasis>rc</emphasis>) are believed to meet all of the criteria for release and can be installed on test instances of production systems.</para>
</listitem>
<listitem>
<para>Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.)
</para>
</listitem>
</itemizedlist>
<para>Milestone markers are numbered: d1, d2, ..., a1, b1, rc1, etc.</para>
</listitem>
</itemizedlist>
<para>A complete sequence of milestones between two releases: </para>
<programlisting>5.0.0
5.0.0rc2
5.0.0rc1
5.0.0b4
5.0.0b1
5.0.0a4
5.0.0a3
5.0.0a1
5.0.0d1
4.6.3</programlisting>
<para>
Version numbers are also recorded in the CVS repository so that the
code tree can be restored to the exact state it was in for a
particular release. To translate between a distribution tar file
(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-level <computeroutput>readme.txt</computeroutput> file:
</para>
<programlisting>
> cvs log readme.txt
RCS file: /usr/local/cvsroot/acs/readme.txt,v
Working file: readme.txt
head: 3.1
branch:
locks: strict
access list:
symbolic names:
acs-4-0: 3.1.0.8
acs-3-2-2-R20000412: 3.1
acs-3-2-1-R20000327: 3.1
acs-3-2-0-R20000317: 3.1
acs-3-2-beta: 3.1
acs-3-2: 3.1.0.4
acs-3-1-5-R20000304: 1.7.2.2
acs-3-1-4-R20000228: 1.7.2.2
acs-3-1-3-R20000220: 1.7.2.2
acs-3-1-2-R20000213: 1.7.2.1
acs-3-1-1-R20000205: 1.7.2.1
acs-3-1-0-R20000204: 1.7
acs-3-1-beta: 1.7
acs-3-1-alpha: 1.7
acs-3-1: 1.7.0.2
v24: 1.5
v23: 1.4
start: 1.1.1.1
arsdigita: 1.1.1
keyword substitution: kv
total revisions: 13; selected revisions: 13
description:
...
</programlisting>
<para>
In the future, OpenACS packages should follow this same
convention on version numbers.
</para>
<sect2 id="eng-standards-transition-rules">
<title>Transition Rules</title>
<para>So what distinguishes an <emphasis>alpha</emphasis> release from a <emphasis>beta</emphasis>
release? Or from a production release? We follow a specific set of
rules for how OpenACS makes the transition from one state of maturity to
the next. These rules are fine-tuned with each release; an example is <ulink url="http://openacs.org/projects/openacs/5.0/milestones">5.0.0 Milestones and Milestone Criteria</ulink></para>
</sect2>
<sect2 id="eng-standards-package-maturity">
<title>Package Maturity</title>
<para>
Each package has a maturity level. Maturity level is recorded in the .info file for each major-minor release of OpenACS,
and is set to the appropriate value for that release of the package.
</para>
<programlisting>
<version ...>
<provides .../>
<requires .../>
<maturity>1</maturity>
<callbacks>
...
</programlisting>
<itemizedlist>
<listitem><para> <emphasis role="strong">Level -1:
Incompatible.</emphasis> This package is not supported for this
platform and should not be expected to work. </para></listitem>
<listitem><para> <emphasis role="strong">Level 0: New
Submission.</emphasis> This is the default for packages that do
not have maturity explicitly set, and for new contributions. The
only criterion for level 0 is that at least one person asserts
that it works on a given platform. </para></listitem>
<listitem><para> <emphasis role="strong">Level 1:
Immature.</emphasis> Has no open priority 1 or priority 2
bugs. Has been installed by at least 10? different people,
including 1 core developer. Has been available in a stable
release for at least 1 month. Has API documentation.
</para></listitem>
<listitem><para> <emphasis role="strong">Level 2:
Mature.</emphasis> Same as Level 1, plus has install guide and
user documentation; no serious deviations from general coding
practices; no namespace conflicts with existing level 2
packages. </para></listitem>
<listitem><para> <emphasis role="strong">Level 3: Mature and
Standard.</emphasis> Same as level 2, plus meets published
coding standards; is fully internationalized; available on both
supported databases. </para></listitem>
<listitem><para> <emphasis role="strong">Level 4:
Deprecated.</emphasis> The package was in some earlier version
is use, but was probably replaced by another package. The
package description should point to a preferred version.
</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="naming-upgrade-scripts">
<title>Naming Database Upgrade Scripts</title>
<para>Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.</para>
<orderedlist>
<listitem>
<para>Upgrade scripts should be named <computeroutput>/packages/<replaceable>myfirstpackage</replaceable>/sql/<replaceable>postgresql</replaceable>/upgrade/upgrade-<replaceable>OLDVERSION</replaceable>-<replaceable>NEWVERSION</replaceable>.sql</computeroutput></para>
</listitem>
<listitem>
<para>If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in <computeroutput>/packages/<replaceable>myfirstpackage</replaceable>/<replaceable>myfirstpackage</replaceable>.info</computeroutput>. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1.
</para>
</listitem>
<listitem>
<para>If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use <computeroutput>upgrade-2.0.1d3-2.0.1d4.sql</computeroutput>.</para>
</listitem>
<listitem>
<para>Database upgrades should be confined to development releases, not alpha or beta releases.</para>
</listitem>
<listitem>
<para>
Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.</para>
</listitem>
<listitem>
<para>Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.</para>
</listitem>
<listitem>
<para>The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in
acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use <computeroutput>upgrade-5.1.0d1-5.1.0d2.sql</computeroutput>
</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
