Proposed usage scenarios for publishing and patching Kepler modules

General Strategy

The version of a published module will be comprise a major, a minor, and a patch number, e.g. 2.0.4. Differences in major or minor numbers represent changes in capabilities, API, etc of the module. Patches represent bug fixes that do not introduce changes visible to other modules.
Dependencies between published modules will be declared in terms of major and minor numbers only. The latest patch level of a module will be retrieved when the module is downloaded via the Module Manager.
A separate branch of each module will be maintained in the repository for each major or minor version of the module. This will allow patches to be created for any major or minor version as needed in the future.

Major Usage Scenarios

Create and publish a new Kepler module

Create a new module in the repository (under trunk/modules) to serve as the site of active development of new features.
Declare in modules.txt the direct dependencies on other modules. Where possible depend on published modules to make publication of the new module easier.
Create a branch of the module for maintenance purposes using the branch-major ant target. This creates an appropriately named branch of the module in the branches/ directory in the repository.
Do any additional work required to prepare the module for publication in the new branch.
Update modules.txt in the branch to refer exclusively to published modules, publishing these other modules first as necessary.
When ready to share the module with the world, publish the 1.0 version using the publish ant target. This zips up a snapshot of the branch and stores the appropriately named archive in the published/ directory of the repository.
Kepler users can now discover and install the published module via the Module Manager interface in Kepler.

Create and publish a major or minor version to a previously published module

Create a new branch for the minor revision, either from the module trunk, or from an existing branch of the module, using the branch-major or branch-minor ant target and providing the name of the module-trunk or branch from which to create the new branch.
Do any additional development required to prepare the new version for publication, including updating all dependencies to published modules only.
Publish the revised module using the publish ant target.
Kepler users can now discover and install the new version via the Module Manager.

Publish a patch to a published version of a module

Make any bug fixes or other updates to the module branch associated with the published version to be patched.
Publish the patch using the 'patch' ant target. This creates a new archive of the module branch and names it appropriately.
Kepler users will be prompted periodically to choose whether to install patch-level updates to their installed modules.
Because each major and minor release has it's own branch in the repository, patches can easily be be provided for any published version of any module at any time.

Restrictions

Patches may not include changes to the list of dependencies on published modules.
Dependencies on modules are declared in terms of major and minor version numbers, not patch level.
You cannot 'publish' a branch more than once, only provide patches to it.
Individual module versions may not take alpha or beta qualifiers. A distribution of the Kepler system, as a whole, may be an alpha or beta, but even such a distribution will contain only published modules with versions unqualified by alpha or beta.

Limitations that could be addressed later

Published modules currently must be stored in the Kepler svn repository. Because modules are discovered and downloaded via http, however, we could easily support multiple repositories or even simple web sites, and allow Kepler users to specify sites to search for modules and updates.

Document Actions

Print this

Sections