-
Notifications
You must be signed in to change notification settings - Fork 14
system test development workflow
This wiki describe a git and github workflow for the ioos/system-test project.
If you never used git before consider trying
this.
If you are familiar with git
jump to Step 1. If you
already know how to fork go straight to Step 2.
If you don't have a github account, go to the github page, and make one.
You then need to configure your account to allow write access, see the Generating SSH keys help.
You can use https
, but I strongly recommend SSH keys
instead.
Also, consider enabling the Two-Factor Authentication
(2FA).
Your personal git configurations are saved in the .gitconfig
file in
your home directory.
Here is my .gitconfig
file as an example:
[user]
name = ocefpaf
email = ocefpaf@gmail.com
[push]
default = simple
[alias]
pull = pull --ff-only
st = status -s
ci = commit
co = checkout
diff = diff --word-diff
ll = log --pretty=format:"%C(yellow)%h%Cred%d\\ %Creset%s%Cblue\\ [%cn]" --decorate --numstat
ls = log --pretty=format:"%C(yellow)%h\\ %ad%Cred%d\\ %Creset%s%Cblue\\ [%cn]" --decorate --date=relative
filelog = log -u
You can edit this file directly or you can use the git config --global
command::
git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com
Note 1: To set up on another computer, you can copy your ~/.gitconfig
file.
I keep my config in a Dropbox folder.
Note 2: Try my aliases out. You may find git ls
and git ll
helpful.
Your fork will be where you'll work, not the main repository!
- Log into your github account.
- Go to the
system-test
github home at ioos github - Click on the fork button:
You should find yourself at the home page for your own forked copy of system-test. Now you can clone your fork.
git clone git@github.com:your-user-name/system-test.git
Change directory to your new repo: cd system-test
. Then test it by typing
git branch -a
to show you all branches and git remote -v
to show the URLs.
You will notice that this fork has no connection to the main system-test repo.
You need to add system-test
main repository as your upstream
.
git remote add upstream https://github.com/ioos/system-test.git
You need to do all this only once! Repeat the commands git branch -a
and
git branch -v
and check if you have your origin pointing to your repo and
upstream pointing to system-test main repo.
You should see something like this:
origin git@github.com:ocefpaf/system-test.git (fetch)
origin git@github.com:ocefpaf/system-test.git (push)
upstream https://github.com/ioos/system-test.git (fetch)
upstream https://github.com/ioos/system-test.git (push)
We added the upstream using git://
for the URL rather than git@
. The
git://
URL is read only. This means that we can't accidentally
(or deliberately) write to the upstream repo, and we are only going to
use it to merge into our own code and send PRs.
Note 1: upstream
is a recommended name, but you may call it whatever you
want, as long as you remember that it points to system-test main repo!
Note 2: Even the administrators should fork from the main repository and
never clone them using the git@
!
Please see http://help.github.com/forking/ for more detail.
You already have your own forked copy of the system-test
repository and you
have configured git. Now you are ready for some real work.
Don't use your master
branch for anything.
- Before you start a new notebook or modify an existing one, fetch any changes
from
upstream
withgit fetch upstream
. Then merge into youmaster
withgit merge upstream/master
. You can thengit push
to your fork to keep your fork updated. - Start a new feature branch with:
git branch branch_name
and change to the branch withgit co branch_name
. (You should Consider using a prompt that is git aware). Always make a new branch for each separable set of changes "one task, one branch", similar to the ipython git workflow. Name your branch for the purpose of the changes - e.g.bugfix-for-issue-42
ornew_cool_feature_X
. Check my remove_pylab PR. - Keep working normally, committing code, and pushing to your branch. Git is
smart enough to tell you that, during the first
push
, there is nothing pointing to your branch, just follow git instructions. It should be something like:git push --set-upstream origin branch_name
, then keep pushing. - When you are ready, go to the URL of your forked repo
http://github.com/your-user-name/system-test
. Use the 'Switch Branches' dropdown menu near the top left of the page to select the branch with your changes: Click on the 'Pull request' button: - Ask for people to review and merge your modifications. We can elect a maintainer to be the "merging" guy, but all should help for the review. Try to call the reviewers by interest, tagging their username in the PR (like @ocefpaf check my code!!! 😄).
This way of working helps to keep work well organized, with readable history. This in turn makes it easier for project maintainers (that might be you) to see what you've done, and why you did it.
Always repeat step 1 before starting a new branch. This will pull down any commits you don't have.
Feel free to ask me for help and clarifications.
For more details read the iris Development workflow.
This wiki was a rip-off of the Iris Development Guide