Our Release Process

Here you will find our release process including all roles and information, what steps we need to do while releasing.

 
 

 

When?

  • Releases normally happen in the last full working week of every month.

Roles

  • RM: Release Manager
  • TM: Test Manager
  • DM: Documentation Manager

Release Manager Access Rights

The following access rights are required for the Release Manager during the release process:
  • Gerrit:
    • be member of the Group "Release Managers"
  • Saros Website (write access)
  • Sourceforge:
  • Author rights for the Saros Mailing List

Tasks of the RM and TM

  • NOTE: The process needs to be migrated to be based on Git.
  • The RM should check if he has sufficient access rights before the release process begins. The project owner can grant those rights.

Monday:

  • Before 12:00: RM creates a new release branch from master (How to branch) and runs the JUnit test cases.
    • When finished RM sends an email to the mailing-list to inform that the branch is ready (including the problems occurred during the tests).
  • Before 16:00: both of the following tasks have to be done. Attention: The second tasks depends on the first one!
    • RM creates list of newly fixed bugs and features and sends it to the mailing-list
      • Use the Changelog from SVN as a starting point (use right click on the project in eclipse: Team - Show History, in history view: Generate Changelog)
      • Take a look at the bug tracker as well for bugs which are said to have been fixed in the release
      • Describe how the fixed bugs can be reproduced. This is especially usefull for the Test Team
      • Try to sort items by importance and write in a language which users can understand
      • For each item on the list, please include the author's name
    • TM and ATM review and update the Test Suite
      • Ask developers for ways to reproduce newly fixed bugs and add appropriate test cases

Tuesday:

  • 10:00-16:00 - Run the Testlink test suite (TM & ATM, assisted by RM & ARM)
    • Test managers must close bugs in the bug tracker that are verified as fixed
  • 16:00-17:00 - TM sends to the mailing-list
    • a list of critical bugs and regression
    • a list of comments on the change-log. In particular whether a [FIX] or actually worked
    • all log files generated during the test as one big archive

Wednesday

  • The whole team fixes critical bugs on the branch
  • The RM informs the working group (e.g. contact Franz Zieris) about the progress and the anticipated date of completion, so that the working group can find a time slot for acceptance testing.

Thursday

  • The working group informs the RM about the agreed time slot.
  • RM prepares the beta-update site for the user acceptance test.
  • The RM sends the changelog to the working group so they can perform the acceptance test.
  • After the test, the working group sends their feedback, logfiles, and references to new bug tracker entries (if any) to the RM.

Friday

  • 09:00-14:00 - The team completes and confirms bugs on the release branch
  • 14:00 - Release begins
    • RM + TM perform a last Sanity Test and run the JUnit test cases.
    • Also: Test backwards-compatibility. In a test session, one person should use the branch version, the other uses the previous Saros version. This information is important in the releasing process that follows.
    • RM releases and merges fixes into master, RM announces the new release to the Saros list and Saros Announce
    • TM closes all bugs found to be fixed

Tasks of the DM

  1. DM checks all "Fixed" list entries in the Documentation Issue Tracker with the status not "Closed"
    • please check also assigned documentation issues which are not marked as "Fixed" - the assignee might just have forgotten to do that - and assign it again if it hasn't been resolved
    • if the documentation issue is resolved the DM must close the entry
  2. DM adds new documentation issues
    • use the list of newly fixed bugs and features as a starting point
    • the Changelog from Git could also be helpful
  3. DM prioritizes entries if they are not already prioritized (see Documentation issue priorities)
  4. DM assigns entries to someone who has the knowledge to correct that documentation issue
    • start with the issues with the highest priority
    • if you don't know someone to assign it to ask your team members
    • if there really is no one right now, leave it at "none"
  5. DM sends a list with the assigned documentation issues to the mailing-list
    • try not to scare off the responsible person with too many issues at once :-) (There are a lot of documentation issues that need to be resolved right now. But if we go step by step we will get an updated documentation eventually.)
    • example for the email:
      • assignee 1:
        • [Code] Saros editor package: package description (package-info.java) is missing
        • [Website] DPPGettingStarted: add instructions on how to add a Buddy to the Buddy-list (roster)
      • assignee 2:
        • ...
  6. all team members should take the time to correct/complete the documentation issues (see also How to handle documentation issues)
    • comment changes should be handled the same as source code changes since they are part of it (ask for a review especially if you have larger comment changes)
      • write comments that summarize the code or describe the code's intent (for more information see Language & Documentation in Code Rules)
      • if you want to know how a package description could look like see the package-info.java files within the concurrent package in the Saros source code
      • commit comment changes to the master
    • mark the documentation issue entry as "Fixed" when you're done
    • if you won't find the time to take care of the issue for this release please do so in the following week(s) that it's done for the next release
  7. DM announces the new documentation changes to the mailing list
    • don't forget to tell everybody that they did a good job
 

How to announce a new release

  • The announcement mailing-list's address is dpp-announce@lists.sourceforge.net
  • Make sure that you are subscribed as a non moderated member to be able to post to this list (the list admin has to uncheck the mod flag, if you subscribed yourself)
  • 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 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 ready the master for development for the next release, 14.1.31.
Make sure that the project admin has placed you in the Release Manager group of Gerrit, this way you are allowed to create branches.
 
  • 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 dpp, nebula and the 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 for review.
  • Create the 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 branch 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 dpp , nebula and the 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] Opened release branch 13.12.6
    • Push the change to Gerrit for review (and automatic JUnit execution).
  • Gerrit will run the JUnit Tests.
    • Announce the branch to the mailing-list 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 merge

  1. Make sure to fetch the latest code from the main repository.
  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] Merged '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.

 

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 prepare the User Acceptance Test

Before you can roll-out the actual release of Saros, you need to prepare the Eclipse Update Site for the User Acceptance Test Team (http://dpp.sf.net/update-beta). As for the real release, there are some preconditions:
  • Eclipse 3.6 for building the test files.
  • Up-to-Date Saros project in workspace (de.fu_berlin.inf.dpp)
  • Up-to-Date Whiteboard project in workspace (de.fu_berlin.inf.dpp.whiteboard)
  • Up-to-Date Nebula project in workspace (de.fu_berlin.inf.nebula)
  • Up-to-Date Feature project in workspace (de.fu_berlin.inf.dpp.feature)
  • Up-to-Date Beta Update site project in workspace (de.fu_berlin.inf.dpp.update_beta)
  • A ssh key for Sourceforge

HowTo:

  1. In each of the projects  SarosWhiteboard , and Nebula:
    • 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 num bers are set to 13.12.6.TESTING
    • Update plugin version of feature
      1. Go to tab Plug-ins
      2. Make sure all three of  de.fu_berlin.inf.dppde.fu_berlin.inf.dpp.whiteboard , and de.fu_berlin.inf.nebula 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] Prepared Beta-Update site for 13.12.6") 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

Note: For some hints about making a release to fix a bug in a release, see How to Re-Release
Preconditions:
!!! You must use Eclipse 3.6 to build a release! 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 Saros project in workspace (de.fu_berlin.inf.dpp)
  • Up-to-Date Feature project in workspace (de.fu_berlin.inf.dpp.feature)
  • Up-to-Date Update site project in workspace (de.fu_berlin.inf.dpp.update)
  • Up-to-Date Whiteboard project in workspace (de.fu_berlin.inf.dpp.whiteboard)
  • Up-to-Date Nebula project in workspace (de.fu_berlin.inf.nebula)
  • A ssh key for Sourceforge
  • A change log of all relevant changes (fixes, features and important API-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)

HowTo:

  1. Prepare the release notes. For an example look here
    • Name the file README (this is necessary so it will be recognised by SourceForge as the accompanying readme file).
    • Include
      • Most important changes as a nice text to be read by users (keep it simple, keep it short)
      • Link to the update site
      • Link to the homepage
      • Notable Regressions
      • Detailed changelog
      • Thanks:
        • 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, Whiteboard, and Nebula:
    • 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. Goto tab Plug-ins
      2. Make sure all three of  de.fu_berlin.inf.dppde.fu_berlin.inf.dpp.whiteboard , and de.fu_berlin.inf.nebula 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 three new archive tags (one for the dpp plugin, for the dpp.whiteboard plugin and for the nebula 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.net
    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.nebula/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
  16. Merge the changes for the release back to trunk
  17. Announce the new release on...
  18. Update the following sites:
  19. Tell everybody that they did a good job
  20. Party!

 

How to make a re-release

  • Sometimes an critical bug might have shipped with a release that just happened, which might make 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 in order:
    • 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 /lib/
  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 informations (classpath, build properties, etc.) in the plugin.xml