Release Management Best Practices

This page gathers resources and best practices on the topic of open-source software release management. It's a collective work by the OW2 Technology Council. It is available both as HTML (below) and as a presentation.

oss-release-process-best-practices.jpg
Open-Source Release Process Best Practices v0.1

Definitions

Release

A release is a deployable software package that is the result of several iterations governed by a release management policy which defines the software release lifecycle.

Release management

Release management is the process of managing, planning, scheduling and controlling a software build through different stages and environments; including testing and deploying software releases.

Source: Wikipedia

Software release lifecycle

A software release life cycle is the sum of the stages of development and maturity for a piece of computer software: ranging from its initial development to its eventual release, and including updated versions of the released version to help improve software or fix bugs still present in the software.

Source: Wikipedia

Software artifact

An artifact is one of many kinds of tangible by-products produced during the development of software. Some artifacts (e.g., use cases, class diagrams, and other Unified Modeling Language (UML) models, requirements and design documents) help describe the function, architecture, and design of software. Other artifacts are concerned with the process of development itself—such as project plans, business cases, and risk assessments.
Build tools often refer to source code compiled for testing as an artifact, because the executable is necessary to carrying out the testing plan.
The sense of artifacts as byproducts is similar to the use of the term artifact in science to refer to something that arises from the process in hand rather than the issue itself, i.e., a result of interest that stems from the means rather than the end.

Examples 

Detailed steps example: XWiki release plan

xwiki-release-plan.png
XWiki Release Plan

Detailed steps example: Syncope Release Plan

syncope-release-plan.jpg
Syncope Release Plan

Release versioning

 MAJOR.MINOR.PATCH[-alpha.xyz]

Increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.”

Source: T. Preston-Werner co-founder of GitHub and CodeConf

Release environment setup

  • OS environment description
  • List of software prerequisites
  • Dependencies repository configuration
  • Build settings, e.g. Maven settings file

Issue clean up

  • No remaining open issues for the release
  • [JIRA] Transition from Resolved to Closed
  • [JIRA] The Fix Version attribute should include this release version
  • Closed issues should be documented

Continuous integration check

  • All test MUST pass
  • Or failures are understood and documented
  • Static code analysis – e.g. SonarQube

License check

Java / Maven projects

Release preparation with Maven

  • No uncommitted changes in the sources
  • No SNAPSHOT dependencies
  • Versions from x-SNAPSHOT to new version
  • Tag SCM information in the POM
  • Run tests against the modified POMs
    *Commit the modified POMs
  • Tag the code with release name
  • Bump the version in the POMs
  • Commit the modified POMs

[Source: Maven Release Plugin Prepare Doc.]

Performing the release

  • Maven dry run of release:prepare
  • Check pom.xml.tag and release.properties
  • Check GPG signatures of binaries
  • Maven release:prepare for real
  • Publication to Nexus
  • [JIRA] Mark version as released

[Source: Apache Syncope Prepare Source for Release]

Release notes writing

Typical release notes sections:

  • Introduction and overall description
  • Main new features
  • List of all fixed issues
  • Tested environments
  • Known issues
  • Migration notes
  • Backward compatibility
  • Link to documentation
  • List of contributors

Packaging

  • As packages in language specific package repositories: e.g. Maven Central, Eclipse Update Repository, PyPI, NPM, Ruby Gems, CPAN, ... 
  • As installable Linux distribution packages: e.g. RPM, DEB
  • As Cloud templates and images: e.g. AppHub, DockerHub

Publication

  • Publication of binaries to:
    • Library repositories (Maven Central, …)
    • Mirrors (e.g. OW2, Apache, CDN, ...)
    • Linux distribution packaging systems
    • Cloud marketplaces (e.g. AppHub)
  • Publication of versioned documentation to:
    • Project site
    • FLOSS Manuals.net

Announcement and promotion

  • Mail to users and developers
  • Blog post
  • Tweets
  • LinkedIn announcement in specialized groups
  • Wikipedia page update

Cloud template creation

About AppHub

  • Multi-cloud
  • Multi-techno
  • Self-service
  • OW2 charter / OSCAR
  • OW2 governance

Binaries naming

It's helpful to everybody if your archive files all have GNU-like names — all-lower-case alphanumeric stem prefix, followed by a dash, followed by a version number, extension, and other suffixes.
Let's suppose you have a project you call `foobar' at version 1, release 2, level 3. If it's got just one archive part (presumably the sources), here's what its names should look:

foobar-1.2.3.tar.gz

Links and resources

Contributors


Tags:
Created by Stéphane Laurière on 2017/01/24 19:08
6.4.4