Hello & welcome to Part 3! This is where we’ll start to use the various things you’ve installed to work with the code.

Get the Code

We’re going to go over some real-world basics of how git works and how conda works. We’ll do this by getting you a copy of the code we’re going to work with on to your local machine, then installing the packages we need with conda.

Visit https://github.com/bmcfee/ismir2018-oss-tutorial, and press the Fork button. You’ll be asked where to fork the code to – select your own GitHub username. A “fork” is your own copy of our code. You can change it without altering our code.

Now, visit https://github.com/<your-username>/ismir2018-oss-tutorial, and press the Clone button. Make sure to select Clone with SSH, and then copy the string that looks like git@github:<your-username>/ismir2018-oss-tutorial.git

Then, in your terminal, go to wherever you keep your code, and do git clone <that string>. This will copy the code to your machine! Once it is done, you should see a directory called ismir2018-oss-tutorial.

cd into that directory, then do ls. You should see the same files that you see on GitHub!

Checkpoint

From the ismir2018-oss-tutorial directory, run:

git status

You should see:

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

Install Things with Conda

Conda, like we said earlier, is both a package manager and an environment manager. A package manager just installs things for you. An environment manager is a bit more complex – it keeps track of different independent environments, each of which can have different things installed. So, for example, you can have one environment for this project and install the things that you need … and then have a different environment for a different project, with different packages installed

This may sound like overkill, but it is very helpful in the long run. You’ll often find that different projects have clashing requirements, and maintaining one environment per project will prevent this from getting out of hand.

So, let’s make one and install the code that we need! To create an environment for this tutorial, do conda create --name ismir-2018. You’ll see that environment has been created at /Users/<your-user>/anaconda3/envs/ismir-2018 (or some path very much like that). Hooray! To turn it on do conda activate ismir-2018.

This means that any Python code you install with conda or pip will only be installed in this environment. If you want to get out of this environment, just run conda deactivate – but don’t run it now!

For now, we’re going to install all the stuff we need. Run conda install --file requirements.txt. This will install all the packages listed in requirements.txt.

Gotchas:

  • If you see an big error message that starts with CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'., don’t worry! The error message contains a few potential commands to fix things – running the echo ". ~/anaconda/etc/profile.d/conda.sh" >> ~/.bash_profile command and then opening a new terminal window should solve the problem. (And if you’re on zsh or fish, you’ll have to put that command in the appropriate place.)

Checkpoint

Run:

conda list

You should see something like the below:

packages in environment at /Users/thorkell/miniconda3:

 Name                    Version                   Build
conda                     4.5.10                   py36_0
conda-env                 2.6.0                h36134e3_0
cryptography              2.2.2            py36h1de35cc_0
cycler                    0.10.0           py36hfc81398_0
docutils                  0.14             py36hbfde631_0
flake8                    3.5.0                    py36_1
freetype                  2.9.1                hb4e5f40_0

Secret Bonus Checkpoint!

Bowser Bonus

Just when you thought you had done all the checkpoints!

We want to stop here quickly and make sure of everything, so we wrote a little test script that makes sure that everything is installed. In the scripts folder, you’ll find a file called test_tutorial_install.py.

Run:

python scripts/test_tutorial_install.py

You should see something very much like:

git version 2.15.0
Python 3.7.0
Conda installed and set in environment.
Success!  Everything has installed correctly. 😊😊😊

Run the Tests

So we’ve installed all the packages we’ll need. Let’s run the tests. Tests make sure that your code is doing what your think it is doing – making sure that 2 + 2 in fact comes out to 4.

You can find the test code in the toymir/tests/ folder, and we’ll talk more about testing later in the tutorial. For now, just run the tests with pytest -v.

💥🔥💥🔥💥🔥💥🔥💥🔥💥 OH NO EVERYTHING FAILED! 💥🔥💥🔥💥🔥💥🔥💥🔥💥

Phew, ok, this is not actually a big deal at all. Failing tests are usually a good sign, becaue they mean that your tests found a bug or a problem. Let’s look at the error message that pytest is showing, and see if we can fix it.

Ah, this does not look so bad. We’re missing a package called seaborn. We could just install it with conda, but we want to fix this problem for the long term. So, open up that requirements.txt file, and add the line seaborn at the bottom, and the save it. Then re-run conda install --file requirements.txt, and then run the tests again.

Gotchas:

  • If you get odd test results, or if running Python code shows odd behaviour, make sure that everything is installed in the ismir-2018 conda environment! Try doing which pytest, for example, and making sure that it is running out of your environment’s directory. (Something like /Users/<your-user>/anaconda3/envs/ismir-2018)

Checkpoint

Run:

pytest

You should see something like:

platform darwin -- Python 3.6.5, pytest-3.7.2, py-1.5.4, pluggy-0.7.1
rootdir: /Users/thorkell/Code/bmcfee/ismir2018-oss-tutorial, inifile:
collected 5 items

tests/test_toymir.py .....          	                        [100%]

Save Our Work

We fixed a bug, hooray! But we’ve only fixed our local version. Let’s commit this to our local git repository, and then update our code on GitHub.

First, make a new branch to work on. Working in a branch means that we can do whatever we want without breaking our main code. Do git checkout -b update-conda-env.

Next, add and commit your files: git add requirements.txt, then git commit -m "Add seaborn to requirements.txt"

Rad! We’ve saved our work locally. To push your code to GitHub, do git push origin update-conda-env.

(You can think of all this git and GitHub magic like you are mailing something to a friend. git checkout -b creates the letter you’re going to mail. git add selects what you’re going to put into your letter. git commit puts the changes into your letter, and then git push sends your paper to the post office.)

We want to get in the habit of keeping our online work up to date with our local work. So let’s go look at GitHub, and merge this branch there.

  • Visit GitHub, and find your fork of this repository: https://github.com//ismir2018-oss-tutorial/branches
  • You’ll see a list of branches - select update-conda-env.
  • You’ll see a small button that says New pull request. Press it!
  • You’ll get taken to a page that says Comparing changes, and should see a dropdown that says Base fork: bmcfee/ismir2018-oss-tutorial, like the below image.
  • You need to change this!

Incorrect merge

  • You need to select this dropdown and change it to point to your fork, with your username. Once you’ve done this, it should look like the below image:

Correct merge

  • After this, you’ll be taken to a nice web form. Put in the reasons for your changes, and press Create Pull Request.

Hooray, you’ve made a Pull Request! Pull Requests (PRs) are the best way to contribute code to a project. You can review & comment on the proposed changes before merging them, or request that things be improved. To finish the mail metaphor, a Pull Request is like adding some notes to your letter about what it is supposed to do and why you are sending it.

🙏🙏 🙏 Here’s an important aside: when discussing code in PRs, please be nice! It’s really easy for a neutral comment to be read as mean, and it’s really easy to alienate people by being mean.

You should do your best to very polite and kind when dealing with people on GitHub (and probably on computers in general). 🙏 🙏 🙏

With that said, let’s merge our PR! This will add the changes from your branch to the master branch.

  • Press Merge. GitHub will merge your commit into master.
  • Now your online repo is up to date, so let’s update your local.
  • In your command line, run git checkout master.
  • Next, do git pull origin master to update your local copy. You’ll see that git adds your commit from GitHub to your local copy.
  • Finally, do git branch -d update-conda-env to delete your local branch – you’ve merged the commits to master, so you can delete it.

Checkpoint

Run:

git log

You should see something like this:

commit fc48577568d259f361a2e5f28267500ff2d4405f
Author: <Your Name> <your-email@your-server>
Date:   <today>

Merge pull request #1 from <your-username>/update-conda-env

Add seaborn to requirements.txt

We’ve just gone over the basic git and GitHub workflow that you should, in general, stick with: make a branch, make some changes, run tests, commit, push, merge, clean up.

This means that you never have untested code in master, and it means that master is always functional. It also means that the online, “deployed” version of master is your primary version, and that you (and maybe many other collaborators) just have a local version that you’re working on.

We’ll come back to why this method is useful when we talk about tests. If you like, you can read more about this way of working with code on GitHub.

Success!

We’ve used git to check out code, modify it, and commit our modifications. We’ve also used conda to install the code we need, in an environment that is specific to this project. In Part 4, we’ll get into the details of our Python code and how it all fits together.