Version 5

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

     

    Prerequisites

    Product
    Version
    Required
    JDK>= 1.6Yes, for Compilation
    Apache Maven>= 3.0Yes
    Giti.e. 1.7.1.1
    Eclipse IDE

    m2eclipse1.0 SR2Recommended for Eclipse
    IntelliJ IDEA

     

    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