...
- Make sure you have git setup and have a github account and have your name and email properly set as git global variables on your workstation.
- Fork the central Sakai repository to your own github account
- We will use the following references
- local = local git clone on your workstation, this where everyone typically does their work
- origin = this is your local fork of the sakai project on github, you clone this repo on your local workstation
- upstream = this is main sakai project github project everyone forks this project into their github account
- We will use the following references
- Clone your fork onto your computer
- Sync sakai master with your local forks master to receive updates
Never work on your local master, generally this branch should always be the same as what is in sakai's master and if you make commits here this complicates things. If you mistakenly commit work to your local master, it's easy to fix
master> git branch SAK-XYZ # make a copy of what we've done so far in a branch
master> git reset --hard upstream/master # match current branch to upstream
master> git checkout SAK-XYZ # resume work on feature branch
- Sync sakai master with your forks master
master> git remote add upstreamhttps://github.com/sakaiproject/sakai
(you will do this only once)master> git pull upstream master
(you will update your local fork frequently)master> git push origin master
(after you update your local fork don't forget to push to your github fork)
- Use your own copy of git to make your changes and test, etc. You can commit and push as to your own repo as much as you like.
- Make sure you always work on a local branch, We recommend using the name of the JIRA as the branch name.
master> git checkout -b SAK-12345
SAK-12345>
(make your changes then commit them, if you make multiple commits its best to squash them into one logical commit)SAK-12345> git push origin SAK-12345
(this creates a new branch called SAK-12345 in your fork on github that contains everything in your local branch SAK-12345, notice they have the same name this is important)
- Make sure you always work on a local branch, We recommend using the name of the JIRA as the branch name.
- When you are ready to "commit to trunk" create a pull request from your repo against the sakai master branch in the sakaiproject repository.
- If the changes are code you would have committed to the old SVN trunk (i.e. just normal development) - merge your own pull request in to Sakai's master branch.
- If the changes you are making are worthy of further review or touching an area of Sakai that you do not generally work in - have someone else review and merge your pull request.
- If after review changes need to be made all you need to do is make the changes and commit in the SAME branch you issued the pull request (PR) from and then push those changes to your fork and it will automatically update the PR that was made to sakai's master.
- Use the rebase interactive mode to find all commits you've made since you branched off your master
SAK-12345> git rebase -i master
pick b76d157 commit2 pick a931ac7 commit1 # Rebase df23917..a931ac7 onto df23917 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. #
- Squash commit1 into commit2 by changing the prefix on the appropriate line:
pick b76d157 commit2 s a931ac7 commit1
Change the commit messages if necessary in the following editor screen
Push the changes back to the branch in your repo
SAK-12345> git push --force origin SAK-12345
Now your changes are all squashed into one commit, your repo branch is updated with your local code, and your PR is automatically updated without closing it and opening a new one!
- Use the rebase interactive mode to find all commits you've made since you branched off your master
...
- On your local clone, checkout the master branch and ensure it is up to date with upstream
master> git checkout master
master> git pull upstream master && git push origin master
- Depending on some settings on your local system, you may also have to fetch upstream to get a reference to the upstream 11.x branch (or any other upstream branches you don't have a reference to locally)
master> git fetch upstream
remote: Counting objects: 24, done.
remote: Compressing objects: 100% (22/22), done.
remote: Total 24 (delta 0), reused 24 (delta 0), pack-reused 0
Unpacking objects: 100% (24/24), done.
From github.com:sakaiproject/sakai
* [new branch] 11.x -> upstream/11.x - Then, you checkout (create) the branch locally and set it up to push to origin, so you can stay in sync with the 11.x branch like you do with master
master> git checkout 11.x
Branch 11.x set up to track remote branch 11.x from upstream.
Switched to a new branch '11.x'master> git push -u origin 11.x
Counting objects: 1, done.
Writing objects: 100% (1/1), 290 bytes | 0 bytes/s, done.
Total 1 (delta 0), reused 0 (delta 0)
To git@github.com:<yourGitHubAccount>/sakai.git
* [new branch] 11.x -> 11.x
Branch 11.x set up to track remote branch 11.x from origin. - To update the 11.x branch from upstream, perform the following (like you would with master, just replacing the master branch name with the 11.x branch name, or any other branch name from upstream)
master> git checkout 11.x
master> git pull upstream 11.x && git push origin 11.x
- To create a local branch for development against only 11.x, you create a new branch as you would normally, but instead of being based on master (which is default), you want to base it on the 11.x branch:
master> git checkout -b SAK-12345 11.x
- Once you have a local feature branch based on 11.x and you've done some development and committed your work, you'll want to push it to your origin so you can issue a Pull Request against the upstream 11.x branch
master> git push -u origin SAK-12345
- Your 11.x specific feature is now ready for you to issue the Pull Request!
Reviewing Pull Requests
If you are reviewing someone else's pull request and would like to check out a copy of the Sakai repo that includes the pull request, use the following command:
...