This article outlines the standard git and GitHub processes for working with Portlet Bridge repositories.
|JDK||>= 1.6||Yes, for Compilation|
|Apache Maven||>= 3.0||Yes|
|m2eclipse||1.0 SR2||Recommended for Eclipse|
One Time Setup
These steps are required the first time you're configuring your local environment for contributing to the Portlet Bridge.
Get a GitHub account
Fork the Portlet Bridge repository
- Use the web interface at http://github.com/
- Fork a copy from: https://github.com/jbossportletbridge/jbossportletbridge into your own GitHub account
Clone your newly forked repo into your local workspace
$ git clone email@example.com:[your user]/jbossportletbridge.git
$ cd jbossportletbridge
Add a remote reference to upstream repo
$ git remote add upstream firstname.lastname@example.org:jbossportletbridge/jbossportletbridge.git
$ git remote add upstream git://github.com/jbossportletbridge/jbossportletbridge.git
These steps outline the regular process to contribute code to Portlet Bridge once the initial setup of your local workspace is already complete.
Update your local repo
$ git pull --rebase upstream master
Note that --rebase will automatically move your local commits, if you have any, on top of the latest branch you pull from. If you don't have any commits it is safe to leave off, but for safety it doesn't hurt to use it each time just in case you have a commit you've forgotten about!
Build and run tests
$ mvn clean install
Work on an Issue
Perform all work related to an issue in a new branch named after the associated JIRA. If one does not exist, please ensure a new issue is created at https://issues.jboss.org/browse/PBR so that the contribution can be tracked, and community feedback provided.
$ git branch PBR-XXX $ git checkout PBR-XXX
Once you have completed making the necessary changes, and ensured that the tests pass by running "mvn clean install", add any changed files to the staging area and commit to the branch.
$ git status
to view which files are not currently staged
$ git add <files> -v
to add the files to staging
$ git commit -m '[PBR-XXX] Commit message referencing JIRA issue'
Rebase changes against master
Once all your commits for the issue have been made against your local topic branch, we need to rebase it against master in upstream to ensure that your commits are added on top of the current state of master. This will make it easier to incorporate your changes into the master branch, especially if there has been any significant time passed since you rebased at the beginning.
$ git pull --rebase upstream master
Pushing local changes to your repo
Now that you've sync'd your topic branch with upstream, it's time to push it to your GitHub repo.
$ git push origin PBR-XXX
Create a pull request
Now your updates are in your GitHub repo, you will need to notify the project that you have code for inclusion.
- In your GitHub repository, switch to the branch you pushed in the previous step
- Click on the "Pull Request" button
- Fill in the summary and details of your pull request
- Send the pull request
- Copy the pull request URL from the next page
- In the associated JIRA, click on the "Workflow" menu and choose "Link Pull Request". Paste the previously copied link and supply any additional comments.
After review a maintainer will merge your pull request into the upstream develop branch, update the affected JIRA issue, and reply when complete.
Updating local master branch once pull request closed
Once the pull request is complete and merged into the upstream master branch, it's important to update your local repository, and forked repo on GitHub, with the latest changes that include your pull request.
At this time it is also safe to delete your feature/branch from your local repo as you see fit.
$ git checkout master $ git pull --ff-only upstream master $ git push origin master