"Environments" are sandboxes where you can install python package of specific versions, and then they don't conflict with other versions. They're very helpful if you're testing your software package with different versions of programs like numpy or scipy but don't want to mess up your own installation.
- Create a gitgoing-specific
condaenvironment by typing at the Terminal (for Mac and Linux) or Anaconda Terminal (for Windows). We'll installpip(package to install python packages - yes it's very meta) andnumpy(matrices in python).
conda create --yes --name gitgoing pip numpy pytest
You should get output that looks like this:
Fetching package metadata: ....
Solving package specifications: ................
Package plan for installation in environment /Users/olga/anaconda/envs/gitgoing:
The following packages will be downloaded:
package | build
---------------------------|-----------------
pytest-2.8.1 | py27_0 219 KB
The following NEW packages will be INSTALLED:
numpy: 1.10.1-py27_0
openssl: 1.0.2d-0
pip: 7.1.2-py27_0
py: 1.4.30-py27_0
pytest: 2.8.1-py27_0
python: 2.7.10-2
readline: 6.2-2
setuptools: 18.4-py27_0
sqlite: 3.8.4.1-1
tk: 8.5.18-0
wheel: 0.26.0-py27_1
zlib: 1.2.8-0
Fetching packages ...
pytest-2.8.1-p 100% |################################################################################################################################| Time: 0:00:00 639.21 kB/s
Extracting packages ...
[ COMPLETE ]|###################################################################################################################################################| 100%
Linking packages ...
[ COMPLETE ]|###################################################################################################################################################| 100%
#
# To activate this environment, use:
# $ source activate gitgoing
#
# To deactivate this environment, use:
# $ source deactivate
#
- Let's activate the environment with the instructions above.
- Now that we have our environment setup, fork this repo by clicking the
Forkbutton 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 ~/codeand then type in the clone command:git clone https://github.com/yourgithubname/gitgoing - Move into the folder via
cd gitgoing, then make sure the clone worked by typinggit status, and you should see:
On branch master
Your branch is up-to-date with 'origin/master'.
First, we'll have a brief chalk-talk overview of what git is and how it works.
- 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 statusin the terminal to see what's up. Typegit diffto get a detailed list of differences. Usejandkto navigate up and down the diff, andqto end the diff. - Type
git commit -am "message for the commit"to create a new commit
- Look,
gitis teaching you life lessons like overcoming fear of commitment :)
- Type
git statusto see what's up. - Type
git pushto 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 branchto list out the current local branches - Type
git checkout -b newbranchto 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 viagit push origin smallchange
- BONUS: Make a merge conflict! Make another branch and edit the
README.mdfile. Now make another branch and edit theREADME.mdfile on the same line. Try to push both branches. You should get a merge conflict. This is good. See, git is teaching you yet another life lesson: dealing with conflict!
- You should see your new branch up on your fork's github page.
- 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
tests/test_gitgoing.pyin your favorite editor - Comment out the test named
test_cv_brokenby removing the # characters at the beginning of each line of the test in thetest_gitgoing.pyfile. - 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 =================================================================
- BONUS: Notice the
@pytest.fixture"decorator" on the functionx_norm(in Python, these things above functions are called decorators. If you're familiar with lambda calculus, they are closures). What does this do to the function?
- Use your new knowledge of
gitto 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
gitgoingrepo website (github.com/yourgithubusername/gitgoing), and pressing the green "compare" button next to the branches, which looks like this:
- BONUS: Look at your contribution and the rest of your class! On the
gitgoinggithub page, click where it says "(N) Contributors" which looks like this:. Then click "Network" which will show you the literal graph network of everyone that has ever forked this repo and pushed any changes to github. Pretty cool!
- And that's how you contribute to open source software!
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.
Awesome job! If you want to learn more about
- Python Packaging User Guide (crowdsourced, more authoratative)
- How to package your Python Code