Development on SwitchYard


These instructions are a modified version of the AS7 instructions (http://community.jboss.org/wiki/HackingonAS7) 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

http://github.com

 

2. Fork jboss-switchyard into your account

http://github.com/jboss-switchyard/core

 

3. Clone your newly forked copy onto your local workspace

 

$ git clone git@github.com:[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://github.com/jboss-switchyard/core.git 

 

To see your remotes :

 

$ git remote -v
origin    git@github.com:[your user]/core.git (fetch)
origin    git@github.com:[your user]/core.git (push)
upstream   git://github.com/jboss-switchyard/core.git (fetch)
upstream   git://github.com/jboss-switchyard/core.git (push)

 

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

 

 

 


$ cd core

$ mvn clean install

.....

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[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] BUILD SUCCESS
[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.
From github.com:jboss-switchyard/core
* 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 git@github.com:[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

 

https://jira.jboss.org/browse/SWITCHYARD

 

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'

 

Note: before committing your changes, please be sure to run checkstyle against your changes.  For example:

mvn checkstyle:checkstyle

 

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 :

https://github.com/[your user]/core 

 

 

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

githubbranch.png

 

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

 

 

pullrequest.png

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:

link_pull_request.jpg

 

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.