From 5740a0d6aa8647c182c39680fecf6b902485a9b2 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 18:50:48 -0400 Subject: Updates to hacking howto * adds "what's where" section which isn't wildly interesting right now but it's somewhat interesting * adds "wiping environment" section --- docs/hackinghowto.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 96a7e1a4..50c59d08 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -41,7 +41,8 @@ If you're running Debian GNU/Linux or a Debian-derived distribution such as Mint or Ubuntu, running the following should install these requirements:: - sudo apt-get install mongodb git-core python python-dev python-lxml + sudo apt-get install mongodb git-core python python-dev \ + python-lxml Running bootstrap and buildout @@ -78,11 +79,26 @@ Updating dependencies --------------------- While hacking on GNU MediaGoblin over time, you'll eventually have to -update the dependencies. To do that, run:: +update your development environment. To do that, run:: ./bin/buildout +Wiping your environment for a clean-slate +----------------------------------------- + +Delete the following directories: + +* bin/ +* develop-eggs/ +* eggs/ +* mediagoblin.egg-info/ +* parts/ +* user_dev/ + +FIXME - how to drop data from mongodb? + + Running the server ================== @@ -99,6 +115,32 @@ Run:: ./bin/nosetests +What's where +============ + +After you've run buildout, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ source code + | |- tests/ + | |- templates/ + | |- auth/ + | \- submit/ + |- docs/ documentation + | + | the rest of these directories are generated by + | buildout. + | + |- bin/ scripts + |- develop-eggs/ + |- eggs/ + |- mediagoblin.egg-info/ + |- parts/ + |- user_dev/ sessions, etc + + + Quickstart for Django programmers ================================= -- cgit v1.2.3 From cafc7451ccdf0dc1d86eba92f3f75254c367d2f7 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 18:55:07 -0400 Subject: Minor tweaks to design decisions text --- docs/designdecisions.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst index 6156d523..3398c24b 100644 --- a/docs/designdecisions.rst +++ b/docs/designdecisions.rst @@ -17,11 +17,11 @@ Chris Webber on "Why Python": software web applications before in Python, including `Miro Community`_, the `Miro Guide`_, a large portion of `Creative Commons`_, and a whole bunch of things while working at `Imaginary - Landscape`_). I know Python, I can make this happen in Python, me - starting a project like this makes sense if it's done in Python. + Landscape`_). Me starting a project like this makes sense if it's + done in Python. You might say that PHP is way more deployable, that Rails has way - more cool developers riding around on fixie bikes, and all of + more cool developers riding around on fixie bikes---and all of those things are true. But I know Python, like Python, and think that Python is pretty great. I do think that deployment in Python is not as good as with PHP, but I think the days of shared hosting @@ -159,14 +159,16 @@ Why Sphinx for documentation Will Kahn-Greene on "Why Sphinx": - Sphinx is a fantastic tool for organizing documentation for a + `Sphinx`_ is a fantastic tool for organizing documentation for a Python-based project that makes it pretty easy to write docs that are readable in source form and can be "compiled" into HTML, LaTeX and other formats. There are other doc systems out there, but given that GNU - MediaGoblin is being written in Python, it makes sense to use - Sphinx for now. + MediaGoblin is being written in Python and I've done a ton of + documentation using Sphinx, it makes sense to use Sphinx for now. + +.. _Sphinx: http://sphinx.pocoo.org/ Why AGPLv3 and CC0? -- cgit v1.2.3 From 34366952a21f040ee5ca3df899a82f9e6bd9cffe Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 19:46:48 -0400 Subject: Heavy documentation updates * Nixed codedocs and software stack chapters in favor of a chapter on Beardomatic! * Switched workflow to vision and added an additional caveat at the top --- docs/beardomatic.rst | 84 +++++++++++++++++++++++++++++ docs/codedocs.rst | 5 -- docs/index.rst | 5 +- docs/softwarestack.rst | 127 ------------------------------------------- docs/vision.rst | 142 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/workflow.rst | 136 ---------------------------------------------- 6 files changed, 228 insertions(+), 271 deletions(-) create mode 100644 docs/beardomatic.rst delete mode 100644 docs/codedocs.rst delete mode 100644 docs/softwarestack.rst create mode 100644 docs/vision.rst delete mode 100644 docs/workflow.rst (limited to 'docs') diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst new file mode 100644 index 00000000..5ebeb239 --- /dev/null +++ b/docs/beardomatic.rst @@ -0,0 +1,84 @@ +=========================================== + Beardomatic: Infrastructure Documentation +=========================================== + +What the hell is Beardomatic? +============================= + +You might be wondering, "Gah! What the hell is Beardomatic!?" + +Well, I'll tell you. GNU MediaGoblin is a piece of software that sits +on a stack of libraries that do a bunch of stuff. It makes it easier +to differentiate the bits of code that encompass GNU MediaGoblin from +the bits of code that GNU MediaGoblin sit on top of. Thus, we came up +with the TOTALLY AWESOME name Beardomatic. + +Now you might be saying, "Holy crap!? Another web framework? Are you +going to write a mocking framework and an enumeration library, too!?" + +No, we're not. We're just calling this Beardomatic so that it's +easier to talk about things. However, at some point, we can take +these infrastructure bits from GNU MediaGoblin and turn them into a +full-blown "web framework". We wouldn't do this to compete for +mindshare with other web frameworks. We would do this to make it +easier for us to bootstrap other similar projects. + + +Beardomatic software stack +========================== + +Beardomatic is a software stack "web framework" composed of the +following bits: + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `buildout `_: for getting dependencies, + building a runtime environment, ... + +* Data storage + + * `MongoDB `_: the document database backend + for storage + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `WebOb `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Routes `_: for URL routing + + * `Beaker `_: for handling sessions + + * `Jinja2 `_: the templating engine + + * `MongoKit `_: the lightweight + ORM for MongoDB we're using which will make it easier to define + structures and all that + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `RabbitMQ `_: for sending tasks to celery + +* Front end + + * `JQuery `_: for groovy JavaScript things + + +How to ... in Beardomatic? +========================== + +FIXME - write this diff --git a/docs/codedocs.rst b/docs/codedocs.rst deleted file mode 100644 index 09f91274..00000000 --- a/docs/codedocs.rst +++ /dev/null @@ -1,5 +0,0 @@ -==================== - Code Documentation -==================== - -FIXME - stub! diff --git a/docs/index.rst b/docs/index.rst index fb92d139..fc8cc642 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,10 +17,9 @@ Table of Contents: deploymenthowto hackinghowto theminghowto - softwarestack designdecisions - workflow - codedocs + vision + beardomatic Indices and tables diff --git a/docs/softwarestack.rst b/docs/softwarestack.rst deleted file mode 100644 index 024f0d5d..00000000 --- a/docs/softwarestack.rst +++ /dev/null @@ -1,127 +0,0 @@ -======= - Stack -======= - -The software stack for this project might change over time, but this -is what we're thinking right now. - -There's some explanation of design decisions in the -:ref:`design-decisions-chapter`. - - -Python -====== - -* http://python.org/ - -The core team does a lot of work in Python and it's the language we're -most likely to do a project like this in. - - -MongoDB -======= - -* http://www.mongodb.org/ - -A "document database". Because it's extremely flexible and scales up -well, but I guess not down well. - - -MongoKit -======== - -* http://namlook.github.com/mongokit/ - -A lightweight ORM for mongodb. Helps us define our structures better, -does schema validation, schema evolution, and helps make things more -fun and pythonic. - - -Jinja2 -====== - -* http://jinja.pocoo.org/docs/ - -For templating. Pretty much django templates++ but allows us to pass -arguments into method calls instead of writing custom tags. - - -WTForms -======= - -* http://wtforms.simplecodes.com/ - -For form handling, validation, abstraction. Almost just like Django's -templates. - - -WebOb -===== - -* http://pythonpaste.org/webob/ - -Gives nice request/response objects (also somewhat Django-ish). - - -Paste Deploy and Paste Script -============================= - -* http://pythonpaste.org/deploy/ -* http://pythonpaste.org/script/ - -This will be the default way of configuring and launching the -application. Since GNU MediaGoblin will be fairly WSGI minimalist though, -you can probably use other ways to launch it, though this will be the -default. - - -Routes -====== - -* http://routes.groovie.org/ - -For URL Routing. It works well enough. - - -JQuery -====== - -* http://jquery.com/ - -For all sorts of things on the JavaScript end of things, for all sorts -of reasons. - - -Beaker -====== - -* http://beaker.groovie.org/ - -For sessions, because that seems like it's generally considered the -way to go I guess. - - -Nose -==== - -* http://somethingaboutorange.com/mrl/projects/nose/1.0.0/ - -For unit tests because it makes testing a bit nicer. - - -Celery -====== - -* http://celeryproject.org/ - -For task queueing (resizing images, encoding video, ...). - - -RabbitMQ -======== - -* http://www.rabbitmq.com/ - -For sending tasks to celery, because I guess that's what most people -do. Might be optional, might also let people use MongoDB for this if -they want. diff --git a/docs/vision.rst b/docs/vision.rst new file mode 100644 index 00000000..fad248df --- /dev/null +++ b/docs/vision.rst @@ -0,0 +1,142 @@ +========================================= + Design Document: GNU MediaGoblin vision +========================================= + +.. Note:: + + When we get a wiki, this will get moved there. It's here for now + mostly because we didn't have a better place for it. + +.. Note:: + + By the time you read this, it's very likely it'll be out of date. + + +This document attempts to describe the envisioned workflow of GNU +MediaGoblin, from a structural standpoint. For now, *nothing* in this +document is probably the eventual, final way that things will work. +Eventually as things come to exist, this document will hopefully be +refactored to describe how things *do* work. + +This documented on hopes, dreams, rainbows, and unicorns. And it will +come to fulfillment through a lot of hard work. Your hard work and my +hard work. + + +Look and feel +============= + +Default look and feel +--------------------- + +Mairin Duffy made mockups for something called Design Hub. That +project did a number of things differently than the way we intend to +go, but it's probably a good idea to steal a good number of ideas from +here. + +http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ + + +User profile mockup +------------------- + +Here's an ascii art mockup on how things might look for a user's page:: + + _____ + |_( )_| USER NAME + | | | + |_/_\_| + + Recent artwork: + ___________________ ___________________________ + | ___ ___ ___ | |_About_User_Name___________| + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | Some sort of self- | + | ___ ___ ___ | | description probably goes | + < | |pic| |pic| |pic| | > | here | + | |___| |___| |___| | | | + | ___ ___ ___ | | | + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | | + |___________________| |___________________________| + + ___________________________ + Recent favorites: |_Recent_activity___________| + ___________________ | New picture: DragonFace | + | ___ ___ ___ | | 4/2/2010 | + | |pic| |pic| |pic| | |---------------------------| + | |___| |___| |___| | | Sup yall this is some kind| + | ___ ___ ___ | | of mini blogpost. Maybe | + < | |pic| |pic| |pic| | > | the interface will allow | + | |___| |___| |___| | | for this? | + | ___ ___ ___ | |___________________________| + | |pic| |pic| |pic| | + | |___| |___| |___| | ___________________________ + |___________________| |_External_comments_here____| + | Dang! This stuff rocks | + | - Joe 4/2/2010 | + |---------------------------| + | Nice job on the dragon | + | - Morgan 4/2/2010 | + '---------------------------' + +So there's this type of interface that puts a lot of different types +of info on the same screen. I'm not sure that I like it. It's +possible we'll go with something much more minimalist. Maybe we'll go +with something "tabbed" the way statusnet / http://identi.ca is on +user pages. + +It's possible that we could support multiple profile styles here, +and you could load whatever profile style you want as set by user +preferences? + + +Uploading mockup +---------------- + +Here's an uploading mockup:: + + Upload an image + + [ Title ] + + Upload: [ ] [Browse] + ___________________________________________ + | | + | | + | o0O | + | o ' | + | o_.' | + | | + | Uploading... OK | <-, + | Resizing... OK | | + | | Area replaced w/ resized + | | image when done + |___________________________________________| + ________________ + License |_CC BY-SA_____|V| + ___________________________________________ + | Description goes here. | + | You can type it up in here and everything | + | and it'll show up under the image. | + | | + | Possibly we should allow some kind of | + | markup... maybe markdown? | + '___________________________________________' + + __________________________________________ + |> Advanced | + ------------------------------------------ + + +Customizability +--------------- + +General site theming customizability is pretty easy! Since we're +using `Jinja `_ we can just set up +user-overriding directories. + +We'll also figure out some sort of way to provide theming "packages", +eventually. + + diff --git a/docs/workflow.rst b/docs/workflow.rst deleted file mode 100644 index b72031de..00000000 --- a/docs/workflow.rst +++ /dev/null @@ -1,136 +0,0 @@ -========================================================================== - Design Document: Workflow, and other structurally significant braindumps -========================================================================== - -.. Note:: - - When we get a wiki, this will get moved there. It's here for now - mostly because we didn't have a better place for it. - - -This document attempts to describe the envisioned workflow of -mediagoblin, from a structural standpoint. For now, *nothing* in this -document is probably the eventual, final way that things will work. -Eventually as things come to exist, this document will hopefully be -refactored to describe how things *do* work. - -This documented on hopes, dreams, rainbows, and unicorns. And it will -come to fulfillment through a lot of hard work. - - -Look and feel -============= - -Default look and feel ---------------------- - -Mairin Duffy made mockups for something called Design Hub. That -project did a number of things differently than the way we intend to -go, but it's probably a good idea to steal a good number of ideas from -here. - -http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ - -User profile mockup -------------------- - -Here's an ascii art mockup on how things might look for a user's page:: - - _____ - |_( )_| USER NAME - | | | - |_/_\_| - - Recent artwork: - ___________________ ___________________________ - | ___ ___ ___ | |_About_User_Name___________| - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | Some sort of self- | - | ___ ___ ___ | | description probably goes | - < | |pic| |pic| |pic| | > | here | - | |___| |___| |___| | | | - | ___ ___ ___ | | | - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | | - |___________________| |___________________________| - - ___________________________ - Recent favorites: |_Recent_activity___________| - ___________________ | New picture: DragonFace | - | ___ ___ ___ | | 4/2/2010 | - | |pic| |pic| |pic| | |---------------------------| - | |___| |___| |___| | | Sup yall this is some kind| - | ___ ___ ___ | | of mini blogpost. Maybe | - < | |pic| |pic| |pic| | > | the interface will allow | - | |___| |___| |___| | | for this? | - | ___ ___ ___ | |___________________________| - | |pic| |pic| |pic| | - | |___| |___| |___| | ___________________________ - |___________________| |_External_comments_here____| - | Dang! This stuff rocks | - | - Joe 4/2/2010 | - |---------------------------| - | Nice job on the dragon | - | - Morgan 4/2/2010 | - '---------------------------' - -So there's this type of interface that puts a lot of different types -of info on the same screen. I'm not sure that I like it. It's -possible we'll go with something much more minimalist. Maybe we'll go -with something "tabbed" the way statusnet / http://identi.ca is on -user pages. - -It's possible that we could support multiple profile styles here, -and you could load whatever profile style you want as set by user -preferences? - - -Uploading mockup ----------------- - -Here's an uploading mockup:: - - Upload an image - - [ Title ] - - Upload: [ ] [Browse] - ___________________________________________ - | | - | | - | o0O | - | o ' | - | o_.' | - | | - | Uploading... OK | <-, - | Resizing... OK | | - | | Area replaced w/ resized - | | image when done - |___________________________________________| - ________________ - License |_CC BY-SA_____|V| - ___________________________________________ - | Description goes here. | - | You can type it up in here and everything | - | and it'll show up under the image. | - | | - | Possibly we should allow some kind of | - | markup... maybe markdown? | - '___________________________________________' - - __________________________________________ - |> Advanced | - ------------------------------------------ - - -Customizability ---------------- - -General site theming customizability is pretty easy! Since we're -using `Jinja `_ we can just set up -user-overriding directories. - -We'll also figure out some sort of way to provide theming "packages", -eventually. - - -- cgit v1.2.3 From 427ee0de13951a66d684d2a6afe33f45df7966b4 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 21:19:00 -0400 Subject: Adds Matt to docs contributors list --- docs/foreward.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/foreward.rst b/docs/foreward.rst index 0a3630a1..c1d60587 100644 --- a/docs/foreward.rst +++ b/docs/foreward.rst @@ -26,6 +26,7 @@ In no particular order: * Deb * Greg * Karen +* Matt How should I bring up errors in the documentation -- cgit v1.2.3 From 81be691a20edaeffc27d1cc160e0576ae5f9cd51 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 21:29:39 -0400 Subject: Changes version to 0.0.1. --- 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 02c190a0..6030b74d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, Chris Webber, et al' # built documents. # # The short X.Y version. -version = '0.1a1' +version = '0.0.1' # The full version, including alpha/beta/rc tags. -release = '0.1a1' +release = '0.0.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 75b70b90c3235d9883a799c4aea659879b5b3d89 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 21:29:50 -0400 Subject: Fixes mdashes and other minor things. --- docs/contributinghowto.rst | 2 +- docs/foreward.rst | 10 +++++----- docs/mediagoblin.rst | 21 ++++++++++++--------- 3 files changed, 18 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index a44c361f..cb5cd909 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -64,7 +64,7 @@ help with. Are there things about our instance you want to change? Are there things about other instances you wish were different? That's - great--you can run your own instance! + great---you can run your own instance! For more information on deploying your own instance, see :ref:`deployment-howto`. diff --git a/docs/foreward.rst b/docs/foreward.rst index c1d60587..edc75e30 100644 --- a/docs/foreward.rst +++ b/docs/foreward.rst @@ -16,8 +16,8 @@ This manual is a living document and is in the ``mediagoblin`` repository in the ``docs/`` directory. -Who wrote this documentation -============================ +Who wrote this documentation? +============================= In no particular order: @@ -29,10 +29,10 @@ In no particular order: * Matt -How should I bring up errors in the documentation -================================================= +I found an error in the docs---who do I tell? +============================================= -There are a few ways--please pick the one most convenient to you! +There are a few ways---please pick the one most convenient to you! 1. Send an email to Will ``willg at bluesock dot org``. 2. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . diff --git a/docs/mediagoblin.rst b/docs/mediagoblin.rst index 6c3a8dfa..a6194dc4 100644 --- a/docs/mediagoblin.rst +++ b/docs/mediagoblin.rst @@ -5,12 +5,13 @@ What is GNU MediaGoblin ======================= -Three years ago, 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. +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. @@ -46,10 +47,12 @@ How can I participate? See `Get Involved `. -How is this licensed? -===================== +How is GNU MediaGoblin licensed? +================================ -FIXME - write this once we work out the details +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? -- cgit v1.2.3 From 84489d7d4a3b3c0a897a9c4fe5176484bcf31d82 Mon Sep 17 00:00:00 2001 From: Matt Lee Date: Wed, 27 Apr 2011 10:55:35 -0400 Subject: Updated copyright --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 6030b74d..967d84d0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # General information about the project. project = u'GNU MediaGoblin' -copyright = u'2011, Chris Webber, et al' +copyright = u'2011, Free Software Foundation, Inc and contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the -- cgit v1.2.3 From 9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 27 Apr 2011 22:42:17 -0400 Subject: Reworked contributing docs based on Asheesh's thoughts I chatted with Asheesh on IRC today and asked him to look over the contributer howto. He had a lot of thoughts and I factored most/all of them in. It's much better now. --- docs/beardomatic.rst | 2 + docs/contributinghowto.rst | 115 ++++++++++++++++++++++++++++----------------- docs/deploymenthowto.rst | 2 + docs/foreward.rst | 7 +-- docs/hackinghowto.rst | 61 ++++++++++++++++++++++-- 5 files changed, 139 insertions(+), 48 deletions(-) (limited to 'docs') diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst index 5ebeb239..14130f6a 100644 --- a/docs/beardomatic.rst +++ b/docs/beardomatic.rst @@ -1,3 +1,5 @@ +.. _beardomatic-chapter: + =========================================== Beardomatic: Infrastructure Documentation =========================================== diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index cb5cd909..3b3fe163 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -2,72 +2,104 @@ Contributing HOWTO ==================== -We're super glad you want to contribute! +Join the community! +=================== + +We're super glad you want to join our community! There are a variety of ways you can help us and become part of the team. We're not just looking for coders! We're also looking for -documentation writers, users, testers, evangelists, painters, bakers, -candle-stick makers... +documentation writers, users, testers, evangelists, user-interface +designers, graphics designers, user-experience designers, system +administrators, friends, painters, bakers, candle-stick makers... -However, if you are a coder and you're looking to code, check out the -:ref:`hacking-howto`. +Here are some things you can do today: -The rest of this chapter talks about different things we need your -help with. + **Hang out with us** -**Become a user** + You should hang out with us! We like people like you! - We're building GNU MediaGoblin for us and for you but really - you're one of us and I am you and we are we and GNU MediaGoblin is - the walrus. - - Sign up for an account. Use the service. Relish in the thought - that this service comes with a heaping side of Freedom and you can - salt and pepper it to your liking. + At a bare minimum, join the `mailing list + `_ and say, "Hi!" + We also hang out on IRC in ``#mediagoblin`` on Freenode.net. -**File bugs** - Filing bugs is a critical part of any project. For more - information on filing bugs, see :ref:`filing-bugs`. + **File bugs** + Filing bugs is a critical part of any project. For more + information on filing bugs, see :ref:`filing-bugs`. -**Translate GNU MediaGoblin** - Knowing more than one language is an important skill. If you are - multi-lingual and are interested in translating GNU MediaGoblin, - see :ref:`translating`. + **Write/Fix some code** + If you are a coder and you're looking to code, check out the + :ref:`hacking-howto`. We even have tips on *becoming* a coder + and we're willing to help you! -**Create a theme** - As people deploy their own GNU MediaGoblin instances, good themes - are a must have! For more information on theming, see - :ref:`theming-howto`. + **Run your own instance** + + Are there things about our instance you want to change? Are + there things about other instances you wish were different? + Want to test upcoming changes? Want to create patches to + implement things you need? That's great---you can run your + own instance! + + For more information on deploying your own instance, see + :ref:`deployment-howto`. -**Spread the word** + **Spread the word** - The seductive call of Free Software services is a powerful one, - but many cannot hear it because it'd drowned out by the rush hour - traffic honking of proprietary walled gardens and faux free - services. Yuck! Be the sweet chirrup of the bird amidst the din! - Tell others that there is a better way to live! + The seductive call of Free Software services is a powerful + one, but many cannot hear it because it'd drowned out by the + rush hour traffic honking of proprietary walled gardens and + faux free services. Yuck! Be the sweet chirrup of the bird + amidst the din! Tell others that there is a better way to + live! - FIXME - do we want to talk about ways to spread the word? + FIXME - do we want to talk about ways to spread the word? - FIXME - how can people notify us that they're spreading the word? + FIXME - how can people notify us that they're spreading the + word? -**Run your own instance** +We're still working on project infrastructure. We hope to have the +bits in place for these additional things to do in the coming months: - Are there things about our instance you want to change? Are there - things about other instances you wish were different? That's - great---you can run your own instance! + **Become a user** + + We're building GNU MediaGoblin for us and for you but really + you're one of us and I am you and we are we and GNU + MediaGoblin is the walrus. - For more information on deploying your own instance, see - :ref:`deployment-howto`. + Sign up for an account. Use the service. Relish in the + thought that this service comes with a heaping side of Freedom + and you can salt and pepper it to your liking. + + + **Help other users** + + Have you spent time with GNU MediaGoblin? If so, your + experience and wisdom are invaluable and you're the best + person we can think of to help other users with their + questions. + + + **Translate GNU MediaGoblin** + + Knowing more than one language is an important skill. If you + are multi-lingual and are interested in translating GNU + MediaGoblin, see :ref:`translating`. + + + **Create a theme** + + As people deploy their own GNU MediaGoblin instances, good + themes are a must have! For more information on theming, see + :ref:`theming-howto`. Contributing thank you drawings / copyright assignment @@ -93,8 +125,7 @@ File bugs GNU MediaGoblin uses a bug tracker called `Redmine `_. -The bug tracker is at http://bugs.foocorp.net/ and bugs go in the -``GNU mediagoblin`` project. +The bug tracker is at ``_. A good bug report has the following things in it: diff --git a/docs/deploymenthowto.rst b/docs/deploymenthowto.rst index 684ac1b1..d943e276 100644 --- a/docs/deploymenthowto.rst +++ b/docs/deploymenthowto.rst @@ -9,3 +9,5 @@ Step 1: Write code that can be deployed. Step 2: ? Step 3: Write the deployment guide and profit! + +But seriously, this is a stub since we're not quite there, yet. diff --git a/docs/foreward.rst b/docs/foreward.rst index edc75e30..d2b9c417 100644 --- a/docs/foreward.rst +++ b/docs/foreward.rst @@ -27,6 +27,7 @@ In no particular order: * Greg * Karen * Matt +* Asheesh I found an error in the docs---who do I tell? @@ -34,9 +35,9 @@ I found an error in the docs---who do I tell? There are a few ways---please pick the one most convenient to you! -1. Send an email to Will ``willg at bluesock dot org``. -2. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . -3. Tell someone on IRC ``#mediagoblin`` on Freenode. +1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . +2. Tell someone on IRC ``#mediagoblin`` on Freenode. +3. Send an email to Will ``willg at bluesock dot org``. When you tell us about your issue, please let us know: diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 50c59d08..8b40e37d 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -8,8 +8,9 @@ So you want to hack on GNU MediaGoblin? ======================================= -First thing to do is check out the Web site where we list all the -project infrastructure including: +First thing to do is check out the `Web site +`_ where we list all the project +infrastructure including: * the mailing list * the IRC channel @@ -87,6 +88,13 @@ update your development environment. To do that, run:: Wiping your environment for a clean-slate ----------------------------------------- +.. Note:: + + Unless you're doing development and working on and testing creating + a new instance, you will probably never have to do this. Will + plans to do this work and thus he documented it. + + Delete the following directories: * bin/ @@ -96,7 +104,8 @@ Delete the following directories: * parts/ * user_dev/ -FIXME - how to drop data from mongodb? +FIXME - how to drop data from mongodb? we should probably write a +script. Running the server @@ -151,3 +160,49 @@ Bite-sized bugs to start with ============================= FIXME - write this + + +Tips for people new to coding +============================= + +Python +------ + +GNU MediaGoblin is written using a programming language called `Python +`_. + +There are two different incompatible iterations of Python which I'll +refer to as Python 2 and Python 3. GNU MediaGoblin is written in +Python 2 and requires Python 2.6 or 2.7. At some point, we might +switch to Python 3, but that's a future thing. + +You can learn how to code in Python 2 from several excellent books +that are freely available on the Internet: + +* `Learn Python the Hard Way `_ +* `Dive Into Pyton `_ +* `Python for Software Design `_ +* `A Byte of Python `_ + +These are all excellent texts. + +FIXME - are there good quality Python tutorial videos? + + +Libraries +--------- + +GNU MediaGoblin uses a variety of libraries in order to do what it +does. These libraries are listed in the :ref:`beardomatic-chapter` +along with links to the project Web sites and documentation for the +libraries. + +There are a variety of Python-related conferences every year that have +sessions covering many aspects of these libraries. You can find them +at `Python Miro Community `_ [0]_. + +.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro + Community. + +If you have questions or need help, find us on the mailing list and on +IRC. -- cgit v1.2.3 From 0c953025122fbbf0fd9d6c52f490802bca3648c0 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 28 Apr 2011 10:38:37 -0400 Subject: Moves "run your own instance" to the future section Chris correctly pointed out that you can't quite run your own instance, yet. But that's the goal! --- docs/contributinghowto.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index 3b3fe163..ff783b9c 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -39,18 +39,6 @@ Here are some things you can do today: and we're willing to help you! - **Run your own instance** - - Are there things about our instance you want to change? Are - there things about other instances you wish were different? - Want to test upcoming changes? Want to create patches to - implement things you need? That's great---you can run your - own instance! - - For more information on deploying your own instance, see - :ref:`deployment-howto`. - - **Spread the word** The seductive call of Free Software services is a powerful @@ -88,6 +76,18 @@ bits in place for these additional things to do in the coming months: questions. + **Run your own instance** + + Are there things about our instance you want to change? Are + there things about other instances you wish were different? + Want to test upcoming changes? Want to create patches to + implement things you need? That's great---you can run your + own instance! + + For more information on deploying your own instance, see + :ref:`deployment-howto`. + + **Translate GNU MediaGoblin** Knowing more than one language is an important skill. If you -- cgit v1.2.3 From 4305e7e64bdf0889f96199a4b6219911fcb08b82 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 28 Apr 2011 10:58:16 -0400 Subject: Adds "Send encouragement" section --- docs/contributinghowto.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index ff783b9c..f10dd72a 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -39,6 +39,16 @@ Here are some things you can do today: and we're willing to help you! + **Send encouragement** + + A nice word from you could send someone into a tizzy of + productive work. Ten nice words could complete a feature. + One hundred nice words could get us to the next milestone. + + Send it to the `mailing list `_ + or hop into ``#mediagoblin`` on Freenode.net and let us know. + + **Spread the word** The seductive call of Free Software services is a powerful -- cgit v1.2.3 From 515b8a48c905d28d682663aa2040850833a5d51a Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 28 Apr 2011 16:27:09 -0400 Subject: Adds placeholder file so _static exists. --- docs/_static/placeholder | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/placeholder (limited to 'docs') diff --git a/docs/_static/placeholder b/docs/_static/placeholder new file mode 100644 index 00000000..e69de29b -- cgit v1.2.3