Release Process

Here you will find our release process including the involved roles and their activities, and how they interact to create a new Saros release.


When?

  • Releases normally happen 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) working on documentation issues or bug fixes. In addition, there are the following special roles with important 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

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

The Release Week

This section gives an overview of the roles' activities. Technical details for these tasks follow below.

Monday

  • Before 12:00:
    • RM creates a new release branch from the master branch
    • 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:
    1. RM and ARM create the Changelog, a list of newly fixed bugs and features and send it to dpp-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
    2. (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.
    1. (b) As soon as the RMs completed their Changelog, the DM 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 dpp-devel, e.g. like this
        Assignee 1:
           * #127 [Code] Saros editor package: package description (package-info.java) is missing
           * #156 [Website] GettingStarted: add instructions on how to add someone to the contact list
        Assignee 2:
           * #134 ...
        

Tuesday

  • 10:00-16:00 - TM & ATM execute the test plan (assisted by RM & ARM)
    • 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 dpp-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 dpp-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.
    • Once all critical bugs are fixed on the release branch, the prepare the beta-update site for the user acceptance test.
    • Send the changelog to the working group so they know on which parts to pay particular attention.

Thursday

  • The working group performs the user acceptance test.
    • After the test, the working group sends their feedback, logfiles, and references to new bug tracker entries (if any) to the RM.
    • Note: Sometimes, the working group is able to perform their test already on Wednesday, which leaves more time for the development team to fix any showstoppers before Friday.
  • Everyone: If you still got documentation issues left: Work on them.

Friday


How Tos

How to create the release branch

Note: This section needs an update to include the Core project.

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)
    • 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 dpp-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:
  • Eclipse 3.6 for building the test files.
  • 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 for Beta tests: de.fu_berlin.inf.dpp.update_beta

Step-by-Step

Note: This section needs an update to include the Core project.

  1. In each of the projects Saros and Whiteboard:
    • File META-INF/MANIFEST.MF: Make sure that the version number is set to 13.12.6.TESTING
  2. In the Feature project:
    • File feature.xml: Make sure that all version numbers are set to 13.12.6.TESTING
    • Update plugin version of feature
      1. Go to tab Plug-ins
      2. Make sure de.fu_berlin.inf.dpp and de.fu_berlin.inf.dpp.whiteboard and de.fu_berlin.inf.dpp.core are included
      3. For all projects, click on Versions...
      4. Select Copy versions from plugin and fragment manifests
      5. Press Finish
      6. (Make sure the version in the overview tab is correct.)
  3. Prepare the Beta Update Site project. Edit the site.xml.
    1. Go to tab Site Map
    2. Remove the previous feature (right-click > "Remove")
    3. Add current feature ("Add Feature" > select "de.fu_berlin.inf.dpp.feature (13.12.6.TESTING)")
    4. Go to tab Archives
    5. In the section "Archive Mapping" adjust the version numbers in the three entries
    6. Save the file site.xml
  4. Build the update site
    1. Press Build button on the selected new version in Site Map tab
      • This will create the two folders plugins and features and create Jar files in them.
      • (NOTE: If they don't appear, it may help if you delete artifacts.jar and content.jar.)
  5. Copy update-site to sourceforge
    1. login with ssh into [username],dpp@web.sourceforge.net (e.g. with WinSCP)
    2. copy the files index.html and site.xml as well as the folders features and plugins into htdocs/update-beta
    3. Make sure that all copied files have read/write permissions for group to allow other developers to delete them
    4. Make sure that all copied files have read permissions for everyone, otherwise users can't access our update site
    5. This means the correct rights are rwxrwsr-x or 2775 (folders) and rw-rw-r-- or 664 (files).
  6. Test the update-site out of an Eclipse of your choice: http://dpp.sf.net/update-beta
  7. Commit your changes (as "[BUILD] Prepare update site for 13.12.6 beta test") and push them to Gerrit (to refs/for/release/13.12.6). Make sure your commit does not contain changes that go beyond these files (if it does, unstage them):
    • de.fu_berlin.inf.dpp.feature/feature.xml
    • de.fu_berlin.inf.dpp.update_beta/artifacts.jar
    • de.fu_berlin.inf.dpp.update_beta/content.jar
    • de.fu_berlin.inf.dpp.update_beta/site.xml

How to create a new release

Preconditions

  • Eclipse 3.6 for building the release files.
    • 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)

Step-by-Step

Note: This section needs an update to include the Core project.

  1. Prepare the release notes. For an example look here
    • Name the file README (this is necessary so it will be recognized by Sourceforge as the accompanying readme file).
    • Include
      • most important changes as a short natural-language paragraph (keep it simple)
      • notable Regressions (if any)
      • link to the update site: http://dpp.sourceforge.net/update
      • link to the homepage: http://www.saros-project.org
      • detailed changelog in a language our users can understand
      • Thanks to:
        • Users who reported bugs and participated in our survey
        • Everybody who participated
  2. Make sure that you are on the release branch and that everything is up-to-date. Use git reset --hard to ensure that you do not have any local changes
  3. Update the CHANGELOG file in Saros project root.
  4. Update the credits.txt file in Saros project root.
  5. In each of the projects Saros and Whiteboard:
    • Go to plugin.xml. Set plugin version number (for instance 13.12.6) in the overview tab.
  6. In the Saros Project: Go to the version compatibility configuration (file version.comp) and add a compatibility information for version 13.12.6
  7. Prepare the Feature project
    1. Go to feature.xml. Set feature version number (for instance 13.12.6 )
    2. Update plugin version of feature
      1. Go to tab Plug-ins
      2. Make sure both de.fu_berlin.inf.dpp and de.fu_berlin.inf.dpp.whiteboard are included
      3. For all projects, click on Versions...
      4. Select Copy versions from plugin and fragment manifests
      5. Press Finish
      6. (Make sure the version in the overview tab is correct.)
  8. Prepare the Update Site project. Edit the site.xml manually. We only provide the most recent Saros version.
    1. Replace the version number in the feature tag; there are two version numbers.
    2. Replace the version number in the two new archive tags (one for the dpp plugin one for the dpp.whiteboard plugin). Each tag has two version numbers, update them too.
  9. Build the update site
    1. Press Build button on the selected new version in Site Map tab
      • This will create the two folders plugins and features and create jar files in them.
      • (NOTE: If they don't appear, it may help if you delete artifacts.jar and content.jar.)
  10. Create release on Sourceforge
    1. Go to the File Explorer on Sourceforge.net (Admin -> File Explorer)
      • Create a new Folder "DPP 13.12.6 "
      • Upload the README
      • Upload the jars created in the build step from the plugins directory
  11. Copy update-site to Sourceforge
    1. login with ssh as [username],dpp to web.sourceforge.net (e.g. using WinSCP)
    2. copy index.html, site.xml, and the de.fu_berlin.inf.dpp.feature_13.12.6.jar from the features folder into htdocs/update
      • copy web directory to htdocs/update if style files changed
    3. Make sure all copied files have the right permissions:
      • Make sure that all copied files have read/write permissions for group to allow other developers to delete them
      • Make sure that all copied files have read permissions for everyone, otherwise users can't access our update site
      • This means the correct rights are rwxrwsr-x or 2775 (folders) and rw-rw-r-- or 664 (files).
  12. Test the update site:
    1. Start an existing Eclipse with Saros installed.
      • Help -> Check for Updates (note that the update site may not be updated for some time...)
  13. Create dropin archive:
    1. File -> Export... -> Plug-in Development -> Deployable features
    2. Choose feature
    3. Destination -> Directory
    4. Choose target directory name: saros-dropin-13.12.6
    5. Check "Use class files from workspace" (otherwise JUnit won't be found which leads to compile errors)
    6. Click Finish
    7. TODO: Add a README file to the folder for users who don't know what to do with a dropin archive
    8. Zip the directory and use the same name: saros-dropin-13.12.6.zip
    9. Upload archive to SourceForge
      • Select all operating systems (in order to make the dropin archive the default download)
  14. Test the dropin archive. (See instructions.)
  15. Commit your changes (as "[BUILD] Changes necessary for Release 13.12.6") and push the commit to Gerrit (on refs/for/release/13.12.6). Make sure your commit does not contain changes that go beyond these files (unstage them otherwise):
    • de.fu_berlin.inf.dpp/CHANGELOG
    • de.fu_berlin.inf.dpp/credits.txt
    • de.fu_berlin.inf.dpp/version.comp
    • de.fu_berlin.inf.dpp/META-INF/MANIFEST.MF
    • de.fu_berlin.inf.dpp.whiteboard/META-INF/MANIFEST.MF
    • de.fu_berlin.inf.dpp.feature/feature.xml
    • de.fu_berlin.inf.dpp.update/artifacts.jar
    • de.fu_berlin.inf.dpp.update/content.jar
    • de.fu_berlin.inf.dpp.update/site.xml

How to announce a new release

  • The announcement mailing-list's address is dpp-announce@lists.sourceforge.net
  • Send the release notes to the list. See the dpp-announce archive for reference.
  • Always include compatibility information:
    • 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

  1. Make sure to fetch the most recent commits of the release and the master branch.
  2. Use git reset --hard to set your working copy to the state of origin/master.
  3. 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.
  4. 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.
  5. 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.

How to create a ssh key for Sourceforge on Windows

  1. Execute PuttyGen
  2. select SSH-2 DSA and press Generate
  3. move mouse until new key is generated
  4. press Save private key and choose a filename to save private key on disk (ignore warning of empty passphrase)
  5. copy public key into the clipboard
  6. log in on Sourceforge
  7. go to SSH Keys
  8. paste your public key into the area labeled Authorized keys
  9. click Update

How to make a re-release

  • Sometimes a critical bug is shipped with a release that just happened, that makes it necessary to re-release.
  • Since making a release is a lot of work and also is confusing to the users, we should use the following criteria to determine whether a re-release is appropriate:
    • Is the release unusable for users due to this bug?
    • Does the bug represent a regression?
    • Have less than 72 hours passed since the release?
  • These rules can be bend at will, but it might also make sense to just withdraw the release, by updating site.xml
  • How a re-release is done:
    • The first rule is:
      • A release is always made from the release branch
    • To achieve this, remember:
      • Fixes go to the release branch
      • Features go to trunk
    • Once the release branch has been patched and fixed, the release is made from the branch. Afterwards the branch is merged to trunk to integrate the fixes to trunk.
    • If another bug is found, repeat:
      • Fixed go to the release branch
      • Features stay in trunk
    • The second rule is:
      • Don't forget to merge back.

Updating Dependencies

  1. The JARs should have their version numbers in the name.
  2. Make sure you have copied the new JARs to <rootofsarosproject>/lib/</rootofsarosproject>
  3. right click on your Saros project in eclipse, choose "Build Path"->"Configure Build Path.."
  4. click tab "Libraries"
  5. click button "Add JARs" to add new JARs to the project
  6. click "Ok" and you are ready, maybe you have to rebuild the project
  7. update all relevant information (classpath, build properties, etc.) in the plugin.xml