This article outlines the standard git and GitHub processes for working with Portlet Bridge repositories.

Prerequisites

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

http://github.com/

Fork the Portlet Bridge repository

1. Use the web interface at http://github.com/
2. 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 git@github.com:[your user]/jbossportletbridge.git

$ cd jbossportletbridge

Add a remote reference to upstream repo

For Committers:

$ git remote add upstream git@github.com:jbossportletbridge/jbossportletbridge.git

For Contributors:

$ git remote add upstream git://github.com/jbossportletbridge/jbossportletbridge.git

Development Process

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

Commit changes

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.

Run

$ 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.

1. In your GitHub repository, switch to the branch you pushed in the previous step
2. Click on the "Pull Request" button
3. Fill in the summary and details of your pull request
4. Send the pull request
5. Copy the pull request URL from the next page
6. 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