From 909c639d07aee08e2a3cd039e6fe4ae397dce5a7 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 12 Jun 2011 22:42:10 -0400 Subject: Fixes git workflow * overhauls the docs so they're (hopefully) clearer on the git workflow * adds text about putting things in bugfix branches, documenting your work, and using the issue tracker * adds a contrived example that uses aliens --- docs/git.rst | 184 +++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 154 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/git.rst b/docs/git.rst index 0db1dacf..ddbcf226 100644 --- a/docs/git.rst +++ b/docs/git.rst @@ -2,11 +2,17 @@ Git, Cloning and Patches ========================== -GNU MediaGoblin uses git for all our version control and we have -the repositories hosted on `Gitorious `_. +GNU MediaGoblin uses git for all our version control and we have the +repositories hosted on `Gitorious `_. We have +two repositories: -We have two repositories. One is for the project and the other is for -the project website. +* MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin +* MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website + +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. How to clone the project @@ -20,46 +26,164 @@ Do:: How to send in patches ====================== +**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! +`_. 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** + +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. + +**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 three ways to let us know how to get it: + +1. (preferred) **push changes to publicly available git clone and let + us know where to find it** + + Push your 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. + +2. **attaching the patch files to the issue** + + Run:: + + git format-patch -o patches /master + + Then tar up the newly created ``patches`` directory and attach the + directory to the issue. + + +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 and +send us the changes. + +Slartibartfast has cloned the MediaGoblin repository and his clone +lives on gitorious. + +Slartibartfast works locally. The remote named ``origin`` points to +his clone on gitorious. 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 + +2. Creates a branch from the tip of the MediaGoblin repository (the + remote is named ``gmg``) master branch called ``issue_42``:: + + git checkout -b issue_42 gmg/master + +3. Slartibartfast works hard on his changes in the ``issue_42`` + 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 (the remote is named + ``origin``):: + + git push origin issue_42 + +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 ``issue_42`` branch:: -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. + git checkout issue_42 -There are two ways you could send in a patch. +2. He fixes the bug and checks it into the ``issue_42`` branch. +3. He pushes his changes to his clone (the remote is named ``origin``):: -How to send in a patch from a publicly available clone ------------------------------------------------------- + git push origin issue_42 -Add a comment to the issue you're working on with the following bits -of information: +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 + ``issue_42`` branch of his publicly available clone. -* the url for your clone -* the revs you want looked at -* any details, questions, or other things that should be known +What happens next +----------------- -How to send in a patch if you don't have a publicly available clone -------------------------------------------------------------------- +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. -Assuming that the remote is our repository on gitorious and the branch -to compare against is master, do the following: +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 ``issue_42`` branch and adds +another comment to the issue tracker about how he fixed it. -1. checkout the branch you did your work in -2. do:: +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. - git format-patch -o patches origin/master +Slartibartfast is notified of this. Slartibartfast does a:: -3. either: + git fetch --all - * tar up and attach the tarball to the issue you're working on, OR - * attach the patch files to the issue you're working on one at a - time +The changes show up in the ``master`` branch of the ``gmg`` remote. +Slartibartfast now deletes his ``issue_42`` branch because he doesn't +need it anymore. How to learn git -- cgit v1.2.3 From fb6924170d0cc6b8648627edebc794e82b0946d7 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 12 Jun 2011 22:46:25 -0400 Subject: Tweaks git workflow structure * minor tweaking of the headers of the git workflow to break things up and organize them a bit better --- docs/git.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/git.rst b/docs/git.rst index ddbcf226..9a44867a 100644 --- a/docs/git.rst +++ b/docs/git.rst @@ -23,10 +23,11 @@ Do:: git clone git://gitorious.org/mediagoblin/mediagoblin.git -How to send in patches -====================== +How to contribute changes +========================= -**Tie your changes to issues in the issue tracker** +Tie your changes to issues in the issue tracker +----------------------------------------------- All patches should be tied to issues in the `issue tracker `_. That makes @@ -37,7 +38,9 @@ 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** + +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 @@ -56,7 +59,9 @@ 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. -**Properly document your changes** + +Properly document your changes +------------------------------ Include comments in the code. @@ -68,7 +73,8 @@ Write comprehensive comments in the issue tracker about what you're doing and why. -**How to send us your changes** +How to send us your changes +--------------------------- There are three ways to let us know how to get it: -- cgit v1.2.3 From 1e85d28e018e6dc0d4be9af82f221ac5450423bb Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 13 Jun 2011 09:08:18 -0500 Subject: Already mentioned, but clarifying that branches should be localized to a feature/bugfix/issue. --- docs/git.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/git.rst b/docs/git.rst index 9a44867a..6421e093 100644 --- a/docs/git.rst +++ b/docs/git.rst @@ -81,9 +81,9 @@ There are three ways to let us know how to get it: 1. (preferred) **push changes to publicly available git clone and let us know where to find it** - Push your 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. + 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. 2. **attaching the patch files to the issue** -- cgit v1.2.3 From 03db7d6c7416010a8eadecf93037ea398e6e07db Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 13 Jun 2011 12:24:52 -0400 Subject: Updates version in docs --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index fedaf33c..0e75a617 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, Free Software Foundation, Inc and contributors' # built documents. # # The short X.Y version. -version = '0.0.1' +version = '0.0.2' # The full version, including alpha/beta/rc tags. -release = '0.0.1' +release = '0.0.2' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 6729d65a3246208b658a3780c7fd62e20c666aa0 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 13 Jun 2011 12:31:23 -0400 Subject: Adds local toc sections * Some of our chapters are pretty long and this should make it much easier for a user to find what they're looking for and jumping to it. It's easier to read the section toc at the top of the chapter, than it is to read it in the sidebar. --- docs/codebase.rst | 4 ++++ docs/contributinghowto.rst | 4 ++++ docs/designdecisions.rst | 4 ++++ docs/git.rst | 4 ++++ docs/hackinghowto.rst | 4 ++++ 5 files changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/codebase.rst b/docs/codebase.rst index 4f5f215f..898eadfe 100644 --- a/docs/codebase.rst +++ b/docs/codebase.rst @@ -4,6 +4,10 @@ Codebase Documentation ======================== +.. contents:: Sections + :local: + + This chapter covers the libraries that GNU MediaGoblin uses as well as various recipes for getting things done. diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index e980a5e0..06d2814e 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -4,6 +4,10 @@ Contributing HOWTO ==================== +.. contents:: Sections + :local: + + .. _join-the-community-section: Join the community! diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst index 50dfe3e8..afa1e26b 100644 --- a/docs/designdecisions.rst +++ b/docs/designdecisions.rst @@ -4,6 +4,10 @@ Design Decisions ================== +.. contents:: Sections + :local: + + This chapter talks a bit about design decisions. diff --git a/docs/git.rst b/docs/git.rst index 6421e093..8eb038b2 100644 --- a/docs/git.rst +++ b/docs/git.rst @@ -2,6 +2,10 @@ Git, Cloning and Patches ========================== +.. contents:: Sections + :local: + + GNU MediaGoblin uses git for all our version control and we have the repositories hosted on `Gitorious `_. We have two repositories: diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index a9aadb62..d8bb9330 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -4,6 +4,10 @@ Hacking HOWTO =============== +.. contents:: Sections + :local: + + So you want to hack on GNU MediaGoblin? ======================================= -- cgit v1.2.3