Git workflow

GNU MediaGoblin uses git for all our version control and we have the repositories hosted on Savannah. We have two repositories:

• MediaGoblin software: http://git.savannah.gnu.org/cgit/mediagoblin.git
• MediaGoblin website: FIXME! Pending add URL

It's most likely you want to look at the software repository -- not the website one.

The rest of this chapter talks about using the software repository.

The short of it is: we do not use merge requests. Instead, create a "feature branch" in git that you push somewhere, and link to it on a ticket. Details below.

How to clone the project

Do::

   git clone git://git.savannah.gnu.org/mediagoblin.git

How to contribute changes

Tie your changes to issues in the issue tracker

All patches should be tied to issues in the issue tracker. That makes it a lot easier for everyone to track proposed changes and make sure your hard work doesn't get dropped on the floor! If there isn't an issue for what you're working on, please create one. The better the description of what it is you're trying to fix/implement, the better everyone else is able to understand why you're doing what you're doing.

Use bugfix branches to make changes

The best way to isolate your changes is to create a branch based off of the MediaGoblin repository master branch, do the changes related to that one issue there, and then let us know how to get it.

It's much easier on us if you isolate your changes to a branch focused on the issue. Then we don't have to sift through things.

It's much easier on you if you isolate your changes to a branch focused on the issue. Then when we merge your changes in, you just have to do a git fetch and that's it. This is especially true if we reject some of your changes, but accept others or otherwise tweak your changes.

Further, if you isolate your changes to a branch, then you can work on multiple issues at the same time and they don't conflict with one another.

Name your branches using the isue number and something that makes it clear what it's about. For example, if you were working on tagging, you might name your branch "360_tagging".

Properly document your changes

Include comments in the code.

Write comprehensive commit messages. The better your commit message is at describing what you did and why, the easier it is for us to quickly accept your patch.

Write comprehensive comments in the issue tracker about what you're doing and why.

How to send us your changes

There are two ways to let us know how to get it:

push changes to publicly available git clone and let us know where to find it

This is the preferred method of sending changes.

Push your feature/bugfix/issue branch to your publicly available git clone and add a comment to the issue with the url for your clone and the branch to look at.

attaching the patch files to the issue

Run

git format-patch --stdout <remote>/master > issue_<number>.patch

format-patch creates a patch of all the commits that are in your branch that aren't in <remote>/master. The --stdout flag causes all this output to go to stdout where it's redirected to a file named issue_<number>.patch. That file should be based on the issue you're working with. For example, issue_42.patch is a good filename and issue_42_rev2.patch is good if you did a revision of it.

Having said all that, the filename isn't wildly important.

Example workflow

Here's an example workflow.

Contributing changes

Slartibartfast from the planet Magrathea far off in the universe has decided that he is bored with fjords and wants to fix issue 42 (the meaning of life bug) and send us the changes.

Slartibartfast has cloned the MediaGoblin repository and his clone lives on repo.or.cz.

Slartibartfast works locally. The remote named ``origin`` points to his clone on repo.or.cz. The remote named ``gmg`` points to the MediaGoblin repository.

Slartibartfast does the following:

1. Fetches the latest from the MediaGoblin repository::

git fetch --all -p

This tells git fetch to fetch all the recent data from all of the remotes (--all) and prune any branches that have been deleted in the remotes (-p).

2. Creates a branch from the tip of the MediaGoblin repository (the remote is named gmg) master branch called bug42_meaning_of_life:

git checkout -b bug42_meaning_of_life gmg/master

This creates a new branch (-b) named bug42_meaning_of_life based on the tip of the master branch of the remote named gmg and checks it out.

3. Slartibartfast works hard on his changes in the bug42_meaning_of_life branch. When done, he wants to notify us that he has made changes he wants us to see.

4. Slartibartfast pushes his changes to his clone:

git push origin bug42_meaning_of_life --set-upstream

This pushes the changes in the bug42_meaning_of_life branch to the remote named origin.

5. Slartibartfast adds a comment to issue 42 with the url for his repository and the name of the branch he put the code in. He also explains what he did and why it addresses the issue.

Updating a contribution

Slartibartfast brushes his hands off with the sense of accomplishment that comes with the knowledge of a job well done. He stands, wanders over to get a cup of water, then realizes that he forgot to run the unit tests!

He runs the unit tests and discovers there's a bug in the code!

Then he does this:

1. He checks out the bug42_meaning_of_life branch::

git checkout bug42_meaning_of_life

2. He fixes the bug and checks it into the bug42_meaning_of_life branch.

3. He pushes his changes to his clone (the remote is named origin):

git push origin bug42_meaning_of_life

4. He adds another comment to issue 42 explaining about the mistake and how he fixed it and that he's pushed the new change to the bug42_meaning_of_life branch of his publicly available clone.

What happens next

Slartibartfast is once again happy with his work. He finds issue 42 in the issue tracker and adds a comment saying he submitted a merge request with his changes and explains what they are.

"merge request"? http://git.savannah.gnu.org/cgit/mediagoblin says "We don't use no stinking merge requests"

Later, someone checks out his code and finds a problem with it. He adds a comment to the issue tracker specifying the problem and asks Slartibartfast to fix it. Slartibartfst goes through the above steps again, fixes the issue, pushes it to his bug42_meaning_of_life branch and adds another comment to the issue tracker about how he fixed it.

Later, someone checks out his code and is happy with it. Someone pulls it into the master branch of the MediaGoblin repository and adds another comment to the issue and probably closes the issue out.

Slartibartfast is notified of this. Slartibartfast does a:

git fetch --all

The changes show up in the master branch of the gmg remote. Slartibartfast now deletes his bug42_meaning_of_life branch because he doesn't need it anymore.

How to learn git

BeginnersCorner#Learning_git