Release Process
Release Process Overview
Special thanks to Michael Stone for creating most of the existing pages and spending time getting me up to speed on how its done now.
Also to Charles Merriam for helping show how good it can get
http://lists.laptop.org/pipermail/devel/2008-April/012318.html
This is a first draft. Please send comments, questions and suggestions to greg at laptop.org
Gregorio 08:46, 27 June 2008 (UTC) (UTC)
The goals of this process are to:
- Ensure high quality releases which meet the needs of users in a timely fashion.
- Maximize the participation, productivity and enthusiasm of the open source community.
- Create a predictable process which helps users and developers plan for the future.
Time-based Releases
A Release consists of a set of builds, documentation, an approved engineering change order (ECO), a completed checklist and support as defined below.
For example, see 8.1.0 Release Notes, the most recent Release as of this writing Gregorio 14:21, 27 June 2008 (UTC)
Each release will have a page linked from the Releases page
Time-based means that we have a target release day well in advance. It also means that we have a plan to begin the final test on a specific day. It does not mean that the release is guaranteed to be complete on the target release day. Features and non-critical bug fixes will be deferred to make the release day. However, a minimum standard of quality as defined by the Release Team must be met before the release is final. The release will be delayed until that minimum quality standard is met.
The definition of a minimum quality standard must be worked out and refined over time in consultation with customers and developers. It should be a priority of development and test teams to define that in advance and codify it as effectively as possible.
The choice of time based releases is motivated by its success in a growing number of open source projects. For examples, see the Fedora, Ubuntu and Gnome projects.
Major Releases
A Major Release includes significant new functionality. There will be two Major releases a year.
Duration of Support
Each Major Release will be supported for a period of 1 year from the time the Release Process Checklist is complete. The date in the "Release team final sign off" field defines the start of the 1 year support time frame.
- Scott suggested that we could be well served by choosing which releases to support long-term only after having deployed them. That way, we will have much harder data with which to judge their quality. Is this approach feasible? --Michael Stone 17:41, 28 June 2008 (UTC)
- I don't think this is feasible as a customer needs to know way ahead of time whether a release is going to be supported. We need to be able to support major releases, or don't call it a major release. So I would prefer to say we are going to support the current and 1 previous major release, rather than say we are going to support a release for 1 year. That way if there is a good reason to delay a major release, or to go to a new process with many more major releases/year, then support is defined by the release (which we understand because we tested it) rather than by some arbitrary time period.Kimquirk 18:37, 29 June 2008 (UTC)
- An alternate suggestion: we might plan to alternate "big" and "little" major releases, with the first release of the year planned for aggressive new features, and the second for stability and upstream maintenance work. The "little" releases would be candidates for longer-term support, say 2 or 3 years. I don't know if I'd actually advocate this, since we are trying to integrate lots of pieces with their own feature "bigness" schedules, but I thought I'd mention the idea. --CScott 01:31, 29 June 2008 (UTC)
Meaning of Support
Support means that a Minor Release with bug fixes will be built at OLPC's discretion based on discussion with customers and other stakeholders.
- Support also means we will work with upstream to understand and resolve security issues, and we will track, recreate and understand critical customer issues, which usually drive the dates for minor releases. And, support means upgradability and backward compatibility. The matrix of test scenarios to ensure these two items is what limits how many release we can support at any given time. Each 'supported' release must be able to upgrade to the next one; and each 'supported' release must provide backward compatibility with any other 'supported' release. We have a lot to talk about here as this implies that every release has an upgrade feature and a backward compatibility feature that needs discussion, design, development, and lots of testing Kimquirk 18:37, 29 June 2008 (UTC)
A set of Non-Upward-Compatible (NUC) features will inevitably creep into any release. If you aren't paying attention, you won't realize they are NUC's until you are already tasked with supporting them -- way too late. Avoiding this trap will require a solid understanding of the release content well before the content is released. This speaks to the critical need for requirements definition and planning, as well as a plan of record identifying the features for a release. Doing this also has benefits for the 'support discussion' as it allows one to understand the level of support required before declaring a certain release as log term or patch fix.
So we also need to talk about patching current features and bug fixes back to prior releases? Steve Holton Tue Jul 8 13:39:30 EDT 2008
Example Major Release Names
Example names of Major Releases are 8.1.0, 8.2.0, 9.1.0, 9.2.0
- Is it worth dropping the .0 suffix for the first release? This seems to be the practice for Gnome (2.22), Ubuntu (8.04), and Fedora (Fedora 9). --CScott 01:31, 29 June 2008 (UTC)
Minor Releases
Minor releases will focus on bug fixes and will come out as often as negotiated by customers and OLPC. Minor releases may include new features if the release manager and primary customers agree they are well tested and documented. Minor releases must be fully backward compatible with the major release that they are based on. That is, activities and APIs must continue to work as before.
An example reason for generating a Minor release would be to add support for an additional languages.
All the bug fixes and changes in a minor release will be tracked and recorded in a software ECO and included in the release notes. See the full minor release process definition at: http://wiki.laptop.org/go/Unscheduled_software_release_process
Example names of Minor Releases names are 8.1.1, 8.1.2, 8.2.1, 8.2.2
- I think we could benefit from trying to define the scope of minor releases more closely. If we release twice a year and support for a year, there will be a newer released major version for half the support window of the old release. How much time do we expect to spend backporting new features and refixing fixed bugs? For reference here is Debian's criteria for updates to stable: basically only "critical" bugs, where critical is defined as "makes unrelated software on the system (or the whole system) break, or causes serious data loss, or introduces a security hole on systems where you install the package." Fedora uses a more liberal policy: basically any proposed update which has not been voted down by testers after a week goes into a rolling "minor release". We should decide on an aim point between these extremes: are we "default yes" or "default no" on making minor releases? How many users must be affected before we'll consider one? My personal feeling is that minor releases suck away scarse release manager, QA, and engineering time, and thus should be avoided absent compelling reason, but I know that others feel we should make frequent minor releases with whatever is "easy" to backport, to help ensure that we make fixes and features available as quickly as possible to our users. --CScott 02:02, 29 June 2008 (UTC)
- I agree with cscott. The better our definition that minor releases are for 'critical bug fixes' the more likely we will only have to do 1-3 minor releases, and generally only within the first 2-3 months of a major release. We should have some examples of what that means. The example above - support for new languages is a good example; and we can generally push a lot of the testing back to the country since that is in the deployment guide (they translate and test). An example related to a security issue should be evaluated for how likely it is; how many people it would affect; how much disruption the fix causes to the rest of the code base, etc.Kimquirk 18:44, 29 June 2008 (UTC)
Release and Build Naming Conventions
Release Names
Recall that Releases consist of a family of builds derived from a reference OS, along with "polish" like documentation, signatures, and installable images. It is assumed that end users including students will use a Release.
The release names are of the form "Y.H.NN"
- Y = target calendar year
- H = major release number representing first release or second release of the calendar year
Example Names
- 8.1.1 First Minor Release rebuild based on the first Major Release in CY08
- 8.2.0 Second Major Release in CY08
Build Names
Recall that Releases consist of a family of builds derived from a reference OS, along with "polish" like documentation, signatures, and installable images. It is assumed that end users including students will use a Release.
The build family consists of a reference OS named:
official-nnn
which lives on http://download.laptop.org/xo-1/os/official/. The word "official" means that it is a final Major or Minor Release build (link to doc, etc.). The "nnn" is an integer uniquely identifying the source code. An example is official-703.
Derivative builds may be created locally by anyone. However, cryptographic signatures are required to enable "cheap" mass installation of the derivatives. No signatures are required if you are willing to use OLPC-supported USB customization technology or if you request developer keys for all your machines.
Derivative builds are named as follows:
variant-nnn-n
The "variant" field is typically a short string identifying a deployment or language group such as "peru" or "en". When the build name does not start with "official" it means that either:
- the reference operating system was customized to produce a derivative build, in which case the name will be as above, or
- a fork has taken place.
For example,
peru-703-6 is the customized build created for Peru based on the source code identified by 703.
and
en-708-1 is the English language customization of release candidate build 708. This is not an official Release unless and until official-708 is released and it is documented on the release page.
- I find this section confusing. The bits on an XO are a combination of a core OS plus an activity set. The peru-703-2 build was intended to denote that "core OS" 703 was combined with "version 2" of peru's activity set for that core. The "en-708-1" name seems to be too brief; it should be something like "g1g1-en-708-1" to more clearly indicate that it is the english language version of the "g1g1" activity set (that is, the activities provided to the original g1g1 participants). Presumably the "en" was intended to reflect that we might add different activities for future European g1g1 participants?
- In any case, I believe this nomenclature was a mistake. We should not be exposing the raw build number of the core OS; we should be providing names like "peru-8.1-2" instead. This also reflects the fact that Peru's activity set is not likely to require change when 8.1.1 is released, since minor releases should maintain API compatibility.
- Finally, the discussion in this section seems to anticipate the fact that some countries might fork the official OLPC core OS to varying degrees, and proposes a naming system for this which is confusingly similar to the names given to "official" core + activities set. If names for forks are required, I think we need to revisit this naming system altogether to avoid confusion. Perhaps '8.1+peru-2' is a better base name; a forked uruguay build based on 8.1 might be called 'uruguay-8.1+uruguay-3' or perhaps we should just encourage using an unrelated name like 'uruguay-1.0+uruguay-3' to avoid confusion with the "official" 8.1. --CScott 02:15, 29 June 2008 (UTC)
Types of Builds
Each build consists of a core OS.
One way of classifying a build is to identify its readiness to be a Release.
There are four types of builds in that classification:
- Released images - (a.k.a. "stable") with release notes and ECO. This is a signed image which does not need a developer key to install on an XO. (e.g. official-703; the OS component of the 8.1.0 Release)
- Release candidates - (a.k.a. "testing") release candidates which are in change control and may become official releases if it passes the test cycle. (e.g. candidate-708; tentatively the OS component of the 8.1.1 Release )
- Development images - (a.k.a. "unstable") - the latest image with the latest code but it is also likely to contain significant bugs. (e.g. joyride-2072)
- Experimental images - images which are not expected to work and which are used for creating major new functionality; typically a part of "topic branches". (e.g. faster-2072)
More details on available builds and how to get them are here.
See also: build system, Debian descriptions of stable/testing/unstable/experimental.
For a developer wanting to contribute new code we recommend the following steps:
- Decide whether you want to hack on activities, releases, bugs, or experimental features.
- Choose the corresponding build type: released images, candidates, development images, or your own topic branch.
- Send an e-mail to devel@lists.laptop.org and/or sugar@lists.laptop.org explaining your work and gathering feedback.
- Implement a basic first pass which compiles and shows the main idea. Post a link to its source to the same lists, preferably in a patch-like format.
- Revise as needed based on feedback.
- If possible, get the changes included in an upstream repository or, as appropriate, ask the list for details on how to package it locally for the XO. One useful link on including packages in Fedora is here
Release candidates are the builds that may replace the current 'stable' designation. Release candidates are created during the execution of software engineering change orders. See details of ECO creation steps in the Release Process page and An Example ECO for 8.1.1
Note: each successful build generates products that can be installed on some system. For example, release builds contain disk images suitable for flashing to NAND, for consumption by OLPC update, for inspection on other systems, and for simulation in QEMU. Traditionally, important builds are announced on devel@lists.laptop.org.
Release Schedules
Getting a stable build out can be hard. A branch grows in stability over time and stability of the release and field testing the final release candidate takes time.
The steps to creating a release schedule are as follows.
Steps
Step 1 - New Major Release is named.
Step 2 - Release objectives and lead customer identified. Target features listed and target date down to the month is chosen.
The module maintainer, with his peers and the community comes up with
a set of features for the release. Product Management participates in the discussion
and informs it based of customers feedback. Product Management and the
relevant module maintainers are responsible to build consensus. The
module maintainers are responsible to ensure that the code going in
git repositories is consistent with that consensus.
Step 3 - Schedule is posted.
"Change Control of X" means that you need to convince the maintainer of X to merge your change instead of pushing it yourself. What we call Change Control, many projects call "Feature Freeze".
Milestones
0 Start Release Process Set Target Date Pick the date and name the release
- 45 days before target date Change Control of Features. Release Candidate chosen. No new features added after this.
- 30 days before target date Change Control of the Release. Only approved bugs allowed in after this
- 15 days before target date Change Control of the Release Show Stoppers only. Only critical must have bugs allowed after this
- <15 days before target date Final Test. Get consensus from test community, QA, and engineering then finish the Release Process Checklist.
- Release day. Announcement Day. Once Release checklist is complete, Kim sends announcement e-mail approving release for production.
Definitions
- Change Control of Features
Prior to Change Control of Features, there is great freedom to propose changes because resources have not been allocated toward integrating and testing the proposed changes. We allocate these resources with release contracts. After entering Change Control of Features, changes requiring reallocation of integration and test resources (i.e. requiring a new release contract) will require approval by module maintainers and Release Management before being accepted. Minor changes can still be added without approval for another 15 days. Changes requiring great coordination to deliver like string changes and UI changes will be deferred if possible.
- Change Control of the Release
All translation packages must be final by this time.
On or before this date Module maintainers propose a set of bug fixes to get into the testing branch. They usually do so by releasing a new version of their module and informing the release team about the changes it contains and the steps necessary to test those. The release team will make sure that
the relevant QA is executed and either approve the changes or ask for fixes/improvements. As soon as the changes are approved they are added to the testing build. After this date no changes are allowed in to the code without the approval of the module maintainer and the Release Triage team.
- Change Control of the Release Show Stoppers
As of this date every single change to the source code needs to be approved by the Release Team before it happens.
- Final Test
This is when the count down to release starts. The release is not final until the Release Team signs off and the Release Process Checklist is complete.
- Announcement Day
This is the target release day but it is not the actual release day until the Final Test milestone is passed.
- It is probably worth comparing this to the Fedora release process, which offers much finer granularity for types of "freeze". In particular, we need at least a string freeze step in our process. I respect Michael's dislike of the word "freeze", but I think we'd be better served by aggressively adopting Fedora's definitions here for consistency with our upstream. --CScott 02:30, 29 June 2008 (UTC)
- unless and until our translations can be added on "ex post facto", any schedule has to include milestones for translations and different rules on what applies. For example, it is reasonably safe to strictly add a new translation up until nearly the end of the release process; modifying existing translations should have an earlier freeze date. But string freeze isn't a separate milestone in the above milestone schedule. Also note that we've already been burned by a translation not being ready when we need it, needing to make alternate translation plans; so we also need to check whether key translations are "ready" during the process. --Jg
Release Steps
Minor Releases follow the process outline here:
http://wiki.laptop.org/go/Software_ECO_process
In particular a Release must complete the checklist:
http://wiki.laptop.org/go/USR_Checklist
A Major Release follows the process documented here:
http://wiki.laptop.org/go/Plan_of_Record-2008/Draft_3#RM:_Release_Mechanisms
Release Goals and Request Prioritization
TBD.
Existing thinking on the current plan is here
http://wiki.laptop.org/go/Plan_of_Record-2008/Draft_3
Open Items
Open items needing definition and additional work
- Finalize Major Release process details and create page for it
- Update and post a new picture of the release process and release trains
- Create a schedule for 8.1.1 and 8.2.0
- List the software components, maintainers and modules in a release.
- Create an activities development process including a way to put them in releases.
- Make it easy to find the source for any component and build.
- Define feature and bug prioritization process
- Define release quality metrics and include test details and milestones
- Create governance and community best practices guidelines
- Gather community buy in and get consensus
- Finalize release and triage team members
- Review and finalize Status page
- Put the process in to practice, revise and improve
- Include more details on translations in the process
User:CScott's suggestions for further discussion:
- Is the "product" of our release a core OS, an OS plus "reference" activities, or are we ultimately responsible for producing final configurations for every deployment? Assuming that it's the second, what's the release process/schedule for those activities, and who decides (a) what activities are considered for inclusion, (b) what bugs will disqualify an activity for inclusion, and (c) what activities we will not "release" without? At what point(s) do we hand off release candidates for countries to validate against their activity set?
- Debian suggests using code names pre-release so that end users aren't confused by the presence of unreleased builds on a stream with "8.2" in the name. In the past we had builds appearing on the "update.1" stream before we officially released "update.1"; we should consider altering that practice. Fedora allows the community to vote on the codename for each release which seems reasonable.
- Fedora is currently on a 6-month release schedule. It has been suggested that we attempt to synchronize with them, and release roughly a month after Fedora does.
- We probably need to add process steps to handle export approval.
- Is six months too long between major releases for a stack in heavy active development? The longer the cycle, the more churn occurs and the harder it seems to be to stabilize. A four-month or even three-month release schedule could still sync up with Fedora, and might avoid the need to spend additional engineering effort on non-trivial minor releases. How will we know whether our release cycles are the right length? (Mozilla started with a 5 week milestone cycle, and moved to quarterly milestones; Fedora, Gnome, and Ubuntu are on 6-month cycles.)
- I believe it is worth adopting a community roadmap like GNOME where, at the start of the release cycle, component owners can outline what they hope to land in the next major release.