Steps needed to make a Grouper release

Changes in SVN

Check git to make sure all commits in 2.2 are in master (DONE from Aug 2, 2015 - April 5, 2016)

Edit all the pom.xmls <version> tags (DONE for 2.3)

Edit all the README.txt files (DONE for 2.3)

Edit all misc/ (DONE for 2.3)

Grouper client (DONE for 2.3)

  • conf/grouper.client*.properties (DONE for 2.3)

Look for other occurrences of grouper.client*.properties and refresh them (should only be grouper API, wsSourceAdapter, subject) (DONE for 2.3)

Look for grouperClient.jar in SVN, and update it after build and copy to release server (should only be grouper API)

Grouper API

  • (DONE for 2.3)
  • Make sure the subject jar up to date in api lib (DONE for 2.3)
  • Run the command line utility to code generate which jars/sizes/etc are expected: GrouperCheckconfig.main() (DONE for 2.3)

Grouper installer (DONE for 2.3)

  • (DONE for 2.3)
  • (DONE for 2.3)

Grouper UI

  • translate the Grouper UI text to French (our French partners have agreed to do this, as of discussion with Chris in Fall 2012)

Grouper WS (DONE for 2.3)

  • (DONE for 2.3)
  • If there is a new minor version with changes to the wsdl, add a new source folder for that version, copy the coresoap *.javas over to it, refactor to change the package, change the build.xml to build a WSDL for that version.  Change GrouperService to be like a previous version but add new methods or change methods in it (DONE for 2.3)
  • Make sure that there is no coresoap (package) in use in src/grouper_ws_v1_6, src/grouper_ws_v2_0, etc.  Take out all src/grouper_ws_vx_x except one, make sure they dont depend on each other (DONE for 2.3)
  • Generate the wssec aar's and commit them (DONE for 2.3)
  • Generate WSDLs and commit them (DONE for 2.3)

Search for the old version (e.g. 2.2.2 or 2_2_2 or 2_2_002) in all the files (DONE for 2.3)

Tag all (API, UI, WS, QS, client, etc) (DONE for 2.3)

  • In git, the tag should be something like: GROUPER_1_2_12, tag for last commit in branch, and push tag (DONE for 2.3)

For a major release, do a branch for all (API, UI, WS, QS, client) as e.g. GROUPER_1_4_BRANCH (won't do until we start work on 2.4.0)

For the final build, replace all the pom.xml <version>x.y.z-SNAPSHOT</version> with the <version>x.y.z</version>, then tag, and then branch or change to <version>x.y.(z+1)-SNAPSHOT</version> (done for 2.3.0)

See which config files / jar files / ddl changed since last release, make sure there are entries in the change log.

If its a minor release, change the release version policy page (DONE for 2.3)

Handle Copyright According to Policy

Run the copyright wizard on the entire branch for java files.  Or you can diff in version control and go through the new files.  Note, only new files should have diffs...  this is the custom copyright.  You can update the year for new files, don't update the year for existing files.  The year should be used and not a range.  That is our policy on copyrights.

Copyright 2015 Internet2

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

Make sure the subjects.sql and quickstart.xml file are in the release directory (copy from 2.3.0) (DONE for 2.3.0)

Misc Checks

  • Make sure all tables, views, and cols (of tables and views) have comments in the DB (oracle or postgres). (dont do 2.3.0)
  • Make sure the grouper-ws web.xml file has the security basic auth in there (didn't get accidentally overridden in commit) (done for 2.3.0)

Security Review

Review UI / WS code changes* from the previous version with respect to Open Web Application Security Project (OWASP) top 10 web application security vulnerabilities. (dont do for 2.3.0)

If possible run a security scan against a test instance - University of Pennsylvania via Chris? (dont do for 2.3.0)

*We have not carried out a thorough security review of the existing code base for any version of Grouper. We should do that in order for the incremental reviews to be adequate. (dont do for 2.3.0)


Run API (SuiteDefault) JUnit tests (set true in all JUnit test includes in  Also run the Grouper Installer, it should end in success for the client connecting to the WS and you should be able to use the UI.

API JUnit Tests



OS X (10.6)




Done by Chris
Time: 14,667.86 (4 hours)
OK (2232 tests)

In progress by Chris

MySQL (with utf/bin collation table types)


Done by Shilen.  All tests pass.



  • MySQL windows
  • MySQL unix with case sensitive table names
  • Postgres
  • Oracle

    create role GrouperRole;
    GRANT connect, resource, CREATE view TO GrouperRole;
    CREATE USER groupertest IDENTIFIED BY <pass>;
    GRANT connect, resource, GrouperRole TO groupertest;
  • Hsql
ps -ef | grep java   --- kill hsql
cd grouper.apiBinary-2.0.0
cd bin
java -cp ../lib/jdbcSamples/hsqldb.jar org.hsqldb.Server -port 9001 -database.0 file:grouper -dbname.0 grouper &
./ -registry -runscript
./ -test -all
  • () MsSQL (new)

Try the UI with a few different languages in the browser request (en without US, french, something not common)

Try checkConfig tests.

Upgrade from x.y-1 to x.y (e.g. 2.2 to 2.3).

  • Install 2.2.2
    • Download and run 2.2.2 installer
  • Open the UI, browse around
  • Upgrade to 2.3.0:
    • Download 2.3.0
    • Unzip
    • Download 2.3.0 ui
    • Unzip
    • Configure
    • Upgrade the registry: C:\temp\grouperUpgrade\grouper.apiBinary-2.3.0\bin>gsh -registry -runscript
    • Build the UI:
    • copy to
    • Edit the
    • C:\temp\grouperUpgrade\grouper.ui-2.3.0>ant dist
    • Map /grouper in tomcat: C:\temp\grouperUpgrade\grouper.ui-2.3.0\dist\grouper
  • Open the UI, browse around

Install the grouper installer

  • Download grouper installer
  • Run: java -jar grouperInstaller.jar
  • Try the UI that was installed
  • Make sure and gsh works in api, ws, ui for 2.3.0



OS X (10.6)




DONE for 2.3 (chris)





Web Service JUnit Tests (Grouper WS and Grouper Client) (DONE for 2.3.0, though 9 errors in client tests)

WS samples (DONE for 2.3.0) (note: still need to code/run new SOAP samples)

WS javadoc (generate, commit, test).  Make sure new operations / args / etc are documented in the WS doc page (TODO?)

UI internationalization tests (TODO?)

Test an API patch

# try to see if someone else is testing, look when process started, wait if so or email list...
[appadmin@i2midev6 ~]$ ps -ef | grep gsh | grep test | grep all

# see if hsql is running, and stop if so
[appadmin@i2midev6 ~]$ ps -ef | grep hsql
[appadmin@i2midev6 ~]$ kill <the_pid>
[appadmin@i2midev6 ~]$ > /tmp/grouperTestResults.txt & 2>&1
[appadmin@i2midev6 ~]$ tail -f /tmp/grouperTestResults.txt

Compile test on server

 * Test {@link Stem}.
 * <p />
 * @author  blair christensen.
 * @version $Id:,v 1.34 2009-12-07 07:31:09 mchyzer Exp $
public class Test extends GrouperTest {

    // Private Class Constants
    private static final Log LOG = GrouperUtil.getLog(Test.class);

     * Method main.
     * @param args String[]
    public static void main(String[] args) { Test("testCache"));

    public Test(String name) {

javac -classpath .:../lib/grouper/*:../lib/test/*:../dist/lib/* -sourcepath .

 java -classpath ../conf:.:../lib/grouper/*:../lib/test/*:../dist/lib/grouper.jar:../lib/jdbcSamples/hsqldb.jar Test

Packaging and releasing

  • ssh to (DONE for 2.3.0)
  • cd to ~mchyzer (DONE for 2.3.0)
  • Build all with: [mchyzer@i2mibuild mchyzer]$ bin/ GROUPER_x_y_z (DONE for 2.3.0)
  • This is the same as these individual commands:
    • bin/ GROUPER_x_y_z
    • bin/ GROUPER_x_y_z
    • bin/ GROUPER_x_y_z
    • bin/ GROUPER_x_y_z
    • bin/ GROUPER_x_y_z
  • Note: sometimes the grouperWs doesnt build correctly due to a bug with javadoc, just try building the ws again...

Resulting .tar.gz's are in ~mchyzer/tmp/grouperAll/build_<username>. There are both source and binary tarballs for the API and Client packages.

  • scp packages built above, to: (DONE for 2.3.0)
lcd /home/mchyzer/tmp/grouperAll/build_username
mkdir /home/htdocs/home/htdocs/
cd /home/htdocs/
mput *.tar.gz

[appadmin@i2midev1 2.0.0]$ pwd
[appadmin@i2midev1 2.0.0]$ ./

Packaging and releasing : provisioning

After tagging, publish to maven central by following the instructions on v2.1.0 Grouper Development Environment Using Maven. (DONE for 2.3.0)

Publish to maven central here

Copy grouper.psp-version.tar.gz to the release URL. (DONE for 2.3.0)

Archive the current release

  • Create PDF of current documentation for the release archive
    • Browse -> Advanced -> Export Space
    • select PDF, uncheck save comments, clear all
    • select pages to export. try to omit non-product pages, defunct pages, and pages for future releases.
    • export, save to desktop, rename and attach to GrouperWG/Archives
  • update Archives page with info from the current vN.N+Release+Notes page and links from the Software+Download page.

Update vN.N+Release+Notes page

Generally roll notes from the oldest release off and add notes for the new release. Keep previous release notes in there, so that we always have current + previous.

Update Software+Download page

Review product pages

  • Ensure that each page identifies which version it's current for, as in "Building the Grouper API as of v1.4.1" as an h2 at the top.
  • Review incoming and outgoing links info for each page.
  • If there's new features with new pages, update the Grouper+Product page to appropriately reference the new pages.
  • Is it all there?
  • Are there pages in the Working Group or Community areas that have graduated to being core product doc? Negotiate with originator to move them over to the product pages.

Update GrouperWG/Home

Just update the "NEW!!" message on this page. Maybe review the Background section to see if it could use some freshening.  Maybe add a news item

Review Training Videos

Update Grouper Wiki Documentation

  • Update wiki pages for all changed features.
  • Review the Glossary, remembering this could be a first place new people go to learn important terms. It seems rusty to Emily but not exactly sure how to improve it. HELP appreciated.
  • Be sure that wiki pages on new Features are linked correctly from the Admin Guides TOC page

Release Numbering and Testing Period

As of Feb. 2012, these procedures were adopted regarding release numbering and testing:

- The X.X.0 release will be considered a pre-release, like a Release Candidate
- That will be the testing release
- The X.X.1 release will be the actual release, presumably after any initial bugs identified have been fixed.

Notify about the release

  • Compose email to grouper-dev and grouper-users with highlights of the new release and link to the Grouper Downloads page
  • email to mw-announce [at] email list
  • Highlights should resemble those on the vN.N Release Notes page and maybe even be identical.
  • If it's especially enlightening, also include a direct link to the changelog (vN.N+Release+Notes#vN.NReleaseNotes-changelog) or to an appropriate Jira report.
  • Change jira admin to make that version released, and if the next build or version isnt there, add it

Other Outreach

  • update Grouper website features page to highlight newest Grouper features
  • Social Media: Announce the new Grouper release on the InCommon and Internet2 Facebook and Twitter accounts as appropriate
  • work with Todd Sedmak, Internet2 PR & Media Relations Manager, around other possible publicity/press releases etc.
  • A Grouper Team member (DaveL for the Grouper 2.2 release) will create a Youtube video (using same tools as the Grouper Training videos) highlighting new features
    • promote this video in coordination with the Internet2 Marketing and Communications Team 
  • schedule a webinar to promote the new release