Version 68
Created by rachmato on Oct 29, 2007 11:55 AM. Last modified by rachmato on Nov 11, 2009 10:53 AM.

    References

     

     

    -

    General Information about JGroups

    -

    JGroups is hosted on SourceForge and includes the following resources:

     

     

    You will need to create a SourceForge account and have Bela Ban assign you appropriate permissions to have release engineer access to the various resources. Having release engineer access allows you to

    • login to SourceForge host via a shell and access the shared file system (needed to update documentation)

    • use the File Release System to upload new releases and make them available (needed to make new releases available to the community)

    You should also subscribe to the mailing lists javagroups-users, javagroups-development.

     

    Access to the codebase by anonymous CVS:

    cvs -d :pserver:anonymous@anoncvs.cvs.sourceforge.net:/cvsroot/javagroups co JGroups

     

    Access to the codebase by account mysfid:

    cvs -d :ext:mysfid@javagroups.cvs.sourceforge.net:/cvsroot/javagroups co JGroups

     

    Access to the SourceForge filesystem by account mysfid:

    ssh mysfid@shell.sourceforge.net

     

    The javagroups project files are located in the SourceForge filesystem at /home/groups/j/ja/javagroups. Directory htdocs contains files associated with the JGroups web page.

     

    -

    Pre-release Steps: These steps are carried out in order to determine if a release of the codebase should be performed.

    -

    Commit all pending changes

     

    Make sure the codebase is up to date and that all pending changes are committed. Liase with Bela Ban and Vladimir Blagojevic.

     

    Run Unit Tests

     

    Unit tests are executed by executing the at target 'all-tests-cc'. Reports are generated using the target 'reports'. The Java versions to be used for testing (and building the distribution) are listed at http://wiki.jboss.org/wiki/Wiki.jsp?page=JDKs. The base version refers to FILL ME IN.

     

    ./build.sh -Dbind_addr=$MYTESTIP_1 all-tests-cc
./build.sh reports

     

    These tests take about 1 hour 20 minutes to execute.

     

    NOTE: JGroups depends on UDP multicast communication and point to point UDP and TCP communication. The tests in the testsuite run on a single host. When running the tests, JGroups need to bind to a network interface, either a non-loopback interface, or the loopback interface. When running the tests, you need to make sure that the interface chosen is set up to be able to send and receive the required messages. Kernel-based firewalls and routing tables can affect the reults of the tests dramatically. For example, to run the testsuite using the loopback address, 127.0.0.1, you need to set up a multicast route on lo. (more details required).

     

    Run Manual Tests

     

    The manual tests ensure that JGroups works correctly in the presence of failures by simulating (manually) process and network switch failures. See the document doc/tests/ManualTests.txt for instructions on how to run the tests. You will need a hardware switch to complete the second set of tests. These tests take several hours to run.

     

    A few useful tips when running the manual tests:

    • don't forget to specify a -Djgroups.bind_addr to make sure your group members are listening on the correct interface

    • Channel.BLOCK option can be set by the org.jgroups.Draw parameter -use_blocking

    • to enable isolated group members to still draw, set -Djgroups.udp.loopback=true

    • there will be a number of combinations to test, namely {udp,tcp} x {fd,fd_sock} x {flush,noflush} and for the flush tests, {blocking, no blocking}. I find it useful to create new configurations, one for each of the combinations possible, such as udp-fd-noflush.xml or tcp-fdsock-flush.xml. You need to rebuild the dist after creating these files to cause them to be in jgroups-all.jar.

    • don't forget to add -Djgroups.tcpping.initial_hosts=hostIP1{FOOTNOTE DEF 7800 7800},hostIP2{FOOTNOTE DEF 7800 7800} when running the TCP tests so that group members can find each other

     

    Run Performance Tests

     

    See the wiki page http://wiki.jboss.org/wiki/Wiki.jsp?page=PerfTests for instructions on how to run the JGroups performance tests.

     

    Word of warning

     

    Don't underestimate the time it takes to resolve any bugs you may find during testing. This is the reason for continuous integration. A week before the release is planned, run the testsuite each day and work the bugs out over time. Also, don't forget the dopcumentation!.

     

     

    Based on the results of the unit tests, manual tests and performance tests, a decision will be made by the JGroups developers whether or not to perform a release of JGroups. If a release is to be performed, complete the release steps below.

    -

    Release Steps: These steps are carried out in order to make a release of JGroups available to the community.

    -

    Gather "individual release notes" from change authors

     

    Each developer that authored significant changes going into the current release must submit to the Project Lead a "individual release note". The node describes over a couple of paragraphs (shorter the better) and in human readable format, important changes such as:

    • New features

    • Critical bug fixes (correcting spelling of a trace log does not qualify)

    • Configuration changes

    • Compatibility changes

     

    The individual notes will be collated by the Project Lead into Release Notes. The style used in JGroups is to review a subset of the key JIRA issues (features, bugs, tasks) which the release addresses, and summarise them concisely to make their point felt. Then reference the JIRA reference.

     

    Set release version numbers

     

    Set the version numbers in the following files:

    src/org/jgroups/Version.java
conf/manifest.mf
build.xml
jgroups-pom.xml

    Update the codebase with the new versions.

     

    Tag the release

     

    Create a CVS tag for the release: JGroups_x_y_z. Before you tag the release, rack your brains to remember if you have forgotten anything (documentation, javadocs, being able to cleanly build not only the release but also the docs, release notes,...)

     

    Update the tags wiki

     

    Add tag information to wiki branches wiki.

     

    Create a distribution

     

    ./build.sh dist

     

    The files making up the JGroups distribution are:

    dist/JGroups-x.y.z-rel.bin.zip
dist/JGroups-x.y.z-rel.src.zip

     

    Create the documentation

     

    There are three sets of focumentation for JGroups: the manual, the tutorial and the javadoc. The manual and tutorial come in pdf and html format.

     

    To build the pdf and html copies of the manual and tutorial:

     

    ./build.sh docs

     

    This produces the files doc/manual/build/ and doc/tutorial/build/ (for JGroups 2.4. and 2.5. there is no tutorial).

     

    To build the javadoc:

     

    ./build.sh javadoc

     

    This produces the files dist/javadoc/.

     

    Upload the distribution to the JGroups web site

     

    Once the distribution files have been built, they need to be uploaded to SourceForge and made available to the community. The SourceForge File Release System is used for this purpose. See SourceForge documentation page (https://sourceforge.net/apps/trac/sourceforge/wiki) entries "Release Files For Download" and "File Management Service" for general instructions. The File Release System makes the distribution files you upload available for download by community users.

     

    NOTE: SourceForge has recently introduced web-based access for creating new directories and uploading files.

    1. Log in as a SourceForge user with project maintainer privilidges

    2. Select the Develop tab, then the Project Admin tab and finally the File Manager tab

    3. In File Manager, you will see a tree of JGroups distribution directories, as well as a set of commands Create New Folder, Upload File, Refresh and Help. Also, on the left of each file or folder name, there is a wheel - clicking on this wheel presents a menu of actions which may be performed. Finally, by clicking on a file or folder, you can change some of its attributes:  is it a release notes file, if not , which is the release notes file, which OSs does the distribution apply to.

    4. Create a new folder for your release.

    5. Upload the distribution files as well as the release notes file.

    6. Mark the release notes file as release note by changing their attributes. Change the attributes of the binary distribution to point to the release notes.

    7. Log out.

     

    Old method of uploading release (deprecated)

    SourceForge requires using ftp to transfer the distribution files from your local machine to the /incoming directory on SourceForge. Once files are uploaded to the /incoming directory, the Release File System can be used to select them to form part of the new release.

     

    > sftp mysfid@frs.sourceforge.net (respond to password: with you sfpwd)
> binary
> cd uploads
> put JGroups-x.y.z-bin.zip
> put JGroups-x.y.z-src.zip
> bye
> exit

     

     

    The File Release System is accessed by logging in to SourceForge, navigating to the Javagroups project page, and accessing Download->BrowseAllPackages and then ManagePackages/Releases. The File Release System will take you through several steps:

     

    1. Create a package, if one does not yet exist

    2. Specify a release name to create the release to associate the uploaded files with one another (e.g. 2.5.2)

    3. Select the files to be released from the list (the list of files in /incoming)

    4. Paste in Change Log and Release Notes

    5. Specify architecture (Platform-Independent) and File Type (.zip) for the uploaded files and refresh

    6. Send email notification to all registered listeners (email is generic - no need to write)

     

    It is helpful to read the documentation E01 before attempting this for the first time.

     

    You will be asked to provide Release Notes and Change Log. The Release Notes should be copied from docs/ReleaseNotes-x.y.z.txt - these describe the key changes made in the releaase. The ChangeLog is created automatically by JIRA: log into JIRA, go to the JGroups project, select OpenIssues->ReleaseNotes-> Select version x.y.z, Select style text, and the JIRA issues making up the ChangeLog will be presented. Copy and Paste into the File Release System field.

     

    Upload the documentation to the web site

     

    (This needs to be updated - SF has changes its file management system).

    The documentation consists of manual, tutorial and javadoc files which need to be placed in certain directories in the javagroups directory on the SourceForge filesystem. The documentation is updated by copying the new manual, tutorial and javadoc files from the distribution you built into the appropriate directories. NOTE: I believe this only holds for the latest version of JGroups - there is not a separate directory for each version!

     

    JGROUPS_WEBPG_HOME=/home/groups/j/ja/javagroups/htdocs/javagroupsnew
# copy the manual
scp -r doc/manual/build/en/* mysfid@shell.sf.net:$JGROUPS_WEBPG_HOME/docs/manual
# copy the tutorial
scp -r doc/tutorial/build/en/* mysfid@shell.sf.net:$JGROUPS_WEBPG_HOME/docs/tutorial
# copy the manual
scp -r dist/javadoc/* mysfid@shell.sf.net:$JGROUPS_WEBPG_HOME/docs/javadoc

     

    There is a readymade script bin/upload_manual.sh which can be used for this purpose. Check access to the documentation after making the copy.

     

    Update jboss.org download pages

     

    On jboss.org, there is a page for JGroups at http://labs.jboss.com/jgroups/. The sources for this page are stored in svn, at http://cms.labs.jboss.com/prod/forge/portal-content/default/members/jgroups. Check out this directory.

     

    The file project.xml contains a

    element makes use of a sourceforge PHP command - you need to fill in group_id=6081 (fixed), package_id=94868 (fixed) and a release_id=xxxxxx (variable). Pick up the release_id by going to sourceforge.net, viewing the JGroups downloads page and hovering the mouse over page elements.

     

    The static content (the page http://labs.jboss.com/jgroups points to this) is maintained in the freezone directory. See the index.html file there.

     

    Update the repositories with the new release jar(s)

     

    There are two repositories to be updated:

     

    buildmagic repository

     

    The jgroups-all.jar from the dist directory needs to be placed in the buildmagic repository, renamed as jgroups.jar and the associated

    repository meta-data updated.

     

    1. Using svn, checkout the jgroups directory containing the ant-compatible JGroups releases:

     

    Check out into a directory of your choice, referred to as $JG_REPO:

    > svn co https://svn.jboss.org/repos/repository.jboss.org/jgroups $JG_REPO

     

    2. Create the subdirectory for the new release

     

    Create a new subdirectory of $JG_REPO, named by release, and a lib subdirectory (e.g. for a <release-name> release):

     

    > cd $JG_REPO
> mkdir <release-name>
> mkdir <release-name>/lib

     

    3. Copy the new jar into the lib directory

     

    > cp $JGROUPS/dist/jgroups-all.jar $JG_REPO/<release-name>/lib/jgroups.jar

     

    4. Update the repository meta-data for the new entry

     

    Each release subdirectory has a meta-data file called component-info.xml, which resides at $JG_REPO/<release-name>/component-info.xml.

    It should look something like this:

     

    <project name="jgroups-component-info">
  <component id="jgroups" 
             licenseType="lgpl" 
             version="2.6.2" 
             projectHome="http://www.jgroups.org" 
             description="JGroups is a toolkit for ...">
    <artifact id="jgroups.jar"></artifact>
    <export>
      <include input="jgroups.jar"></include>
    </export>
  </component>
</project>

     

    A simple way to arrange for this is to copy an existing component-info.xml entry into place and update the version number.

     

    3. Using svn, add the new directories and files to version control and commit the changes to the buildmagic repo.

     

    For more detailed instructions on updating the ant repository, see the wiki page JBossBuild

     

    maven2 repository

     

    The jgroups-all.jar and the jgroups-sources.jar from the dist directory need to be placed in the maven2 repository, renamed, and the associated repository meta-data updated.

     

    1. using svn, checkout the jgroups directory containing the maven-compatible JGroups releases:

     

    Check out into a directory of your choice, referred to as $JG_REPO:

    > svn co https://svn.jboss.org/repos/repository.jboss.org/maven2/jgroups/jgroups $JG_REPO

     

    2. Update the working copy in $JG_REPO with the JGroups binary jar

     

    > mvn deploy:deploy-file -Dfile=$JGROUPS/dist/jgroups-all.jar \ 
                         -Durl=file://$JG_REPO \
                         -DpomFile=$JGROUPS/jgroups-pom.xml

     

    This command will do the following:

    • use the pom you passed to determine groupId/artifactId/version

    • create a directory in the svn working copy you checked out with the groupId/artifactID/version number

    • copy the jar into the directory and name it by version number

    • copy the pom passed into the directory

    • create checksums for the jar and the pom

    • update the maven meta-data files in the parent directory.

     

    You can then check the newly created files to see that all is in order before committing (see 4).

    NOTE: you need to make sure that the version number in the pom is updated before performing this operation!

     

     

    3. Update the working copy in $JG_REPO with the JGroups sources jar

     

    > mvn deploy:deploy-file -Dfile=$JGROUPS/dist/jgroups-sources.jar \ 
                         -Durl=file://$JG_REPO \
                         -DpomFile=$JGROUPS/jgroups-pom.xml \
                -Dclassifier=sources

    This command performs the same actions as in step 2, except that the classifier parameter causes the

    file to retain the sources suffix in the repository.

     

    4. Using svn, add the new directories and files to version control and commit the changes to the maven2 repo.

     

    For more detailed instructions on updating the maven repsitory, see the wiki page MavenReleaseRepository

    maven2 snapshot repository

     

    You may also need to make available copies of the jgroups-all.jar and the jgroups-sources.jar as a snapshot, and not a formal release. This is typically required when testing software based on a maven build which (i) has a dependency on JGroups, and (ii) has some issue which is related to JGroups. In this case, a patched version of JGroups (which affects the issue) can be made available in the snapshot reposority and imported into the maven build.

     

    The snapshot repository is located at https://snapshots.jboss.org/maven2.

     

    The procredure for making snapshots available in the snapshot repository is different from making releases available in the maven release repository. Access to the snapshots repository is via WebDav, and no checking out of repository directories is required. Access is controlled based on your jboss.org userid and password. Some initial customization of your maven settings is required, in order to define the location of the snapshots repo as wellas the webDAV settings. See the instructions at http://www.jboss.org/community/wiki/MavenSnapshotRepository in the section Deploying a Maven Project to the Repository. I have found that adding (to your maven settings) a <server/> entry specifying WebDAV options and a <repositories/> entry to identify the snapshot repository in your default profile is sufficient.

     

    Once the maven settings have been adjusted for accessing the snapshots repo, you may add snapshots (jgroups-all.jar and jgroups-sources.jar) to the repository using the following commands:

    > mvn deploy:deploy-file -Dfile=$JGROUPS/dist/jgroups-all.jar \ 
                         -Durl=dav:https://snapshots.jboss.org/maven2 \
                         -DrepositoryId=snapshots.jboss.org \
                         -DgroupId=jgroups \
                         -DartifactId=jgroups \
                         -Dversion=x.y.z-SNAPSHOT \
                         -DgeneratePom=true \
                         -DuniqueVersion=false

    Set the version x.y.z to the JGroups version in question. Usually snapshots are versioned with timestamps, but this causes problems when adding multiple artifacts to a single snapshots deployment (i.e. when we want to add in the sources for the same snapshot). Specifying unqiueVersion=true causes snapshots to be unversioned; in practice, this means that one stapshot will overwrite the preceeding one, if it exists.

     

    In order to add the sources jars to the snapshot, use the command:

    > mvn deploy:deploy-file -Dfile=$JGROUPS/dist/jgroups-sources.jar \ 
                         -Durl=dav:https://snapshots.jboss.org/maven2 \
                         -DrepositoryId=snapshots.jboss.org \
                         -DgroupId=jgroups \
                         -DartifactId=jgroups \
                         -Dversion=x.y.z-SNAPSHOT \
                         -DgeneratePom=true \
                         -DuniqueVersion=false \
                         -Dclassifier=sources

    Note the classifier=sources parameter.

     

    It is possible to shorten this command line by incorporating the parameters into the JGroups pom, and specifying the pom instead, as was done with deploying to the release repository.

    Announce the release

     

    Send out an email containing a short greeting announcing the new release, followed by (ii) the content of the release notes, followed by (iii) the content of the ChangeLog to the mailing lists javagroups-users@lists.sourceforge.net, javagroups-development@lists.sourceforge.net and jboss-development@lists.jboss.org.

    8865 Views Categories: Tags: