Part 3: Development

Assuming you correctly set up your repositories (remote and local), you are now ready to try some development!

As mentioned earlier, this workshop repository contains a small open source python project called Caduceus. In the README, you will find some information about installing and using Caduceus. In general, most open source projects will have a README containing at least this much information. Many projects will also have docs detailing how to contribute, and what the developer workflow for the project is. Always read the docs before you start development! If you are brand new to python and need some more information before diving into development, you can checkout the curriculum at this Python Workshop for Beginners.

For this workshop, I've created a few issues to try your hand at. If you navigate to the issues tab above, you will see I have created five issues and labelled them based on python skill level. In this case "beginner" means that you have hardly used python before at all. Pick any of the six issues you think would be doable and follow the steps below:

Updating your Repository

Any time you start working on a new feature for a public git repository, you want to make sure that your local and remote forks of the repo are up to date with the public one. That way you are all synced up when you start making the changes. To do this, use the following commands (note that the "# Note ..." parts denote comments and are not part of the commands you'll run):

git checkout master         # Check out your master branch
git fetch upstream          # Fetch any new upstream code
git rebase upstream/master  # Rebase your master branch to match upstream
git push origin master      # Update your remote `origin` repository

Making a New Branch

Like I mentioned in the Intro to Git page, it's good practice to make a new branch before starting on a new feature. To do this just run the following command:

git checkout -b "name-of-feature"

This will create a new branch called "name-of-feature" and will switch to using that branch as where you're working right now. In this case, you can put something like "issue-1" based on the number of the issue you are working on.

Note that the single command above is shorthand for the following two commands:

git branch "name-of-feature"
git checkout "name-of-feature"

You may use either.

Making Changes

A great thing about working on an open source git repository, is that you have access to all the code written by anyone else in that repo. This is super helpful for when you need to learn about the conventions used in that repository during feature development.

Poke around all the file in the repository to get a feel for how they all interact with each other. When you make your changes try to follow any patterns you see. For example, in Caduceus, we capitalize every word in a class name, so any classes you create should follow this convention.

Once you have reviewed our naming and programming conventions, you can go ahead and make whatever changes the issue you chose requires!

Open up the files in your chosen text editors and get to work. Once you've made your changes, reinstall Caduceus with pip and use the example.py script to test if your changes work!

Adding and Committing your Changes

Once you are happy with your files, you can add and commit your changes to the repository. First, tell git to track the files:

git add filename1 filename2 #...

Always add specific files. Doing things like git add * or git add --all may accidentally include some messy files you don't want.

Now we'll commit the new file:

git commit -m "A commit message"

There are some conventions we follow for commit messages. Here is some great advice from Elana Hashman about it:

• Use present-tense, imperative commit messages.
  • DON'T write "This fixes issue #234 by optimizing the algorithm"
  • DO write "Optimizes algorithm; fixes #234"
• Write descriptive commit messages that give the reviewer the big picture
  • DON'T write "Updates in css files"; this is redundant and can be determined by viewing the files the patch modifies
  • DO feel free to write multi-line commit messages; keep in mind that while only the first line is visible in summary view, additional comments below go into the git log and can be very useful
• Ask for help if you're not sure how to do some of these things!

Now update your fork's remote repo with the changes you just committed:

git push origin HEAD    # HEAD is shorthand for the most recent commit on the current branch

Once you've completed all these steps, you're ready to submit a pull request, per Part 4: Pull Requests.