Information for GPars Developers
The JIRA issue tracker: http://jira.codehaus.org/browse/GPARS - no longer works.
The Git repository held at GitHub is the official mainline: Our Repo is here.
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.
A repository that was a mirror of the GitHub repository was maintained at Codehaus (before they closed) in order to continue integration with various continuous integration servers (over time more of this will migrate to GitHub). Also that Codehaus project was the location of our issue tracker and the route for artifacts to get into the Maven repository.
You should never need to clone this repository, but for completeness, the command:
git clone https://github.com/GPars/GPars.git
creates a clone of the repository in the subdirectory GPars. This URL gives read-only access to the repository.
Project committers and contributors typically keep their personal clones of the main repository for feature branches:
Building The Project
The Gradle build tool wrapper is included, so running the gradlew build script will download and setup gradle for the project and execute the build.
Create an IDEA or Eclipse project files through gradlew idea or gradlew eclipse commands and you are ready to go.
Upon start or right before building the project, IDEA will prompt you for the JDK version 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. These results are 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 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.
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.
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 will 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, or where there are issues start a debate on the email list.
When changes have been reviewed and agreed, one of the committing authors agrees 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.
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)
Install Gradle from an up-to-date Gradle Trunk or the new SDK installer tool
Edit the build.gradle or gradle.properties file to change the number of the wrapper to the new one.
If the wrapper is a snapshot, then edit wrapper/gradle-wrapper.properties to add back in the missing snapshots from the repository URL
Check the result with
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
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
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 or a proper release
Make sure all demo programs work
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 repository credentials are in $USER_HOME/.gradle/gradle.properties or specify your credentials directly in the uploadArchives task in build.gradle and add uploadArchive task to the desired build task:
Confirm the artifacts have been successfully uploaded 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. Cleanup The Snapshot Repository
After a proper release, the older snapshot artifacts should be removed manually from the snapshot repository. Any webdav client, like e.g. AnyClient
http://www.anyclient.com/download.html should be capable.
8. Upload The User Guide and Docs
User Guide at /build/docs/manual should be uploaded to GPars Document Website .
The javadoc and groovydoc folders should be copied too
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.