gitgoing

Get going with contributing to open-source software

Free software: BSD license
Documentation: https://gitgoing.readthedocs.org.

Setting up your environment

Make a github account
Install git on your computer

Mac
1. Create a folder ~/code by typing into the terminal mkdir ~/code
- (feel free to use your own code folder if you already have one that you like)
1. OPTIONAL: Use homebrew http://brew.sh (it's a great package manager for installing command line apps!)
- Install by pasting this into your terminal: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- If you don't have git installed, type brew install git to install it!
Windows
1. Install gitextensions here: http://sourceforge.net/projects/gitextensions/
2. Create a folder C:\code by typing into powershell mkdir C:\code
- (feel free to use your own code folder if you already have one that you like)

Install Anaconda Python distribution found here: http://continuum.io/downloads

Make sure to use the Python 2.7 version. You can verify that your computer has Python 2.7 by typing python --version into your terminal.

Fork this repo by clicking the Fork button in the top right corner on the github page for this repo: https://github.com/CodeNeuro/gitgoing
Clone the fork that you just made by clicking the url to clone on the right side of the github page of your fork. Then browse in your terminal to your code folder cd ~/code and then type in the clone command: git clone {url_of_your_fork}
Move into the folder via cd gitgoing, then make sure the clone worked by typing git status, and you should see:

On branch master
Your branch is up-to-date with 'origin/master'.

Let's learn Git

Make a change (aka edit) to a file in your cloned repo and save the change locally. Try making a change to this README.md file by adding content to the bottom of it.
Type git status in the terminal to see what's up. Type git diff to get a detailed list of differences. Use j and k to navigate up and down the diff, and q to end the diff.
Type git commit -am "{message for the commit}" to create a new commit
Type git status to see what's up.
Type git push to push your changes up to the github server.
If you made a change to the README.md file, you should see it changed on your fork's github page.
Type git branch to list out the current local branches
Type git checkout -b {branch_name} to create a new branch
Make a commit onto the branch, and push the changes up to github. Note: You will need to use the branch name in the push, e.g. if my branch is called smallchange, I would push via git push origin smallchange
You should see your new branch up on your fork's github page.

Let's make a real contribution

You can run the test suite by typing py.test (pronounced "pie test") in the repo's root directory. This is a python package that will execute the tests and print out the results.
Open up the test file gitgoing/tests/test_gitgoing.py in your favorite editor
Comment out the test named test_cv_broken by removing the # characters at the beginning of each line of the test in the test_gitgoing.py file.
Run the tests again and watch it fail. You should see this kind of message:

============================================================================= test session starts ==============================================================================
platform darwin -- Python 2.7.9 -- py-1.4.25 -- pytest-2.6.3
plugins: cov
collected 8 items 

tests/test_gitgoing.py ..F....X

=================================================================================== FAILURES ===================================================================================
___________________________________________________________________________________ test_cv ____________________________________________________________________________________

x_norm = array([[ -3.78944360e-01,   1.02198073e+00,  -1.18127826e+00,
         -2.7882...2.19688063e+00,   1.71670354e-01,  -1.37347439e+00,
          5.33478606e-01]])

    def test_cv(x_norm):
        from gitgoing.gitgoing import std, mean, cv
    
        test_cv = cv(x_norm)
        true_cv = std(x_norm)/mean(x_norm)
    
        # This test will fail
>       assert test_cv == true_cv
E       assert 0.51026948757496537 == 1.9597487687387671

tests/test_gitgoing.py:47: AssertionError
================================================================ 1 failed, 6 passed, 1 xpassed in 0.23 seconds =================================================================

Use your new knowledge of git to fix the test!
Create a branch git checkout -b myfixbringsalltheboystotheyard
Fix the test by editing files, using Sublime text
Add and commit the changes git commit -am "fixed test_cv_broken"
Push to your new branch git push origin myfixbringsalltheboystotheyard
Run the tests again and watch it succeed.
Create a pull request back to the original repo that you forked by going to your gitgoing repo website (github.com/yourgithubusername/gitgoing), and pressing the green "compare" button next to the branches, which looks like this:
And that's how you contribute to open source software!

Build the documentation

A key part of any open source project is documenting it! The sphinx library makes it really easy to add documentation to a project, which you can then host for free on github pages.

We're currently doing that for this repository, you can see the documentation page here

To see where the documentation comes from, you can build it yourself locally. If you've cloned this repository, just navigate to the docs folder, and then enter

sphinx-build -a . build

This creates a set of .html files in the folder build. If you go into that folder and double-click index.html, it should open in a web browser, and you'll see something that looks just like the webpage mentioned above.

Sphinx takes a little bit of configuration, but can automatically generate a page directly from your Python package, including the documentation you provide for your classes and methods. And you can regenerate the documentation whenever you change the code. This makes it easy to automatically document your project and keep the documentation up to date.

Additional useful links

http://www.sbf5.com/~cduan/technical/git/

oeolartep / gitgoing