Documentation Revision, clarification, and editing.
- a line in the .gitignore file to ignore the built documentation tree. - a complete revision/editorial pass of all non-technical documents that outline process, project fundamentals, and background. These edits clarified the text, unified the style, and elaborated on stubs.
This commit is contained in:
tycho garen
@@ -1,185 +1,215 @@
|
||||
.. _contributing-howto-chapter:
|
||||
|
||||
====================
|
||||
Contributing HOWTO
|
||||
====================
|
||||
===================================
|
||||
HOWTO Contribute to GNU MediaGoblin
|
||||
===================================
|
||||
|
||||
.. contents:: Sections
|
||||
:local:
|
||||
|
||||
|
||||
.. _join-the-community-section:
|
||||
|
||||
Join the community!
|
||||
===================
|
||||
|
||||
We're super glad you want to join our community!
|
||||
We're **really** glad that you want to join the MediaGoblin community!
|
||||
|
||||
See `the join page on the website <http://mediagoblin.org/join/>`_ for
|
||||
where we hang out.
|
||||
There are a variety of ways to help and support MediaGoblin and to
|
||||
join the team. If you want to code, great, if not, even better!
|
||||
MediaGoblin interested contributors in many different roles: users,
|
||||
system administrators, technical writers, testers, evangelists,
|
||||
UI/UX and graphics designers, cheerleaders, and dreamers.
|
||||
|
||||
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, user-interface
|
||||
designers, graphics designers, user-experience designers, system
|
||||
administrators, friends, painters, bakers, candle-stick makers...
|
||||
This document provides an overview of different ways you can get
|
||||
involved with MediaGoblin along with instructions for getting
|
||||
started. There is some obvious overlap with `the "join" page on
|
||||
mediagoblin.org <http://mediagoblin.org/pages/join.html>`_ at present.
|
||||
|
||||
Here are some things you can do today:
|
||||
Hang out with the MediaGoblin folk
|
||||
----------------------------------
|
||||
|
||||
MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_,
|
||||
and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_.
|
||||
|
||||
**Hang out with us**
|
||||
Don't be afraid to drop by and say "Hi!" And, if you're looking for
|
||||
something to do, just ask: there's always work to be done.
|
||||
|
||||
You should hang out with us! We like people like you!
|
||||
File Bugs / Triage Bugs
|
||||
-----------------------
|
||||
|
||||
At a bare minimum, join the `mailing list
|
||||
<http://mediagoblin.org/join/>`_ and say, "Hi!"
|
||||
Issue reports are critical for all projects. Identified bugs give
|
||||
developers a basis for beginning work, and providing an idea of what
|
||||
features and issues are most important to users and the overall
|
||||
usability of the software. If you identify errors, flaws, unexpected
|
||||
behaviors, or deficits that impede use, file a bug.
|
||||
|
||||
We also hang out on IRC in ``#mediagoblin`` on Freenode.net.
|
||||
See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best
|
||||
and most useful bug reports.
|
||||
|
||||
If you want to contribute to MediaGoblin and don't know where to
|
||||
start, look at the `bug database <http://bugs.foocorp.net/projects/mediagoblin/issues>`_
|
||||
as a starting point.
|
||||
|
||||
**File bugs**
|
||||
See the section on `bug triage <#triage-bugs>`_ for suggestions on how
|
||||
to most effectively triage and approach the issue queue.
|
||||
|
||||
Filing bugs is a critical part of any project. For more
|
||||
information on filing bugs, see :ref:`filing-bugs`.
|
||||
Write/Fix Code
|
||||
--------------
|
||||
|
||||
If you are a coder and you would like to write code, the `repository <https://gitorious.org/mediagoblin>`_
|
||||
is hosted on `gitorious <https://gitorious.org/>`_. Clone or fork the
|
||||
repository and start poking around. Become familiar with this `manual </>`_
|
||||
for an overview of how the software works and is used. Consider the
|
||||
`contributor wiki <http://wiki.mediagoblin.org/>`_ for more
|
||||
information about the project, our preferred methods, and guides for
|
||||
developing MediaGoblin. We even have tips on *becoming* a coder and
|
||||
we're willing to help!
|
||||
|
||||
**Write/Fix some code**
|
||||
Send Encouragement, Spread the Word
|
||||
-----------------------------------
|
||||
|
||||
If you are a coder and you're looking to code, check out the
|
||||
`wiki <http://wiki.mediagoblin.org/`_. We even have tips on
|
||||
*becoming* a coder and we're willing to help you!
|
||||
Sometimes, a nice word, simple encouragement, and interest in the work
|
||||
we're doing is enough to inspire a tizzy of productive work. Just a
|
||||
bit more interest and encouragement can even make the difference
|
||||
between a complete feature and limited functionality; between a
|
||||
completed milestone and lost momentum.
|
||||
|
||||
Similarly, MediaGoblin, and the movement for free network services, is
|
||||
always in need of encouragement. Use free network services, understand
|
||||
the `principals <http://autonomo.us/2008/07/franklin-street-statement/>`_
|
||||
behind the movement, be able to articulate the benefits of free
|
||||
network services and the problems with psudo-free applications that
|
||||
don't respect the users' freedom.
|
||||
|
||||
**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 <http://mediagoblin.org/join/>`_
|
||||
or hop into ``#mediagoblin`` on Freenode.net and let us know.
|
||||
|
||||
|
||||
**Spread the word**
|
||||
|
||||
The seductive call of Free Software services is a powerful
|
||||
one, but many cannot hear it because it's 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?
|
||||
Write a blog post, post a status update, drop by the `listserv <http://mediagoblin.org/join/>`_
|
||||
or join ``#mediagoblin`` on freenode.net and let us know.
|
||||
|
||||
Participate in MediaGoblin
|
||||
==========================
|
||||
|
||||
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**
|
||||
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.
|
||||
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**
|
||||
Help Others
|
||||
-----------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
**Run your own instance**
|
||||
Run your own MediaGoblin 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`.
|
||||
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
|
||||
the `Deployment HOWTO </deploymenthowto.html>`_
|
||||
|
||||
**Translate GNU MediaGoblin**
|
||||
.. _translating:
|
||||
|
||||
Knowing more than one language is an important skill. If you
|
||||
are multi-lingual and are interested in translating GNU
|
||||
MediaGoblin, see :ref:`translating`.
|
||||
Translate MediaGoblin
|
||||
---------------------
|
||||
|
||||
If you know English and another language and feel comfortable
|
||||
translating elements of the interface or even the documentation,
|
||||
we'd love to have help translating the software and resources.
|
||||
|
||||
**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
|
||||
======================================================
|
||||
|
||||
Copyright assignment with GNU MediaGoblin to the `FSF
|
||||
<http://fsf.org>`_ is highly encouraged but not mandatory. To
|
||||
incentivize both this and people to make cool contributions to our
|
||||
project, if you make useful contributions to GNU MediaGoblin *and* do
|
||||
a copyright assignment to the Free Software Foundation, the founder of
|
||||
the project, Chris Webber, will make a custom drawing of a goblin
|
||||
dedicated specifically to you.
|
||||
|
||||
For why we're doing copyright assignment, see the
|
||||
`wiki <http://wiki.mediagoblin.org/>`_.
|
||||
Create a Theme
|
||||
--------------
|
||||
|
||||
MedaGoblin development is premised on the idea that the entire
|
||||
interface for the platform be completely theme-able. If you have a
|
||||
design or theming background, consider developing themes for
|
||||
MediaGoblin. New themes help test the theming system, provide
|
||||
attractive and appealing interfaces for prospective users. If you want
|
||||
to start a new theme but don't know where to start, touch base with
|
||||
the development community on the list or in the IRC channel for more
|
||||
information.
|
||||
|
||||
.. _filing-bugs:
|
||||
|
||||
File bugs
|
||||
File Bugs
|
||||
=========
|
||||
|
||||
GNU MediaGoblin uses a bug tracker called `Redmine
|
||||
<http://www.redmine.org>`_.
|
||||
MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_.
|
||||
|
||||
The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
|
||||
Our instance is located at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
|
||||
|
||||
A good bug report has the following things in it:
|
||||
The most useful bug reports have the following components:
|
||||
|
||||
1. A short summary that's 60 characters or less.
|
||||
|
||||
2. A description that describes the issue (bug, feature request, ...)
|
||||
as well as the context.
|
||||
as well as the context. Consider:
|
||||
|
||||
* If it's a bug, can you reproduce it? Is the issue specific to a
|
||||
browser, computer, image, ...?
|
||||
* If you think you've found a bug, can you reproduce it in a
|
||||
controlled environment? Is the issue specific to a browser,
|
||||
computer, image, media type, or other dimension? All data helps.
|
||||
|
||||
* If it's a feature request, are there related links on the Internet
|
||||
for more information? Would you be willing to help implement or
|
||||
test the feature?
|
||||
* If you're submitting a feature request, are there related links
|
||||
on the Internet for more information? Would you be willing to
|
||||
help implement or test the feature?
|
||||
|
||||
That's it! When someone looks into the issue and has questions,
|
||||
they'll contact you!
|
||||
That's it!
|
||||
|
||||
If you don't hear from anyone in a couple of weeks, find someone on
|
||||
IRC.
|
||||
The better the issue report, the easier it is to address the bug, and
|
||||
the more likely that the developers will be able to resolve the
|
||||
issue. If someone has questions about the bug report, they may reach
|
||||
out to the reporter directly.
|
||||
|
||||
If you get a response after a couple of weeks, find someone on IRC.
|
||||
|
||||
.. _translating:
|
||||
.. _triage-bugs:
|
||||
|
||||
Translate GNU MediaGoblin
|
||||
=========================
|
||||
Triage Bugs
|
||||
===========
|
||||
|
||||
Coming soon when we set up translation infrastructure.
|
||||
The triage process involves reviewing bugs, removing duplicates,
|
||||
validating that the issues described are reproducible, ensuring that
|
||||
the exact behavior is properly documented, diagnosing the cause of
|
||||
each issue, and working with developers to ensure that critical bugs
|
||||
get addressed. In many cases, developers do this kind of work as a
|
||||
matter of course, but one need not be able to code in order to help
|
||||
working with bugs.
|
||||
|
||||
To triage bugs, go to the `bug tracker <http://bugs.foocorp.net/projects/mediagoblin>`_
|
||||
and begin reviewing the open issues. If you are able, attempt to:
|
||||
|
||||
Where to go when you get stuck
|
||||
==============================
|
||||
- ensure that one or two people in addition to the initial reporter
|
||||
have been able to reproduce the issue.
|
||||
|
||||
Go to `our Web site <http://mediagoblin.org/>`_ where we list the
|
||||
various places we hang out and how to get a hold of us.
|
||||
- document the issue more clearly. If you had any trouble reproducing
|
||||
the issue, provide any elucidating information that you can to help
|
||||
others solve the problem more effectively.
|
||||
|
||||
- find a way to resolve the problem or provide a workaround.
|
||||
|
||||
For help, instructions, and suggestions be in touch with the
|
||||
development community on the list or in the IRC channel for more
|
||||
information. With many eyes, all bugs are shallow.
|
||||
|
||||
How to Get Help with MediaGoblin
|
||||
================================
|
||||
|
||||
The usual channels, the IRC channel, the listserv, the bug tracker,
|
||||
are all great ways to be in touch with us. Check the `web site <http://mediagoblin.org/pages/join.html>`_
|
||||
for more specific contact information.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user