Development on SwitchYard

    These instructions are a modified version of the AS7 instructions ( to match the processes used by the SwitchYard team.      They are meant to be a loose guide - it is not required that you create a GitHub account and submit your patches through a pull request - it would be perfectly acceptable to submit a patch through JIRA.


    Setting up your workspace


    1. Create a github account


    2. Fork jboss-switchyard into your account


    3. Clone your newly forked copy onto your local workspace


    $ git clone[your user]/core.git
    remote: Counting objects: 1554, done.
    remote: Compressing objects: 100% (505/505), done.
    remote: Total 1554 (delta 667), reused 1353 (delta 543)
    Receiving objects: 100% (1554/1554), 188.97 KiB, done.
    Resolving deltas: 100% (667/667), done.

    4. Add a remote ref to upstream, for pulling future updates


    $ cd ../core
    git remote add upstream git:// 


    To see your remotes :


    $ git remote -v
    origin[your user]/core.git (fetch)
    origin[your user]/core.git (push)
    upstream   git:// (fetch)
    upstream   git:// (push)


    5. Use maven (SwitchYard is currently using maven 3.0.x)




    $ cd core

    $ mvn clean install


    [INFO] ------------------------------------------------------------------------
    [INFO] Reactor Summary:
    [INFO] SwitchYard ........................................ SUCCESS [8.365s]
    [INFO] Switchyard: Build ................................. SUCCESS [2.002s]
    [INFO] Switchyard: Core API .............................. SUCCESS [2.426s]
    [INFO] Switchyard: Test Utilities ........................ SUCCESS [1.643s]
    [INFO] Switchyard: Core Runtime .......................... SUCCESS [3.765s]
    [INFO] ------------------------------------------------------------------------
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 18.687s
    [INFO] Finished at: Wed Nov 03 13:53:56 EDT 2010
    [INFO] Final Memory: 25M/117M
    [INFO] ------------------------------------------------------------------------


    NOTE: if the build fails, try "$ mvn -U clean install". This will pull down changes in parent that might be causing the build failure.


    6. Pulling later updates from upstream

    $ git pull --rebase upstream master

    remote: Counting objects: 8, done.
    remote: Compressing objects: 100% (5/5), done.
    remote: Total 5 (delta 3), reused 0 (delta 0)
    Unpacking objects: 100% (5/5), done.
    * branch            master     -> FETCH_HEAD
    First, rewinding head to replay your work on top of it...
    Fast-forwarded master to fd771bb54bdbab544f0e21f4c3700d58c7c2e626.


     $ git config --global alias.up "pull --rebase"


    and then just use the new alias instead of pull


    $ git up upstream master

    7. Pushing pulled updates (or local commits if you aren't using topic branches) to your private github repo (origin)


    $ git push origin master
    Counting objects: 192, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (44/44), done.
    Writing objects: 100% (100/100), 10.67 KiB, done.
    Total 100 (delta 47), reused 100 (delta 47)
    To[your user]/core.git
       3382570..1fa25df  master -> master


    You might need to say -f to force the changes. Read the note on 12 though before you do it.


    Contributing a change


    1. Discuss your planned changes

    2. Make sure there is a JIRA somewhere for the enhancement/fix



    3. Create a simple topic branch in your fork to isolate that work


    git checkout -b SWITCHYARD-XXXX

    Note : See tips section for how to use a nice git prompt for tracking what branch you are in.



    4. Make changes and commit one or more times


    git commit -m 'SWITCHYARD-XXXX Frunubucate the Fromungulator'
    git commit -m 'SWITCHYARD-YYYY Tripple Performance of Fromungulation'


    Before committing your changes, please be sure to run both checkstyle and findbugs against your changes.  For example:



    mvn checkstyle:checkstyle


    In the core and the components modules, we run findbugs - to check whether your change has errors :


    mvn findbugs:check


    To generate findbugs.xml files to pinpoint findbugs violations and resolve errors :


    mvn findbugs:findbugs


    5. Rebase your branch against the latest master (applies your patches on top of master)


    git fetch upstream

    git rebase -i upstream/master

    # if you have conflicts fix them and rerun rebase

    # The -f, forces the push, alters history, see note below

    git push -f origin test



    The  -i triggers an interactive update which also allows you to combine  commits, alter commit messages etc. It's a good idea to make the commit  log very nice for external consumption. Note that this alters history,  which while great for making a clean patch, is unfriendly to anyone who  has forked your branch. Therefore you want to make sure that you either  work in a branch that you don't share, or if you do share it, tell them  you are about to revise the branch history (and thus, they will then  need to rebase on top of your branch once you push it out).

    6. Get your changes merged into upstream


    Browse to your fork on github :[your user]/core 



    Use the "Switch Branches" pull-down to select your branch (test in this instance)



    Press the Pull Request button to create pull request for your changes




    Submit the pull request with a description of your changes and any instructions that may be needed.


    Once you've submitted the pull request, link it back to the JIRA as follows:



    Processing a Pull Request

    After review a maintainer will merge your patch, update/resolve issues by request, and reply when complete.  The following are step by step instructions for processing a pull request.


    If you haven't done so already, clone the SwitchYard repo's into a separate work area (e.g. ~/dev/src/git/pullrequests/switchyard):

    These clones should be used solely for processing pull requests (i.e. don't do any development work in them).


    Process the request:

    1. Make sure the local repo is up to date.

        $ git fetch





        $ git pull --rebase origin/master




    2. Create a working branch to merge the changes into (to validate the build, run tests, etc.).

        $ git checkout -b SWITCHYARD-XYZ




    3. Pull the changes into the branch.
    4. Rebase the branch against master (NO MERGE COMMITS)

        $ git rebase master




    5. Test the changes (Note: Only core and components need checkstyle and findbugs to be enabled right now. Just use "mvn -U clean install" for other repositories)

        $ mvn -U clean install checkstyle:check findbugs:check




    6. Switch back to master

        $ git checkout master




    7. Merge the working branch into master

        $ git merge SWITCHYARD-XYZ




    8. Verify the history looks good

        $ git log




    9. Push the changes

        $ git push origin master




    10. Close out the pull request (may have automatically been closed after the push).
    11. Repeat this process for each pull request linked to the affected JIRA.
    12. Update the status of the JIRA.


    Dealing with merge commits when processing a pull request

    There are three situations in which you can get a merge commit when processing a pull request:

    1) The parent for the commit(s) in a pull request are different from the current upstream master.  This can happen if the person submitting the pull request failed to rebase on upstream master before submitting.  It can also happen if multiple pull requests are in the queue, as the later pull requests will not have commits from the earlier commits.

    2) Similar situation to #1, but the merge includes changes to files that are part of the pull request.

    3) You have local commits in the branch you are using to process the pull request.


    For #1, it's OK to move ahead with the push.

    For #2, talk to the person submitting the pull request and determine if they want to resubmit or they would like you to resolve the merge.

    For #3, don't ever do this!


    Note: if you are in case  #1, run "git status" before pushing the pull request.  You shoud be two commits ahead of master - the original commit and your merge commit.  If you're more than two commits ahead of master, something went wrong and you should not push.


    Changes to Core which impact Components

    If you push a change to core that impacts components (e.g. core API change breaks component compile or core runtime change breaks component test), then you must push an updated set of artifacts to the snapshot repository.  It is the responsibility of the person pushing the change to make sure this happens.