Setting up for Contributions via GITHUB

Introduction

GIT is a source code management system (SCM) and GITHUB is a web-based tool for managing and sharing GIT repositories. SCM's are typically used for managing software projects but, due to the text-based nature of Lilypond, they work very nicely for this project. GITHUB help pages offer a substantial orientation to help you get started. This document is about a specific workflow for the Mutopia Project.

The process of updating using GIT/GITHUB is fairly straightforward. Since you cannot write directly into The Mutopia Project repository, you fork your own copy, and then use GIT on your local machine to clone (reproduce) that repository on your home computer. The cloning process will recreate the entire directory hierarchy of the project. You then make edits locally, check them in, and when you are done you push them to your forked GITHUB repository. Once this is done you make a request to The-Mutopia-Project to pull your changes into the project's master repository.

Prerequisites

1. A GITHUB account. This provides you with some storage and the ability to access our repository.
2. A home machine with GIT installed.
3. Some amount of working space. Mutopia is growing but currently it is less than 100MB.

Setting Up

Fork the repository

See this GITHUB article as a reference to create a fork of the Mutopia Project repository.

Create your local repository

The git clone command is used to create a local copy of your fork. The following command creates a clone in a folder called mp.

$ git clone git@github.com:<your-user-name>/MutopiaProject.git mp
$ cd mp

The clone process may take some time depending on the speed of your internet connection. Note that your repository URL is available from your fork page on GITHUB.

You now have a local copy but you still have some further setup to do. Use the help files on GITHUB as a guide. For the following steps, your current working directory must be somewhere under cloned repository folder. The following commands define an identity that will be used when committing your contributions and will appear in the log files.

$ git config --global user.name "John Doe"
$ git config --global user.email "johndoe@whatever.com"

or whatever obfuscation you desire. For example,

$ git config --global user.email "johndoe at whatever dot com"

When you created your clone, it automatically created a remote called origin that will be used later when you need to push your changes to GITHUB. To fetch changes in the MutopiaProject master repository, you need to create an upstream remote:

$ git remote add upstream git@github.com:MutopiaProject/MutopiaProject.git
$ git remote -v # list your remotes
origin	git@github.com:<your-user-name>/MutopiaProject.git (fetch)
origin	git@github.com:<your-user-name>/MutopiaProject.git (push)
upstream	git@github.com:MutopiaProject/MutopiaProject.git (fetch)

The Workflow

Each time you work on a score or a set of scores, you should follow this workflow:

The first step (A) is to synchronize your repository's master with the the MutopiaProject master. A topic branch is then created (B) so your work can take place separately from the master branch. While working in a branch you make whatever file changes you need to make (C), committing all your changes when done. You then (D) push your branch to your fork on GITHUB and submit a pull request. The last step is for the MutopiaProject admin team to process the pull request (E).

Synchronize with your local repository

Make sure you are in your master branch (not one of your topic branches), and fetch any upstream changes:

$ git checkout master
$ git fetch upstream
$ git merge upstream/master

Create a topic branch for your work

$ git checkout master
$ git checkout -b update-1
$ git branch -v # list your branches

The first git checkout command simply switches to the master, the second does double duty by creating the branch and switching to it.

Once you are in a branch, all of the work you do is visible only in that branch. If you decide against the changes, you can simply delete the branch. If the work gets complicated or something else comes up you can create another branch off the master and work on that without affecting the update-1 branch. Once you have completed your work, you commit your file into the branch of your repository:

$ git add whatever.ly
$ git commit

You will be prompted to enter a message to describe your changes. You may find it easier to supply the message when you make the commit, like this:

$ git add whatever.ly
$ git commit -m "This is the commit message"

Pushing

After committing, the update-1 branch in your repository now contains your changes. (If you discover you need to make more changes, just repeat the edit-test-commit loop.) To prepare for getting your changes into the MutopiaProject master, you must first get them into your forked repository. This is done using the git push command:

$ git branch -v             # list branches
$ git push origin update-1  # push branch

Notice that the push is to your origin, not the upstream repository (which you probably don't have push access to anyway.) The above push command copies all the changes you made in update-1 and recreates the branch and changes in your GITHUB repository.

Note for first-timers: It is important in this workflow not to merge the changes in your development branch into your repository's master.

Your last step is to go to your GITHUB account and issue the pull request to the MutopiaProject master, specifying your branch in the request.

All done. Thanks!

Cleaning up

Once your pull request has been reviewed and processed, your changes will be merged into The-Mutopia-Project master repository. The next time you synchronize your repository master with the project repository (the first step of our workflow), your processed changes will be pulled into your local repository.

Deleting your topic branch

Obviously destructive, it is recommended that you keep the branch around until the pull request has been processed.

The first step is to delete the local topic branch,

$ git branch -D update-1

Then to delete the branch on your GITHUB repository,

$ git push origin :update-1

Notes

If you were to create, edit, and push another file while you are in the branch you just pushed, a subsequent pull request will cause this edit to be merged with your previous pull request if it is still outstanding. Remember that branches are cheap and making a small set of changes in a new branch will prevent pulls from being merged.

The advantage to small sets of changes, pushed in branches, is that they can be reviewed and closed quicker. Also, the commit comments are appended to the log of changes in the View Change History link of the piece.