Information for GPars developers

Build info

The continuous integration build can be found under:

Build Server	Link	Note
JetBrains TeamCity	http://teamcity.jetbrains.com/project.html?projectId=project34	needs registration
Codehaus Bamboo	http://bamboo.ci.codehaus.org/browse/GPARS-DEF

Issue Tracker

The JIRA issue tracker:http://jira.codehaus.org/browse/GPARS

Source Repository

The Git repository held at GitHub is the official mainline:

git://github.com/GPars/GPars.git

To work on the codebase please fork the repository on GitHub in the usual GitHub workflow way. Keeping the master branch as a mirror of the mainline, working on a feature branch and then sending in pull requests based on that feature branch seems to be the best way of working. Please refer to the Git and GitHub documentation for any further details on using Git and GitHub.

Mirror Repository

A repository that is a mirror of the GitHub repository is maintained at Codehaus in order to continue integration with various continuous integration servers (over time more of this will migrate to GitHub). Also this Codehaus project remains the location of the issue tracker and is the route for artefacts to get into the Maven repository.

You should never need to clone this repository, but for completeness, the command:

git clone git://git.codehaus.org/gpars.git GPars

creates a clone of the repository in the subdirectory GPars. The above URL gives read-only access to the repository. Those people with write access to the repository should use the URL:

ssh://git@git.codehaus.org/gpars.git

Personal clones

Project commiters and contributors typically keep their personal clones of the main repository for feature branches:

Václav Pech

git://github.com/vaclav/GPars.git

Russel Winder

git://github.com/russel/GPars.git

Building the project

The gradlew script will download and setup gradle for the project and execute the build.

gradlew clean build

IDE integration

Create an IDEA or Eclipse project files through gradlew idea or gradlew eclipse commands and you are ready to go.

IntelliJ IDEA

Upon start or right before building the project IDEA will prompt you for the JDK to use. Once you specify that on the project level, you should be good to go.

The default IntelliJ IDEA project file

GPars holds a default IDEA project file in the root of the project and is named GPars_IDEAX.ipr. This project serves as a master copy for the generated project files (see above) and also to configure our Continuous Integraion. If you for some reason decide to use the default project file, you need to go through a few configuraion steps first.

The first time you open the project you will be prompted to enter a PROJECT_JDK_NAME and a MAVEN_REPOSITORY variable. These are IDEA variables and not system variables. The result is stored in your home directory.
Each developer can have a unique value. For example, your MAVEN_REPOSITORY may be a path on your disk, and PROJECT_JDK_NAME can be any string value, e.g. "1.6". This is the name of the Global JDK defined defined within IDEA. You can setup a global JDK in IDEA under File->Project Structure->SDKs. There is a little text box to fill in where you give the JDK a name. Whatever you typed into this textbox needs is what needs to be typed into the IDEA Environment Variable screen for PROJECT_JDK_NAME.

The MAVEN_REPOSITORY variable should point to your local maven repository, which IDEA will be using to keep downloadable artifacts of third-party libraries that are needed to build and run GPars. You need to populate the repo first for IDEA to find the necessary artifacts. The best way to do so is to open the /java-demo/pom.xml file (provided Maven support is enabled in your IDEA installation) and ask IDEA to Import changes. Alternatively you can use the Refresh button in the Maven tool window.
Future IDEA environment variables can be declared within the .ipr and .iml with the syntax $VAR_NAME$. Anything undefined at project startup will prompt the user for entry.

Code style

If you plan to contribute code to the project, please check out our brief code style guide to make sure your contribution fits seamlessly with the rest of the code base.

VCS workflow

People clone the main GitHub repository
People create feature branches in their personal cloned repository
People publish their work to possibly cooperate with others on the feature and when ready for review announce the branch asking for people to review. (git push [mirrorRepo] myFeature)
People reviewing the feature branch fetch the changesets from the public mirror and review running tests ([git remote add mirrorRepo mirrorRepoUrl;] git fetch [mirrorRepo] myFeature)
If there are no worries about the proposed changes then people say so, where there are issues start a debate on the email list.
When changes have been reviewed and agreed, one of the committing authors is agreed to merge the branch into their master and pushes to the GitHub main repository (and their public mirror repository of course) (git checkout master;git pull; git merge --no-ff myFeature;git push)

Notice the --no-ff flag when merging.
Note that this workflow is applicable to all people whether they are committing authors or not. It's just that non-committing authors have to convince a committing author to do the commit. A consequence is that people should not be advised to submit patches on JIRA issues, but instead to specify where their feature branch is so it can be pulled. Obviously patches work as well but the whole point is for everyone to publish their feature branches so others can review them in a VCS context.

Simplified workflow

Trivial spelling error fixes, extra tests that don't necessitate a change of code but just extend the test coverage, and very simple (non-controversial) bug fixes with their tests are currently exempt from having a review process. Discretion on the part of committing developers is required here. (git pull; fix; commit; git push) or (git pull; git checkout -b myFix; fix; commit; git checkout master; git pull; git merge --no-ff myFix;git push)

Upgrading Gradle

Install Gradle from an up to date Gradle Trunk.
Edit the build.gradle file to change the number of the wrapper to the new one.
Run "gradle wrapper"
If the wrapper is a snapshot the edit wrapper/gradle-wrapper.properties to add back in the missing snapshots from the repository URL
Check the result with "git diff".
Check the results with "gradlew clean test".
If on Linux check that the Bamboo build should work with "env -i ./bambooBuild"
If everything is successful commit the result "git commit -m ' . . .' -a"
Push to the mainline "git push"
Push to the personal mirror "git push --mirror . . . "
Wait expectantly to see if Bamboo works or not . . .

The release plan

1. Set version

In build.gradle and in doc.properties set the version property

version = '1.0.0'

Also update the ReleaseNotes.txt file.

2.Write what's new

Update the "What's new" section of the user guide as well as the ReleaseNotes.txt file

3. Tag the sources

After a proper release create a tag in the VCS with sources that were used to make the release. Label the tab using the release-x.x pattern.

4. Build the project

Issue a full rebuild either for a snapshot

gradlew clean build [uploadArchives]

or a proper release

gradlew clean release [uploadArchives]

Make sure all demos work

gradlew demo

5. Upload the artifacts

Run the Release build plan on Bamboo, which will make all the artifacts available for download.

6. Update the maven repository

Make sure your codehaus credentials are in $USER_HOME/.gradle/gradle.properties

gpars_repoUserName=xxx
gpars_repoPassword=xxx

or specify your credentials directly in the uploadArchives task in build.gradle and add uploadArchive task to the desired build task:

gradlew build uploadArchives

Or

gradlew release uploadArchives

Check out that the artifacts have been successfully uploaded either at https://dav.codehaus.org/snapshots.repository/gpars/ for snapshots or at https://dav.codehaus.org/repository/gpars/ for proper releases. Within a couple of hours the new proper release should be propagated into the maven central repository at http://repo1.maven.org/maven2/org/codehaus/gpars/gpars/.

7. Clean up the snapshot repository

After a proper release the older snapshot artifacts should be removed manually from the snapshot repository at https://dav.codehaus.org/snapshots.repository/gpars/. Any webdav client, like e.g. AnyClient (http://www.anyclient.com/download.html) should be capable to do so.

8. Upload the User Guide and docs

The generated User Guide at /build/docs/manual should be uploaded to http://www.gpars.org/guide/ .

The javadoc and groovydoc folders should be copied to http://gpars.org/javadoc/index.html and http://gpars.org/groovydoc/index.html respectively.

9. Update the version

After a proper release the version in the build file has to be changed to the next version.

10. Update JIRA

Proper releases should be also closed in JIRA.

11. Tell the world

People are impatiently waiting for the new GPars features so now it is the highest time to tell them. New proper releases should be announced at the following mailing lists and sites:

announce@gpars.codehaus.org
user@gpars.codehaus.org
dev@gpars.codehaus.org
user@groovy.codehaus.org
http://docs.codehaus.org/pages/createblogpost.action?spaceKey=GPARS
Any other relevant channel

Xircles Project Page

http://xircles.codehaus.org/projects/gpars

After a proper release create a tag in the VCS with sources that were used to make the release. Label the tab using the release-x.x pattern.