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.
This commit is contained in:
Will Kahn-Greene
parent
84489d7d4a
commit
9d952fdc79
@ -1,3 +1,5 @@
|
||||
.. _beardomatic-chapter:
|
||||
|
||||
===========================================
|
||||
Beardomatic: Infrastructure Documentation
|
||||
===========================================
|
||||
|
||||
@ -2,74 +2,106 @@
|
||||
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`.
|
||||
|
||||
The rest of this chapter talks about different things we need your
|
||||
help with.
|
||||
Here are some things you can do today:
|
||||
|
||||
|
||||
**Become a user**
|
||||
**Hang out with us**
|
||||
|
||||
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.
|
||||
You should hang out with us! We like people like you!
|
||||
|
||||
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**
|
||||
**File bugs**
|
||||
|
||||
Filing bugs is a critical part of any project. For more
|
||||
information on filing bugs, see :ref:`filing-bugs`.
|
||||
|
||||
|
||||
**Translate GNU MediaGoblin**
|
||||
**Write/Fix some code**
|
||||
|
||||
Knowing more than one language is an important skill. If you are
|
||||
multi-lingual and are interested in translating GNU MediaGoblin,
|
||||
see :ref:`translating`.
|
||||
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**
|
||||
**Run your own instance**
|
||||
|
||||
As people deploy their own GNU MediaGoblin instances, good themes
|
||||
are a must have! For more information on theming, see
|
||||
:ref:`theming-howto`.
|
||||
|
||||
|
||||
**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!
|
||||
|
||||
FIXME - do we want to talk about ways to spread the word?
|
||||
|
||||
FIXME - how can people notify us that they're spreading the word?
|
||||
|
||||
|
||||
**Run your own instance**
|
||||
|
||||
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!
|
||||
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
|
||||
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 - how can people notify us that they're spreading the
|
||||
word?
|
||||
|
||||
|
||||
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:
|
||||
|
||||
**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.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user