diff options
author | Will Kahn-Greene <willg@bluesock.org> | 2011-04-27 22:42:17 -0400 |
---|---|---|
committer | Will Kahn-Greene <willg@bluesock.org> | 2011-04-27 22:46:27 -0400 |
commit | 9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba (patch) | |
tree | b6be68c4d65a379fdeb78d8bdd034b3ebd4c00b0 /docs | |
parent | 84489d7d4a3b3c0a897a9c4fe5176484bcf31d82 (diff) | |
download | mediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.tar.lz mediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.tar.xz mediagoblin-9d952fdc7930dcdf1c2ee5ca6094c80a998d86ba.zip |
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.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/beardomatic.rst | 2 | ||||
-rw-r--r-- | docs/contributinghowto.rst | 115 | ||||
-rw-r--r-- | docs/deploymenthowto.rst | 2 | ||||
-rw-r--r-- | docs/foreward.rst | 7 | ||||
-rw-r--r-- | docs/hackinghowto.rst | 61 |
5 files changed, 139 insertions, 48 deletions
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 + <http://mediagoblin.org/join/>`_ 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 <http://www.redmine.org>`_. -The bug tracker is at http://bugs.foocorp.net/ and bugs go in the -``GNU mediagoblin`` project. +The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_. 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 +<http://mediagoblin.org>`_ 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 +<http://python.org/>`_. + +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 <http://learnpythonthehardway.org/>`_ +* `Dive Into Pyton <http://diveintopython.org/>`_ +* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_ +* `A Byte of Python <http://www.swaroopch.com/notes/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 <http://python.mirocommunity.org>`_ [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. |