Overview
This document describes Subversion (SVN) layout, build and install procedures in terms of addons versioning and relationship with the J system and library releases.
Goals
Well designed software versioning scheme ensures predictable stable sustained delivery of new functionality.
Productivity: conducive to unobstructed steady stream of features and new addons
Stability: provide a well-defined solid production cross-cut of addons supported with bug-level updates
Clarity: simple design that lowers entry barrier and ensures fast adoption
Pointing in different directions, these goals create necessary tension to ensure a well-balanced solution, satisfying the needs of developers, users and businesses.
Principles
As a foundation of the SVN layout, and the build and install mechanisms, the following principles are asserted.
Relativity: Addons are related to J system as modules to host, with relatively rare J and frequent addon releases
Existence: Addons code must be compatible with the J release, thus an addon does not exist for a given J release until it is compatible
Uniqueness: For a given J release there is only one well-defined production version of an addon supported with bug-level updates
Layout
Based on the goals and principles, we arrive at a hierarchical layout: J release/addon release (minor version). Addon release must consciously and manually be blessed by the developer into a new J release, after the code is made compatible with it.
In particular, addon development version is located in trunk under
addons/trunk/category/name, e.g.
addons/trunk/data/sqlite
and stable addon releases are located in tags under
addons/tags/jXYY/category/name/major.minor, e.g.
addons/tags/j601/data/sqlite/1.3
J release level jXYY is named by J version j504, j601, etc.; the major.minor is pair of addon release is numbered continuously across J verions 1.3, 1.4, etc.
addons--tags--------trunk
+--j601 +--data
+--data +--sqlite
+--sqlite |
+--1.3 |addon release
+--1.4 <---+
Stability Levels
To serve the needs of developers, users and businesses, the following stability levels are assumed.
Development: current code changes are placed into trunk
Stable: when code in trunk is considered stable an addon release is created by copying trunk into a tag under J release/addon release. Further bug-level updates for a given addon release are commited into that tag.
Production: first stable addon release (tag) for given J release by default, unless overriden by local configuration
“There Is No Spoon”
Code has versions, it does not care whether it is called alpha, beta or candidate release, which are transient subjective and random notions of human judgement. Thus there is no beta branch in the layout. If a pre-release J version is available, a top level with corresponding name is created, under which subsequent addon versions be placed as they become available. This approach has an added value of possibility to develop for several future verions of J in parallel.
In addition, because addons are already modularized entities, and each is independently developed and versioned, there are no branches for alternative code paths. If such need still arises, it should be done in a "sandboxes" area, typically named after the developer, in the addons/branches directory.
Using Tags
Tags are used to separate code between J releases and allow for different versions of addons. There are two levels of tags according to the folder layout: J release jXYY tags and addon version major.minor tags.
When a new version of J appears, beta or otherwise, a new empty J release folder addons/tags/jXYY is created by the SVN administrator. Addon developers typically rely on the build system to place the code from trunk under that J release folder by including it in RELEASE property or can place the code in J release/addon version folder manually.
Regular Development
Code under current development is committed into trunk. During build, addon code is merged from trunk into the current version tag under one or more J release folders, as defined by the manifest properties
RELEASE=: 'j601 j602' NB. J release folder(s) VERSION=: '1.3.0' NB. current addon version
A build event occurs when build version (3rd after major.minor) in manifest is increased by developer on commit to trunk, at which point
the major.minor tag is created under the J release folder(s) if necessary
the latest code from trunk is merged into the tag(s) corresponding to the VERSION property
affected tags are built
This should not create conflict unless the addon is updated into current tag(s) manually.
If RELEASE is not defined, build from trunk does not occur, and commits to trunk are considered development (non-stable) level.
Committing to Tags
If addon developer wishes to have fine control over addon versions and be able to update other J release folders than specified in RELEASE, addon tags are created and/or updated manually by developer.
This includes both historic tags and tags under newly created J beta folder: i.e. the current J release is still in use and maintained in trunk, while a future possibly incompatible version of addon is developed in parallel in a separate J release folder and commited directly to the tag.
Under tag folders, build event is triggered when manifest is committed and its build version is increased; RELEASE property is ignored; no automatic tag creation or merging takes place.
Misc Folders
Misc folders should only be updated in trunk. For this, the tag numbers are autogenerated. Which also means that there is only one stable (at the same time production) tag for misc, and any changes to it constitute bug-level update.
Build System
Build system monitors SVN. As soon as a build event is triggered in one of the tags folders, it picks up the sources from that folder, validates and attempts a build. If the build is successful, archive(s) are created and placed into the distribution folder, updating its catalog.
Distribution
There are separate distribution folders for each J release. Each contains a catalog of addons available in it and archives of addon releases.
The result of build are platform related archive(s) named after addon category, name, build version and platform
addons/jXYY/category_name_major.minor.build_platform.ext, e.g.
addons/j601/data_sqlite_1.0.3_win.zip
If this is the first build for an addon, catalog entry is created, if first for the tag, the version list is extended with the addon version, otherwise the existing tag version is replaced with newer one.
Build Conventions
build event happens when an addon's manifest is commited and either this tag did not have a build or its build version is greater than in the catalog for this tag
there is a broad set of validations, such as correspondence of manifest items with physical location, name and version of addon release, presence of files; hierarchical dependency constraints ensuring that distribution always contains a valid combination of related addons and there are no circular dependencies
if build fails due to validation or build errors, no distribution is created
build log entry reflects the build status and any validation or build errors
build event from trunk happens only if RELEASE is specified
Installation
User installs addons with installation tool in J system. It presents a list of addons, and for each, the installed version if any, and a dropdown of available versions from the catalog. User selects desired addons and their versions and after confirmation, the archives are downloaded and installed.
Catalog
for each J version, there are separate server distribution folders with separate catalogs
catalog contains a list of addons available only for this J version formed from builds of stable addon versions (tags)
each addon entry has a list of latest (major.minor.build) versions for each major.minor pair (tag)
Installation Conventions
each particular local J system knows only about addons available for its version
the dropdown of versions for a given addon is preselected with the installed version, or the first item if none is installed. This ensures production stability principle, yet allows customer choice of newer versions
after a newer major.minor version is installed it becomes the override of production version (initially first), becoming the target of further updates
availability of bug-level update of installed versions can be highlighted with a suggestive color
dependencies are verified during selection, violation of dependencies can be highlighted with a warning color
only one version of addon is possible in one J installation, so to support dependents created for different versions, future versions should be backward compatible or dependents updated.