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
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
- On the forums - http://community.jboss.org/en/switchyard/dev?view=discussions
- On IRC - irc://irc.freenode.org/switchyard
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'
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 :
https://github.com/[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):
$ git clone git@github.com:jboss-switchyard/components.git
These clones should be used solely for processing pull requests (i.e. don't do any development work in them).
Process the request:
- Make sure the local repo is up to date.
$ git fetch
$ git pull --rebase origin/master
- Create a working branch to merge the changes into (to validate the build, run tests, etc.).
$ git checkout -b SWITCHYARD-XYZ
- Pull the changes into the branch.
$ git pull https://github.com/<user>/<repo> SWITCHYARD-XYZ
- Rebase the branch against master (NO MERGE COMMITS)
$ git rebase master
- 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
- Switch back to master
$ git checkout master
- Merge the working branch into master
$ git merge SWITCHYARD-XYZ
- Verify the history looks good
$ git log
- Push the changes
$ git push origin master
- Close out the pull request (may have automatically been closed after the push).
- Repeat this process for each pull request linked to the affected JIRA.
- 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.
Comments