diff options
Diffstat (limited to 'docs/source/contributinghowto.rst')
| -rw-r--r-- | docs/source/contributinghowto.rst | 262 |
1 files changed, 146 insertions, 116 deletions
diff --git a/docs/source/contributinghowto.rst b/docs/source/contributinghowto.rst index a4f5771a..8eaff5e4 100644 --- a/docs/source/contributinghowto.rst +++ b/docs/source/contributinghowto.rst @@ -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! - -See `the join page on the website <http://mediagoblin.org/join/>`_ for -where we hang out. - -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... - -Here are some things you can do today: - +We're **really** glad that you want to join the MediaGoblin community! - **Hang out with us** +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. - You should hang out with us! We like people like you! +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. - At a bare minimum, join the `mailing list - <http://mediagoblin.org/join/>`_ and say, "Hi!" +Hang out with the MediaGoblin folk +---------------------------------- - We also hang out on IRC in ``#mediagoblin`` on Freenode.net. +MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_, +and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_. +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. - **File bugs** +File Bugs / Triage Bugs +----------------------- - Filing bugs is a critical part of any project. For more - information on filing bugs, see :ref:`filing-bugs`. +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. +See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best +and most useful bug reports. - **Write/Fix some code** +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. - 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! +See the section on `bug triage <#triage-bugs>`_ for suggestions on how +to most effectively triage and approach the issue queue. +Write/Fix Code +-------------- - **Send encouragement** +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! - 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 Encouragement, Spread the Word +----------------------------------- - Send it to the `mailing list <http://mediagoblin.org/join/>`_ - or hop into ``#mediagoblin`` on Freenode.net and let us know. +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. - **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** - - 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. +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. - **Help other users** +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. - 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. +Help Others +----------- - **Run your own instance** +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. - 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`. +Run your own MediaGoblin Instance +--------------------------------- - **Translate GNU MediaGoblin** +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! - 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`. +For more information on deploying your own instance, see +the `Deployment HOWTO </deploymenthowto.html>`_ +.. _translating: -Contributing thank you drawings / copyright assignment -====================================================== +Translate MediaGoblin +--------------------- -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. +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. -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: + +Triage Bugs +=========== + +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: -Translate GNU MediaGoblin -========================= +- ensure that one or two people in addition to the initial reporter + have been able to reproduce the issue. -Coming soon when we set up translation infrastructure. +- 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. -Where to go when you get stuck -============================== +How to Get Help with MediaGoblin +================================ -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. +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. |