When?

Releases happen through a time-based model, normally in the last full working week of every month.

Roles

Everyone is involved in the release process to some degree -- at least as a Developer (D). Specifically, these are the roles and their responsibilities:

Release Manager (RM)

is responsible for the Saros release as a whole

this includes having the last word on which bugs are "critical"

receives help from the Assistant Release Manager (ARM)

Test Manager (TM)

is responsible for assuring the quality of the release

currently, he does so through creating and executing the test plan

receives help from the Assistant Test Manager (ATM)

Documentation Manager (DM)

is responsible that both our code documentation and the Saros website do not lag behind the development

Developer (D)

is everyone, including the roles mentioned above

works on documentation issues or bug fixes

The rest of this process description is a recipe how to fulfill the above responsibilities in order to create a new Saros release within one working week. It consists of checklists and timings, none of which are absolutely mandatory.We consider ourselves capable software developers and responsible team players. So if you find another (a better?) way to fulfill your responsibilities (without hampering the other developers in fulfilling theirs), you're free to do so. However, the lists below provide a pretty good guideline, so consider sticking to them for a while.

Preparation

There are a few things that need to be done before the Release Week can start. The right time are the last days of the week before the Release Week.

Assign the roles

Feel free to volunteer! Otherwise, role assignment is done by Franz. These are the guidelines:

The RM should be someone who did not participate in a Saros release process before.

The ARM should be someone who was (A)RM more than once.

The TM should be someone who did not assume the TM role before.

The ATM should be someone who was (A)TM before.

Create missing accounts

D (the whole team, i.e. everyone incl. you):

Make sure you have a Sourceforge account that is assigned to the Saros project. If Saros is not listed among your projects (to check: login to Sourceforge, top left corner "Me" > "Profile"), tell Franz your account name and he will add you.

Make sure you have Author access to this website (saros-project.org).

If you are with Freie Universität Berlin, you can use your Zedat credentials to login. Ask Franz afterwards to grant you Author rights.

The Release Week

Monday

DM checks all non-closed entries from the Documentation Issue Tracker, while focusing (not slavishly) on those assigned to the current milestone/release.

Close if the documentation issue is resolved. Some open issues might be obsolete, e.g. when they refer to packages/features that do no longer exist. Close these issues as invalid.

Before 16:00:

RM and ARM create the Changelog, a list of newly fixed bugs and features and send it to saros-devel

Use the Git commit history as a starting point. Look for commits with the tags [GUI], [FEATURE], or [FIX]; it should be safe to ignore [INTERNAL] and [REFACTOR] commits.

Look at the bug tracker for the entries referenced in the [FIX] commits; make sure they are in the state "pending-fixed" (i.e. they are technically fixed, but not yet released to the wide public).

Describe how the fixed bugs can be reproduced. This is especially useful for the testers.

Try to sort items by importance and write in a language which users can understand (if you run out of time, this sub-task can be deferred until Friday).

For each item on the list, please include the author's name

TM and ATM might help in this progress (they are blocked by this anyway), especially when the commit history is long

(a) TM and ATM use the Changelog created by the RMs to compile a Test Plan to cover all these new features (incl. GUI changes) and fixed bugs

You may want to ask the original commit author for ways to reproduce newly fixed bugs

Also: Consider backward-compatibility. In a test session, one person should use the release branch version, the other uses the previous Saros release. This information is important in the releasing process that follows.

(b) As soon as the RMs completed their Changelog, theDM adds new documentation issues, prioritizes and assigns them to the developers.

For the newly introduced [FEATURE]s and changes to the [GUI]: Are they adequately represented on our website? See also: Documentation issue priorities.

Assign each open issue to someone with the knowledge to work on it: start with the highest priority, aim for an even distribution; leave it as "assigned to: none" only if there really is no one.

Send the list with the assigned documentation issues to saros-devel, e.g. like this

Tuesday

Test managers close entries in the bug tracker that are verified as fixed (new status "closed-fixed")

after 16:00 - RM decides which of the discovered/still-open bugs are critical (= no release without them being fixed); TM sends to saros-devel ...

the list of the critical bugs

a list of comments on the Changelog (in particular whether a [FIX] or actually worked)

all logfiles generated during the tests as one big archive

Before the TM's mail on saros-devel arrives: Everyone else takes the time to correct/complete the documentation issues (see also How to handle documentation issues). Mark the tracker issue as "fixed" when you're done.

In case you really don't find the time to take care of the issues assigned to you during the release week, please do so in the following week.

Wednesday

The whole team fixes critical bugs on the release branch.

Use slack time to work on your documentation issues.

The RM makes arrangements for the user acceptance test:

Inform the working group (i.e. contact Franz Zieris) about the progress and the anticipated date of completion. The working group will find a time slot for testing, and then infors the RM about the agreed time slot.

How Tos

How to create the release branch

Let's assume we are currently preparing a release on 2013-12-06, thus the release id is 13.12.6. Your task is to create a branch for the current release 13.12.6, but also prepare the master for development for the next release, 14.1.31.

Update your local repository

make sure origin/master points to the desired commit

switch to the master branch

make sure you have no local commits on top of origin/master, e.g. by using a git reset --hard.

Prepare the master

In the master, edit META-INF/MANIFEST.MF for the projects Saros and Saros Whiteboard, and set the Bundle-Version to the next release. The format is $next release id$.DEVEL, so in this case it's 14.1.31.DEVEL.

Commit it; the commit message should be "[BUILD] Master ready for development towards 14.1.31"

Push the change to Gerrit, to refs/for/master.

Jenkins will run the JUnit tests; the ARM will review this patch.

After Jenkins and ARM approved: Submit the commit.

Create the release branch.

Right click the project -> Team -> Switch To -> New Branch.

Call the branch release/13.12.6 and base it off refs/remotes/origin/master.

Push this commit to refs/heads/release/13.12.6 on Gerrit. This will create the new branch in the system.

In the branch

edit META-INF/MANIFEST.MF for the projects Saros and Saros Whiteboard, and set the Bundle-Version to $current release id$.TESTING (in this case 13.12.6.TESTING)

make sure that in project Saros the file saros.properties contains the line:de.fu_berlin.inf.dpp.debug=true

The commit message should be something like "[BUILD] Open release branch 13.12.6"

Push this commit to Gerrit, to refs/for/release/13.12.6

Jenkins will run the JUnit tests; the ARM will review this patch.

After Jenkins and ARM approved: Submit the commit.

Note: Gerrit's replication config needs to be amended so the new release branch is mirrored to GitHub.

Announce the branch to saros-devel as open for testing using the following template:

Release Branch is open for testing
-> https://github.com/saros-project/saros/tree/release/13.12.6
* The branch is ready to be tested
* Only bug-fixes should be committed to the branch
* Remember to push to refs/for/release/13.12.6
* Bug-fixes in the branch will be merged when 13.12.6 is released
Master is open for 14.1.31.DEVEL
-> https://github.com/saros-project/saros/tree/master
* All new features should go to master
* Remember to push to refs/for/master

How to prepare the User Acceptance Test

Note: There is actually no need for the "update_beta" project. We should use the normal "update" project instead, which will then be changed twice on the release branch, and delete the update_beta project once the HowTo below is adapted.

Preconditions

Before you can roll-out the actual release of Saros, you need to prepare the Eclipse Update Site for the acceptance test (http://dpp.sf.net/update-beta). As for the actual release, there are some important preconditions:

How to create a new release

Preconditions

Do not use Eclipse 3.7! Eclipse 3.7 seems to have introduced an API incompatibility with previous versions via the method org.osgi.framework.Version.compareTo(). If Saros is compiled using Eclipse 3.7 it will not work on earlier versions.

Up-to-date working copy and the following projects in your Eclipse workspace

Saros Eclipse plugin: de.fu_berlin.inf.dpp

Saros core project: de.fu_berlin.inf.dpp.core

Whiteboard plugin: de.fu_berlin.inf.dpp.whiteboard

Saros Eclipse Feature: de.fu_berlin.inf.dpp.feature

Saros Eclipse Update Site: de.fu_berlin.inf.dpp.update

A change log of all relevant changes (fixes, features and important GUI-changes) since the last release (the test manager can be asked for a compiled list of changes up until the release)

Eclipse with previous version of Saros installed (through update-site)

This update breaks compatibility with previous versions of Saros. You should not use this version of Saros with previous versions.OR

This update is compatible with all Saros version since 10.9.19

How to merge

Make sure to fetch the most recent commits of the release and the master branch.

Use git reset --hard to set your working copy to the state of origin/master.

Use Git Merge to merge with the release branch (git merge release/13.12.6), and the conflicts (git mergetool).

There should be conflicts in all MANIFEST.MF files because there were changes on the release branch as well as on the master branch. Always use the master version (e.g. 14.1.31.DEVEL).

For all other conflicted files (if any), you may prefer the release-branch version because these changes were important bug-fixes.

In the unlikely case there were both bug-fixes (release-branch) and feature-developments (master-branch) in the same files there is no general rule. You'll have to use your software development skills to find a solution that incorporates both change types.

Commit your changes (e.g. "[BUILD] Merge 'release/13.12.6' back into 'master'"), push your change to Gerrit (to refs/for/master), and watch for the result of the JUnit tests.

In case the JUnit tests or the compilation fails, fix the issue locally, amend your commit, and push it again.

In case your conflict-resolving was trivial, you may approve your change yourself and submit it directly. The change will be integrated as a merge commit.