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?
• Roles
• Preparation
• The Release Week
• How to ...
  • ... create the release branch
  • ... prepare the User Acceptance Test
  • ... create the Saros release
  • ... announce the new Saros release
  • ... merge the release branch back
• Other things
  • How to create a ssh key for Sourceforge on Windows
  • How to make a re-release
  • Updating Dependencies

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:

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.
    • Otherwise, contact Franz and he will create an account for you.
  • Make sure you subscribed saros-devel.
• RM and ARM:
  • Make sure you are in the Gerrit group "Release-Managers". If you are not, ask Franz to do something about it.
  • Make sure Sourceforge knows about your public SSH key.
  • Ask Franz to make sure you are a Sourceforge "Release Technician".
  • Ask Franz to make sure you are in the Sourceforge group "Release-Manager".
  • Ask Franz to make sure you are a non-moderated member of the saros-announce list.
• DM:
  • Ask Franz to make sure you are in the Sourceforge group "Tracker-Admin".

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 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
  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.
  2. (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 saros-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 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.
  • 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

• 09:00-14:00 - The whole team works on any newly found critical bugs on the release branch
• 14:00 - The release begins
  • RM + TM perform a last sanity test check and run the JUnit test cases locally.
  • TM closes all additional bugs, that have been fixed in the meantime (new status "closed-fixed")
  • RM performs the release
  • RM announces the new release on saros-devel, saros-announce, and the Sourceforge news section
  • RM merges the release branch back into the master branch
  • RM tells everybody that they did a good job
  • Everyone: Party.

How Tos

How to create the release branch

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

ToDo: Switch to semantic versioning.

• 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

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 overwrite and 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

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: .
     • 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 followd by git clean -f to ensure that you do not have any local changes
3. In the Saros project
   • Update the CHANGELOG file
   • Update the credits.txt file
   • Go to the version compatibility configuration (file version.comp) and add a compatibility information
   • Make sure the saros.properties file sets the de.fu_berlin.inf.dpp.debug property to false
4. 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
5. 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 de.fu_berlin.inf.dpp.core, 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.)
6. 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 three new archive tags (one for the dpp plugin, one for the core and for the dpp.whiteboard plugin). Each tag has two version numbers, update them too.
7. 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.)
8. 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
9. 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/ in the unlikely case the 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 overwrite or 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).
10. 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...)
11. 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. In the dropin folder, delete the files artifacts.jar and content.jar
    8. Add the readme:
       This is the Saros Eclipse plugin dropin archive. You can install it by unzipping it to eclipse/dropins and restarting Eclipse.
    9. Create a .zip file from the folder
    10. Upload archive to SourceForge
        • Select all operating systems (in order to make the dropin archive the default download)
12. Test the dropin archive. (See instructions.)
13. 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.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
    • de.fu_berlin.inf.dpp.whiteboard/META-INF/MANIFEST.MF
    • de.fu_berlin.inf.dpp/CHANGELOG
    • de.fu_berlin.inf.dpp/META-INF/MANIFEST.MF
    • de.fu_berlin.inf.dpp/credits.txt
    • de.fu_berlin.inf.dpp/saros.properties
    • de.fu_berlin.inf.dpp/version.comp

How to announce a new release

• The announcement mailing-list's address is saros-announce@googlegroups.com
• Send the release notes to the list. See the dpp-announce archive and saros-announce 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