From: Christopher Allan Webber Date: Mon, 22 Aug 2011 03:23:03 +0000 (-0500) Subject: Changing the MediaGoblin Sphinx docs a bit... X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=26924b717efe7942593c992999a792de36dc82f4;p=mediagoblin.git Changing the MediaGoblin Sphinx docs a bit... - Removing the git guide, and moved it to the wiki - moving mediagoblin.rst to about_mediagoblin.rst --- diff --git a/docs/source/mediagoblin.rst b/docs/source/about_mediagoblin.rst similarity index 100% rename from docs/source/mediagoblin.rst rename to docs/source/about_mediagoblin.rst diff --git a/docs/source/git.rst b/docs/source/git.rst deleted file mode 100644 index ab3206b6..00000000 --- a/docs/source/git.rst +++ /dev/null @@ -1,224 +0,0 @@ -========================== - 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: - -* 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 -======================== - -Do:: - - git clone git://gitorious.org/mediagoblin/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: - -1. *(preferred)* **push changes to publicly available git clone and - let us know where to find it** - - 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** - - Run:: - - git format-patch --stdout /master > issue_.patch - - ``format-patch`` creates a patch of all the commits that are in - your branch that aren't in ``/master``. The ``--stdout`` - flag causes all this output to go to stdout where it's redirected - to a file named ``issue_.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 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 - - 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. - -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 -================ - -Check out `the wiki `_. diff --git a/docs/source/index.rst b/docs/source/index.rst index 8c00869a..79f2653e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,11 +12,10 @@ Table of Contents: :maxdepth: 2 foreword - mediagoblin - contributinghowto + about_mediagoblin deploymenthowto theminghowto - git + contributinghowto codebase vision