We use git and GitHub to develop SAMOA, so you need to open an account at http://github.com first.
In the guide I assume <user> is your actual GitHub username. I also assume familiarity with git's concepts.
Commands to be entered on the command line are shown in monospace font:
example command
example output
Fork the repository on GitHub
The repository is at https://github.com/apache/incubator-samoa.
It is a mirror of the official Apache git repository (git://git.apache.org/incubator-samoa.git).
Fork it by clicking on the Fork button. You will get a complete copy of the repository in your GitHub account at https://github.com/<user>/incubator-samoa.
Clone the repository on your local machine
You need to have git installed on your local machine.
git clone git@github.com:<user>/incubator-samoa.git
Refer to GitHub's guide if you have trouble using this SSH remote URL (https://help.github.com/articles/which-remote-url-should-i-use).
Now you have a clone of the repository on your local machine. The clone is configured with an origin remote pointing at your GitHub fork.
cd incubator-samoa
git remote -v
origin git@github.com:<user>/incubator-samoa.git (fetch)
origin git@github.com:<user>/incubator-samoa.git (push)
Setup the upstream remote
Now we need to setup a remote pointing to SAMOA's GitHub repository. This remote is useful for contributors to fetch the latest modifications before submitting a pull request, and for committers to fetch pull request to review and merge.
git remote add upstream git@github.com:apache/incubator-samoa.git
git fetch upstream
git branch -u upstream/master
git remote -v
origin git@github.com:<user>/incubator-samoa.git (fetch)
origin git@github.com:<user>/incubator-samoa.git (push))
upstream git@github.com:apache/incubator-samoa.git (fetch)
upstream git@github.com:apache/incubator-samoa.git (push)
For committers
Setup the apache remote
As a committer, you have write access to the official Apache git repository. You need to setup a remote pointing to it in order to commit changes.
git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-samoa.git
git fetch apache
git remote -v
apache https://git-wip-us.apache.org/repos/asf/incubator-samoa.git (fetch)
apache https://git-wip-us.apache.org/repos/asf/incubator-samoa.git (push)
origin git@github.com:<user>/incubator-samoa.git (fetch)
origin git@github.com:<user>/incubator-samoa.git (push))
upstream git@github.com:apache/incubator-samoa.git (fetch)
upstream git@github.com:apache/incubator-samoa.git (push)
Fetch pull requests automatically
The easy way to check out a pull request is the following.
git fetch upstream pull/ID/head:SAMOA-XX
git checkout SAMOA-XX
If you review many pull requests, you can setup your git clone to automatically fetch the pull requests from the upstream remote.
The order in which you add the refs is important (pull goes before heads).
git config --unset remote.upstream.fetch
git config --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pull/*'
git config --add remote.upstream.fetch '+refs/heads/*:refs/remotes/upstream/*'
git fetch upstream
remote: Counting objects: 554, done.
remote: Compressing objects: 100% (58/58), done.
remote: Total 554 (delta 67), reused 40 (delta 40), pack-reused 456
Receiving objects: 100% (554/554), 101.94 KiB | 0 bytes/s, done.
Resolving deltas: 100% (170/170), done.
From github.com:apache/incubator-samoa
* [new ref] refs/pull/1/head -> upstream/pull/1
* [new ref] refs/pull/2/head -> upstream/pull/2
* [new ref] refs/pull/3/head -> upstream/pull/3
* [new ref] refs/pull/4/head -> upstream/pull/4
* [new ref] refs/pull/5/head -> upstream/pull/5
* [new ref] refs/pull/6/head -> upstream/pull/6
* [new ref] refs/pull/7/head -> upstream/pull/7
* [new ref] refs/pull/8/head -> upstream/pull/8
* [new ref] refs/pull/9/head -> upstream/pull/9
You can now check out a pull request simply as follows.
git checkout -b SAMOA-XX upstream/pull/ID
The new local branch will automatically track the pull request.
Source: https://gist.github.com/piscisaureus/3342247 (note that in SAMOA's case pull requests come to the upstream remote rather than the origin one).
Get ready to update the website
Checkout the gh-pages branch that contains website and documentation.
git checkout -b gh-pages upstream/gh-pages
In a separate directory, check out the currently-published website from SVN.
cd ..
svn checkout https://svn.apache.org/repos/asf/incubator/samoa/site samoa-website