From 26924b717efe7942593c992999a792de36dc82f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 21 Aug 2011 22:23:03 -0500 Subject: Changing the MediaGoblin Sphinx docs a bit... - Removing the git guide, and moved it to the wiki - moving mediagoblin.rst to about_mediagoblin.rst --- docs/source/about_mediagoblin.rst | 70 ++++++++++++ docs/source/git.rst | 224 -------------------------------------- docs/source/index.rst | 5 +- docs/source/mediagoblin.rst | 70 ------------ 4 files changed, 72 insertions(+), 297 deletions(-) create mode 100644 docs/source/about_mediagoblin.rst delete mode 100644 docs/source/git.rst delete mode 100644 docs/source/mediagoblin.rst (limited to 'docs/source') diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst new file mode 100644 index 00000000..af6658f3 --- /dev/null +++ b/docs/source/about_mediagoblin.rst @@ -0,0 +1,70 @@ +================= + GNU MediaGoblin +================= + +.. contents:: Sections + :local: + + +What is GNU MediaGoblin +======================= + +Three years ago (2008), a number of free software luminaries got +together at the FSF office to answer the question, "What should +software freedom look like on the participatory web?" Those thinkers +included Richard Stallman---founder of the free software movement and +instigator of the GNU project, Evan Prodromou---the driving force +behind Status.net, a highly sucessful federated micro-blogging +service, and FIXME. + +Since that time Identi.ca and Libre.fm have answered the +freedom-loving web-user's need for micro-blogging and music sharing. +Now, GNU MediaGoblin is building a format for users to share photos. +Later versions of MediaGoblin will include support for video and other +media as well as tools to encourage collaboration on media projects. + + +Why are we doing this? +====================== + +Centralization and proprietization of media on the internet is a +serious problem and makes the web go from a system of extreme +resilience to a system of frightening fragility. We believe people +should be able to free their data from proprietary control and that +means someone has to build the tools to make it possible. We decided +that in this case, that someone would be us! + + +Who are you? +============ + +Free software activists and folks who have worked on a variety of +other projects like Libre.fm, GNU Social, Status.net, Miro, Miro +Community, OpenHatch and other projects as well. We're admirers and +contributors. We're writers and painters. We're friendly and +dedicated to computer user freedom. + + +How can I participate? +====================== + +See `Get Involved `_ on the website.. + + +How is GNU MediaGoblin licensed? +================================ + +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the source for details. + + +Is this an official GNU Project? What does that mean? +====================================================== + +We are! It means that we meet the GNU Project's rigourous standards +for free software. To find out more about what that means, check out +`the GNU site `_. + +Please feel free to contact us with further questions! + 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 diff --git a/docs/source/mediagoblin.rst b/docs/source/mediagoblin.rst deleted file mode 100644 index af6658f3..00000000 --- a/docs/source/mediagoblin.rst +++ /dev/null @@ -1,70 +0,0 @@ -================= - GNU MediaGoblin -================= - -.. contents:: Sections - :local: - - -What is GNU MediaGoblin -======================= - -Three years ago (2008), a number of free software luminaries got -together at the FSF office to answer the question, "What should -software freedom look like on the participatory web?" Those thinkers -included Richard Stallman---founder of the free software movement and -instigator of the GNU project, Evan Prodromou---the driving force -behind Status.net, a highly sucessful federated micro-blogging -service, and FIXME. - -Since that time Identi.ca and Libre.fm have answered the -freedom-loving web-user's need for micro-blogging and music sharing. -Now, GNU MediaGoblin is building a format for users to share photos. -Later versions of MediaGoblin will include support for video and other -media as well as tools to encourage collaboration on media projects. - - -Why are we doing this? -====================== - -Centralization and proprietization of media on the internet is a -serious problem and makes the web go from a system of extreme -resilience to a system of frightening fragility. We believe people -should be able to free their data from proprietary control and that -means someone has to build the tools to make it possible. We decided -that in this case, that someone would be us! - - -Who are you? -============ - -Free software activists and folks who have worked on a variety of -other projects like Libre.fm, GNU Social, Status.net, Miro, Miro -Community, OpenHatch and other projects as well. We're admirers and -contributors. We're writers and painters. We're friendly and -dedicated to computer user freedom. - - -How can I participate? -====================== - -See `Get Involved `_ on the website.. - - -How is GNU MediaGoblin licensed? -================================ - -GNU MediaGoblin software is released under an AGPLv3 license. - -See the ``COPYING`` file in the source for details. - - -Is this an official GNU Project? What does that mean? -====================================================== - -We are! It means that we meet the GNU Project's rigourous standards -for free software. To find out more about what that means, check out -`the GNU site `_. - -Please feel free to contact us with further questions! - -- cgit v1.2.3