release-process.txt

Seam Release Process
====================

Notify branch is closed
------------------------
* Send an email to seam-dev@lists.jboss.org.
  - State a version of the following :
    - As all issues in JIRA for Seam <release> are now resolved, the release 
      process for <release> is now underway.  Please don't make any commits to 
      the <branch or trunk> without checking with and getting approval from 
      this mail list first. 

Updating version numbers
------------------------
* Update the version information:
  - readme.txt 
    - one place at top including date.
  - changelog.txt
    - Generate a JIRA release note report for the release in "text" format
        - Only "issue types" that have jira's will work
        - Usually that is (Bug, Feature Request, Task, and Patch)
        - Check all the issue types one at a time to determine final list.
 - update pom.xml versions
    - mvn versions:set -DnewVersion=XXX -Pall
 - or use maven-release-plugin

export MAVEN_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=512m";
mvn release:prepare -DreleaseVersion=<2.3.1.Final> -Dtag=<JBoss_Seam_2_3_1_Final> -DpushChanges=false
-DdevelopmentVersion=<2.3.2-SNAPSHOT> -Dusername=<your_github_account> -DcheckModificationExcludeList=seam-cdk-helper/**
-Pall,release

 - check your sources and changes of version string usages
   - git diff

 - Alternatively change missing by
   - find . -prune -o -type f -exec grep -i /XXX/YYY/g' {} \;

    
Maven repository settings
-------------------------
* A released version of seam should not reference any repositories other than
  "http://repository.jboss.org/nexus/content/groups/public/".
  See "build/readme.txt" for details.
  - Search "$SEAM/build" for "repositories".  
    - Comment out any repository entry not "http://repository.jboss.org/nexus/groups/public/"
    - Should only be entries in "settings.xml" or "ci.settings.xml"
  - Verify prior to tagging
    - Clean your local maven repository
        - ex. "~/.m2"
        - <TODO document way to set local repo settings for clean build />
    - Go to root and run "mvn clean verify -s build/settings.xml -Pall,distribution -Darquillian=jbossas-managed-7" with these changes
    - This should build, and test without a problem.
  - Run "mvn dependency:tree -s build/settings.xml -DoutputFile=$(pwd)/dependency-report.txt -DappendOutput=true"
    - Review for snapshot dependencies

Staging Maven artifacts 
------------------------
* Maven release procedure.
    - Run mvn deploy -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2 -s settings-staging.xml    
      or
    - Run mvn release:perform -s settings-staging.xml
    - Then follow http://community.jboss.org/wiki/MavenDeployingaRelease section Closing the Staging Respository
    - test a Seam project with staged artifacts in repository https://repository.jboss.org/nexus/content/groups/staging/
    - then release Maven artifacts 
Note: staging-settings.xml contains a setup of jboss.org Account to be able to upload to Staging repository - look at  https://community.jboss.org/wiki/MavenRepositoryConfiguration
There needs to be something like:

	<server>
      <id>jboss-releases-repository</id>
      <username><your jboss.org account></username>
      <password></password>
    </server>
  </servers>


Internal testing before tagging for Final releases
--------------------------------------------------
Final releases should be verified before tagging. Just note revision number after updating changelog.txt.
Send email to <seam-dev@lists.jboss.org> about frozen branch and point the QE to the revision number.
After verification continue with creating final tag and final steps for releasing (if you use mvn
release:prepare/perform, do the verification before perform goal) .

JDK Version Specific Information
--------------------------------
The latest version of Sun's JDK 1.6 is used for building the release, and the 
majority of the testing.

Building and Checking Dist
--------------------------
* Run "mkdir ../releaselogs" for release artifacts and logs.
    
* Create the distribution build
    - run "mvn clean install -s ../build/settings.xml -Pdistribution > ../releaselogs/x.x.x.XX.distbuild.txt"
    - Use the dist build for all example tests
    
* Diff the zip, tar.gz, and exploded version of the dist build
    - example of how to do it:
        - explode the zip and gz into "../tmp/zip" and "../tmp/gz"
        - cp distribution directory into "../tmp/dist" 
        - in "../tmp" run:
            - "diff -r ./gz/. ./zip/."
            - "diff -r ./gz/. ./dist/."
    - There should be no differences.
    - Compare the new dist to dist of the previous version using the same method
        - Manually look over for any glaring differences or errors.
    - Delete "../tmp" if you wish
    
* check that the following files/directories exist in the distribution/target/*.zip or *.tar.gz "ls -1"    
    build
    copyright.txt
    doc
    extras
    changelog.txt
    lgpl.txt
    lib
    readme.txt
    seam
    seam.bat
    seam-gen
    seam2migration.txt
    seam21migration.txt
    seam23migration.txt

* check that the following source directories exist in the distribution/target/jboss-seam-<version>-src.zip "ls -1"
    bom
    build
    distribution
    eclipse-code-formatter-profile.xml
    examples
    functional-tests
    jboss-seam
    jboss-seam-debug
    jboss-seam-excel
    jboss-seam-flex
    jboss-seam-gen
    jboss-seam-ioc
    jboss-seam-mail
    jboss-seam-pdf
    jboss-seam-remoting
    jboss-seam-resteasy
    jboss-seam-rss
    jboss-seam-ui
    jboss-seam-wicket
    pom.xml
    release-process.txt
    seam-integration-tests
    seam-reference-guide

* Archive reports
    - run these in the dist directory
        find . -name *.jar > ../releaselogs/jarlist.txt 
        find . -name *.war > ../releaselogs/warlist.txt
        find . -name *.ear > ../releaselogs/earlist.txt
        find . -name *.zip > ../releaselogs/ziplist.txt
        find . -name *.gz > ../releaselogs/gzlist.txt
        find . -name *seam*.jar > ../releaselogs/seamjarlist.txt
    - Manually review the lists for problems
        - <TODO: list expected items or provide listing in svn/>        
 
* Built source verification, dependency report & test suite
    - Clean your local maven repository
        - ex. "rm -Rf ~/.m2"
        - take build/settings.xml and set <localRepository>/path/to/local/repo</localRepository> 
        
    ** Source verification **
        - Go to root of checked out directory and run "mvn clean install -s ../build/settings.xml -Pall,distribution > ../releaselogs/x.x.x.XX.sourcebuild.txt"
        - diff the original and the built versions of the $DIST directories
            - only difference should be build related 
            - <TODO: list expected differences/>
        - Extract seam jars from orig, and the newly built into tmp directories
            - diff the directories
            - Should be no differences except version of Maven and/or jdk versions
        
    ** Dependency report **
        - mvn dependency:tree -Pall -DoutputFile= ../releaselogs/x.x.x.XX.dependencybuild.txt -DappendOutput=true         
        - Review for snapshot dependencies
            - there should be none.
        - Compare with real jar versions from META-INF/MANIFEST.MF
            - use Tatletale for creating reports (http://www.jboss.org/tattletale/downloads)
        
    ** Testsuite execution **
        - "mvn clean verify > ../releaselogs/x.x.x.XX.testallreport.txt"
        - check ../releaselogs/x.x.x.XX.testallreport.txt
          - There should be no failures or errors.
        - run "find . -type d -name surefire-reports -exec cp -R {} ../releaselogs \;"        
        
    ** Compare the original distribtion to the one used for the testing.
        - Review changes in thirdparty jars, directories, and files.
            - <TODO: generate list of acceptable difference>             
    
    - Delete or rename to original dist.
    - Rename the "*.orig" back to the original name


Example verification
--------------------
* The list of examples below is extensive, and testing may not touch each.
    - This should be based on risk analysis, and release note review.
    - For a major/minor GA build they should all be tested.
    - Any examples that are not tested should be noted. 
* Verify the the following are accurate and up to date:
    - "$DIST/readme.txt" 
    - "$DIST/examples/readme.txt"    
* For these examples verify the following:
    - readme.txt is accurate
    - mvn clean package -P<container-profile> - more details in example root
    - mvn jboss-as:deploy (while export JBOSS_HOME=<installation_path>)
    - mvn clean verify -Darquillian=jbossas-managed-7 
    or
    - mvn clean verify -Darquillian=jbossas-remote-7
* Examples with "(tutorial)" are discussed in the reference guide tutorial.
    - document should be validated as well
    - including tomcat deployments
* JBoss AS 7.1.1 examples
  - blog (tutorial)
  - booking (tutorial)
  - contactlist
  - drools
  - dvdstore (tutorial)
  - excel (review docs)
  - groovybooking
  - hibernate (tutorial)
  - icefaces
  - itext
  - jpa 
  - mail
  - messages (tutorial)
  - nestedbooking
  - numberguess (tutorial)
  - quartz
  - registration (tutorial)
  - remoting/chatroom
  - remoting/gwt
  - remoting/helloworld
  - remoting/progressbar
  - seambay
  - seamdiscs
  - seampay
  - seamspace
  - spring
  - todo (tutorial)
  - ui
  - wicket (you should verify both buildtime instrumentation and runtime instrumentation)

Functional tests of Seam examples
---------------------------------
The functionality of most examples can be verified by automated tests. There are also jobs
at Hudson system which run the testsuites periodically. 

Set JBOSS_HOME or CATALINA_HOME environment property for automatic deployment of example for ftesting.
   
* JBoss 7.1.1 examples
  The following examples are tested automatically:
	
	* blog (tutorial)
	* booking (tutorial)
	* contactlist
	* drools
	* dvdstore (tutorial)
	* groovybooking
	* hibernate (tutorial)
	* jee5/booking
	* jpa
	* messages (tutorial)
	* nestedbooking
	* numberguess (tutorial)
	* openid (need to set properties openid.account and openid.password on command line for Maven)
	* quartz
	* registration (tutorial)
	* remoting/helloworld
	* remoting/gwt
	* remoting/chatroom
	* seambay
	* seamdiscs
	* seampay
	* seamspace
	* spring
	* toto (tutorial)
	* ui (except the s:resource/download link)

  The testsuite also verifies ability to deploy of the following examples:
	
	* excel
	* itext
	* mail
	* ui
    
  The following sample applications have to be verified manually:
   
	* excel
	* itext	
	* mail
	* nestedbooking (only nested conversation part)
	* ui (only s:resource/download link)
   
  All automated tests are executed from src/test/ftest directory.
  	* To run the automated tests:
	  mvn clean verify -Pftest-jbossas
	* To test examples manually:
      cd <example_name>
	  mvn clean package;
      export JBOSS_HOME=<installation-path-to-jboss-as-7.1.1>
      cd <example>-{ear,war} jboss-as:deploy 
	  ...test manually
	  mvn jboss-as:undeploy
 
Testing of Cluster - TODO update
------------------  
Currently testing of cluster environment is done through one automated test of booking example.
The main goal of this test is to simulate recovery from breakdown. 
This test should be executed autonomously (not as a part of test bundle).
To run the test follow these steps:
1) Specify jboss.home property in src/test/ftest/ftest.properties to point to your JBoss server folder
2) Create second "all" configuration of your JBossAS instance (name it for instance "all2")
3) Start first (master) instance of JBossAS: 
	JBOSS_HOME/bin/run.sh -c all -g DocsPartition -u 239.255.101.101 -b localhost -Djboss.messaging.ServerPeerID=1 
	-Djboss.service.binding.set=ports-default
4) Start second (slave) instance of JBossAS:
	JBOSS_HOME/bin/run.sh -c all2 -g DocsPartition -u 239.255.101.101 -b localhost -Djboss.messaging.ServerPeerID=2
	-Djboss.service.binding.set=ports-01
5) Go to src/test/ftest directory and run:
	ant test -Dtest=booking -Dcluster=true

** A booking example is configured to run in cluster only on JBoss AS. **

  
JBDS and seam-gen verification
------------------------------
These tests use a stable version of MySQL and the latest release of JBDS.  Be sure
to use the latest stable release of tools (3.3.0.GA at the time of writing), and
to also apply the JBoss tools provided WTP patch.  <TODO: update is version changes
behavior>

* export the following tables to MySQL:
CREATE TABLE `Person` (
  `username` varchar(10) NOT NULL,
  `name` varchar(100) NOT NULL,
  `birthdate` date default NULL,
  `address` varchar(600) NOT NULL,
  PRIMARY KEY  (`username`)
) ENGINE=InnoDB;

CREATE TABLE `Vehicle` (
  `ownerUsername` varchar(10) default NULL,
  `make` varchar(50) NOT NULL,
  `model` varchar(50) NOT NULL,
  `year` int(11) NOT NULL,
  `registration` varchar(8) NOT NULL,
  `state` varchar(2) NOT NULL,
  PRIMARY KEY USING BTREE (`registration`,`state`),
  KEY `ownerUsername` (`ownerUsername`),
  CONSTRAINT `owner` FOREIGN KEY (`ownerUsername`) REFERENCES `Person` (`username`)
) ENGINE=InnoDB;

<NOTE: seam-gen should be able to run without an internet connection.  To test 
       this you should first remove/rename your maven repository (document 
       option to set this as a property).  Then either disable networking, or 
       lock down a firewall on the test machine so that no requests are allowed 
       out.  Then test the various seam-gen targets. JBoss AS may not start in 
       the configuration so testing the live app may need to be done after
       executing the various seam-gen targets.  This does not have to be
       done for each test below but the different targets should be verified./>       

* Review seam-gen chapter of the reference guide
  - accurate and up to date
* seam-gen EAR 
  - run seam  with setup create-project and explode
      - during setup choose an EAR project
      - verify basic functionality
  - run seam generate-entities restart    
      - test the basic functionality of the app (CRUD on each table)
  - run "seam new-action new-form restart"
      - test both generated pages 
  - run seam test 
  - run "ant validate" in seam-gen project directory
* seam-gen WAR 
  - run seam with setup create-project and explode
      - during setup choose a WAR project
      - verify basic functionality
  - run seam generate-entities restart
      - test the basic functionality of the app (CRUD on each table)
  - run "seam new-action new-form restart"
      - test both generated pages
  - run seam test
  - run "ant validate" in seam-gen project directory
* JBDS - import the EAR seam-gen generated project into JBDS.
  - Enable Seam support in project properties
  - Check that EL code completion works for Seam components 
     - both project specific and core components
     - in views, and config files, etc... 
  - Check that Hibernate Console work on the project
     - expand the Configuration node
     - Open HQL editor and query "from SomeEntity" and execute the query
  - Execute testng testcases for project
* JBDS new WAR project
  - Reverse engineer entities from MySQL
  - Create "new Seam Action" and "new Seam Form"
  - Test generated pages (check hot deployment of Seam components, html)   
  - Test running unit tests from Eclipse
* JBDS new EAR project
  - Reverse engineer entities from MySQL
  - Create "new Seam Action" and "new Seam Form"
  - Test generated pages (check hot deployment of Seam components, html)  
  - Test running unit tests from JBDS
* JBDS - test a subset of the examples with testNG plugin.
    - See "/readme.txt" and "/examples/readme.txt" for details. 
    
Portlet Bridge Verification
--------------------------
* Use the latest released version of the JBoss Portlet Bridge (PBR) and GateIn.
  - for PBR source distribution is preferred
  - http://www.jboss.org/portletbridge
  - http://www.jboss.org/gatein

* Deploy PBR seam booking example following the PBR document instructions.
    - Review any known issues with the PBR in the PBR JIRA project.
    - simplified instructions for deploying seam booking:
      - run "mvn package" in $PBR_SRC/examples/seam/booking/
      - copy $PBR_SRC/examples/seam/booking/ear/target/seamEAR.ear into 
        running JBossAS in GateIn destribution
        
* Verify the example and functionality.
    - Update applications in application registry
      - in the GUI under http://localhost:8080/portal - Group -> Administration -> Application Registry,
        click Categories, Import Applications
    - Add new page with Seam booking portlets
      - in the GUI - click Group Editor -> Add Page
    - User authentication through portal
        - use default users, and new users that are created
    - Basic hotel booking
        - user both text search and search button 
        - change dates, and options in the booking
        - confirm, logout, login, verify confirmation, cancel confirmation
    - Conversation handling
        - launch several hotels booking conv. from the search page
        - individually confirm and switch between conversations.
        - <NOTE: Can not launch into multiple conversations ATM>
        
* Upgrade the Seam version in the Seam portlet booking example and follow 
  steps above
    - install the jars with current version of Seam into your local mvn repo
    - adjust the following files to contain current version of Seam:
      - $PBR_SRC/parent/pom.xml
    - build all the distribution by running "mvn -U clean install" in the $PBR_SRC dir
    - make sure the built booking application contains jars related to the current version of Seam
    - deploy the app
      
* Deploy a second version of the booking example as a separate portlet
    - <TODO: DEFER - this is not supported in the bridge yet/>
    - <TODO: there may be a new chatroom seam portlet for this testing/>
    
Document review
---------------
* Review the API javadocs in both IE and FF.
    - Specifically for version differences
    - This is not a full review at all
* Review the Reference Guide documentation in both IE and FF.
    - Review for format and code styles
    - Review for version numbers, and dependencies
    - Review any extensive changes based on release notes and the team. 
    - This is not a full review at all.

Final Build + Upload
--------------
* When ready for the release
    - checkout a clean version of the tag in a new/clean directory.
    - run "mvn clean install -Pdistribution -Dbuild.translations=true > ../releaselogs/x.x.x.XX.finaldistbuild.txt"
    - diff this to the one used for testing

* Follow instructions for sourceforge upload
    - Create md5 files for the ".zip" and ".tar.gz" files
    - Create md5 files for the archives
    - upload the .zip and .tar.gz and md5 files
    
* Login to sourceforge.org and go to http://sourceforge.net/projects/jboss/ project
    - Under admin tab click on "file releases"
    - Add a release to the "JBoss Seam" project
    - Set "Status" to "hidden"
    - Paste this release changelog snippet in the "changelog"
    - Paste this release readme.txt in the "release notes" 
    - Add the files uploaded to the release
    - Keep everything hidden for now.

* Upload the "seam-reference-guide/target/*.war" file content to "docs.jboss.com/seam/<NEW VERSION>" 
    - Note: you need to setup SSH key for that- contact jboss.org team if you didn't have it
    - Warning: if you updating/recreating latest symlinks for final releases, you need to create link
      on local and then rsync all to remote.
      for instance:
      mkdir 2.3.0.Final; 
      extract seam-reference-guide/target/*.war into above created directory
      ln -s 2.3.0.Final latest
      rsync -rva --protocol=28 . seam@filemgmt.jboss.org:/docs_htdocs/seam/
    
* Create draft of the documentation and download pages on seamframework.org
    - documentation points to "docs.jboss.com"
    - downloads point to sourceforge download page

Final Coordination and Announcement
-----------------------------------
* For a GA release and if its newest version of Seam
    - Update "http://docs.jboss.com/seam/latest" with the docs from this version.
        - Not for cr,alpha,beta releases
    - This can take a long time
* Update the DTDs and XSDs on jboss.org/schema/seam and jboss.org/dtd/seam    
    - Easiest way to use a script that checks for changes
        - <TODO add script to svn>
        - or copy all files into a directory, change to it and run:
        rsync -nrv --protocol=28 . seam@filemgmt.jboss.org:schema_htdocs/seam
        - if command successfully ends, run it without -n - first line
    - Update any changes to the site
* Login to sourceforge.org and modify the Seam release entry
    - Change the date to today
    - Change "Status" to active
    - Provide the link to the SF download page for the release for announcements.
* Update the documentation and download pages on seamframework.org with drafts.
* Update Jira so that version shows as "released" 
* Announce the release
    - Blog on in.relation.to
    - seamframework.org news, and forums
    - jboss.org news
    - TheServerSide.com

Update Demos (out of date - probably create openshift deployment)
------------
* This step is not needed for every point release:
* Upload the booking and dvdstore examples to demo.jboss.com
* <TODO more information on what is needed>


Notes
-----
* To reapply a tag:
 - First delete the original
    - git tag -d JBoss_Seam_x_x_x_XXX
 - Recreate the tag
    - git tag JBoss_Seam_x_x_x_XXX 

[FUTURE]
--------
* Store release related scripts (especially when more automated) in svn.
* Store release logs, and reports in svn.
* Find a jar/archive reporting tool for detailed dependency, version reports.