GitHub Best Practices - skyscreamer/yoga GitHub Wiki

Here are some suggested practices for how to contribute to this project.

Make sure you have an account on github: https://help.github.com/articles/set-up-git

Go to the project home (http://github.com/skyscreamer/yoga) and click on the fork button to create your own fork.

% git clone [email protected]:<username>/yoga.git

It is a git best practice to develop each new feature or bug fix in a new branch, and we strongly recommend you do the same with descriptive branch names. It's trivial to create branches and switch between them. Using them will make it simple for you to pause one task list item and begin another. It also simplifies our process of tracking contributions to the main code base. Submitting pull requests for the same branch over and again can sometimes lead to unexpected results, so the basic process should be:

% cd yoga
% git checkout -b my_descriptive_branch_name

You'll immediately be in the new branch. Remember this isn't Subversion or CVS, so the branch checkout doesn't create a new directory, it changes the state of your working directory, adding/removing files as necessary to update the state.

If you are using an IDE, now is when you'll want to refresh (Eclipse) or Git->Synchronize (IntelliJ) to make sure your editor is in sync with the git repo on your filesystem.

Now, write some code!

Git requires files be staged before committing. You can add the files manually:

% git add <file>

Or add the -a tag when you commit.

When you commit, just do the following:

% git commit

This will commit your changes to your local copy of the repository (which is distinct from your fork on github).

If you know changes have been made to the primary code base, or if a pull request has been denied because you are out of sync with the primary code repository, you'll need to do a merge.

First create a "remote" to the primary (aka upstream) code repository. You only need to do this once ever. You're basically defining an alias that can be reused across checkouts:

% git remote add upstream git://github.com/skyscreamer/yoga.git

Retrieve and merge updates:

% git fetch upstream
% git merge upstream/master

% git push origin my_descriptive_branch_name

If you cloned from another source than your fork, you can create a remote to your fork, and push to that fork instead of origin.

Go to your fork on the web site (e.g. http://github.com/YOUR_USERNAME/yoga), and click on the "Pull Request" button on the top. Under the base branch you should see skyscreamer/yoga @ master and under the head branch username/yoga @ master. Replace "master" in the head branch with the name of your new branch (e.g. my_descriptive_branch_name). Press enter, and click the "Update Commit Range" at the bottom.

You should then be able to add a descriptive comment about what is in this merge, and submit the pull request. A project admin can then apply the merge to the primary code repository.

You can read more about pull requests here: http://help.github.com/pull-requests/

A helpful guide to previewing submitted pull requests is here: http://beust.com/weblog/2010/09/15/a-quick-guide-to-pull-requests/

For more reading, check out the excellent Pro Git book online, especially the Public Small Project section in chapter 5.2: http://progit.org/book/ch5-2.html. Also check out github's "Fork a Repo" help page: http://help.github.com/fork-a-repo/

mvn jetty:run-war