docs/source/contributinghowto.rst

   1 .. _contributing-howto-chapter:
   2
   3 ===================================
   4 HOWTO Contribute to GNU MediaGoblin
   5 ===================================
   6
   7 .. contents:: Sections
   8    :local:
   9
  10 .. _join-the-community-section:
  11
  12 Join the community!
  13 ===================
  14
  15 We're **really** glad that you want to join the MediaGoblin community!
  16
  17 There are a variety of ways to help and support MediaGoblin and to
  18 join the team.  If you want to code, great, if not, even better!
  19 MediaGoblin interested contributors in many different roles: users,
  20 system administrators, technical writers, testers, evangelists,
  21 UI/UX and graphics designers, cheerleaders, and dreamers.
  22
  23 This document provides an overview of different ways you can get
  24 involved with MediaGoblin along with instructions for getting
  25 started. There is some obvious overlap with `the "join" page on
  26 mediagoblin.org <http://mediagoblin.org/pages/join.html>`_ at present.
  27
  28 Hang out with the MediaGoblin folk
  29 ----------------------------------
  30
  31 MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_,
  32 and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_.
  33
  34 Don't be afraid to drop by and say "Hi!" And, if you're looking for
  35 something to do, just ask: there's always work to be done.
  36
  37 File Bugs / Triage Bugs
  38 -----------------------
  39
  40 Issue reports are critical for all projects. Identified bugs give
  41 developers a basis for beginning work, and providing an idea of what
  42 features and issues are most important to users and the overall
  43 usability of the software. If you identify errors, flaws, unexpected
  44 behaviors, or deficits that impede use, file a bug.
  45
  46 See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best
  47 and most useful bug reports.
  48
  49 If you want to contribute to MediaGoblin and don't know where to
  50 start, look at the `bug database <http://bugs.foocorp.net/projects/mediagoblin/issues>`_
  51 as a starting point.
  52
  53 See the section on `bug triage <#triage-bugs>`_ for suggestions on how
  54 to most effectively triage and approach the issue queue.
  55
  56 Write/Fix Code
  57 --------------
  58
  59 If you are a coder and you would like to write code, the `repository <https://gitorious.org/mediagoblin>`_
  60 is hosted on `gitorious <https://gitorious.org/>`_. Clone or fork the
  61 repository and start poking around. Become familiar with this `manual </>`_
  62 for an overview of how the software works and is used. Consider the
  63 `contributor wiki <http://wiki.mediagoblin.org/>`_ for more
  64 information about the project, our preferred methods, and guides for
  65 developing MediaGoblin. We even have tips on *becoming* a coder and
  66 we're willing to help!
  67
  68 Send Encouragement, Spread the Word
  69 -----------------------------------
  70
  71 Sometimes, a nice word, simple encouragement, and interest in the work
  72 we're doing is enough to inspire a tizzy of productive work. Just a
  73 bit more interest and encouragement can even make the difference
  74 between a complete feature and limited functionality; between a
  75 completed milestone and lost momentum.
  76
  77 Similarly, MediaGoblin, and the movement for free network services, is
  78 always in need of encouragement. Use free network services, understand
  79 the `principals <http://autonomo.us/2008/07/franklin-street-statement/>`_
  80 behind the movement, be able to articulate the benefits of free
  81 network services and the problems with psudo-free applications that
  82 don't respect the users' freedom.
  83
  84 Write a blog post, post a status update, drop by the `listserv <http://mediagoblin.org/join/>`_
  85 or join ``#mediagoblin`` on freenode.net and let us know.
  86
  87 Participate in MediaGoblin
  88 ==========================
  89
  90 We're still working on project infrastructure.  We hope to have the
  91 bits in place for these additional things to do in the coming months:
  92
  93 Become a User
  94 -------------
  95
  96 We're building GNU MediaGoblin for us and for you but really
  97 you're one of us and I am you and we are we and GNU
  98 MediaGoblin is the walrus.
  99
 100 Sign up for an account.  Use the service.  Relish in the
 101 thought that this service comes with a heaping side of Freedom
 102 and you can salt and pepper it to your liking.
 103
 104
 105 Help Others
 106 -----------
 107
 108 Have you spent time with GNU MediaGoblin?  If so, your
 109 experience and wisdom are invaluable and you're the best
 110 person we can think of to help other users with their
 111 questions.
 112
 113
 114 Run your own MediaGoblin Instance
 115 ---------------------------------
 116
 117 Are there things about our instance you want to change?  Are
 118 there things about other instances you wish were different?
 119 Want to test upcoming changes?  Want to create patches to
 120 implement things you need?  That's great---you can run your
 121 own instance!
 122
 123 For more information on deploying your own instance, see
 124 the `Deployment HOWTO </deploymenthowto.html>`_
 125
 126 .. _translating:
 127
 128 Translate MediaGoblin
 129 ---------------------
 130
 131 If you know English and another language and feel comfortable
 132 translating elements of the interface or even the documentation,
 133 we'd love to have help translating the software and resources.
 134
 135 Create a Theme
 136 --------------
 137
 138 MedaGoblin development is premised on the idea that the entire
 139 interface for the platform be completely theme-able. If you have a
 140 design or theming background, consider developing themes for
 141 MediaGoblin. New themes help test the theming system, provide
 142 attractive and appealing interfaces for prospective users. If you want
 143 to start a new theme but don't know where to start, touch base with
 144 the development community on the list or in the IRC channel for more
 145 information.
 146
 147 .. _filing-bugs:
 148
 149 File Bugs
 150 =========
 151
 152 MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_.
 153
 154 Our instance is located at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
 155
 156 The most useful bug reports have the following components:
 157
 158 1. A short summary that's 60 characters or less.
 159
 160 2. A description that describes the issue (bug, feature request, ...)
 161    as well as the context. Consider:
 162
 163    * If you think you've found a bug, can you reproduce it in a
 164      controlled environment?  Is the issue specific to a browser,
 165      computer, image, media type, or other dimension? All data helps.
 166
 167    * If you're submitting a feature request, are there related links
 168      on the Internet for more information?  Would you be willing to
 169      help implement or test the feature?
 170
 171 That's it!
 172
 173 The better the issue report, the easier it is to address the bug, and
 174 the more likely that the developers will be able to resolve the
 175 issue. If someone has questions about the bug report, they may reach
 176 out to the reporter directly.
 177
 178 If you get a response after a couple of weeks, find someone on IRC.
 179
 180 .. _triage-bugs:
 181
 182 Triage Bugs
 183 ===========
 184
 185 The triage process involves reviewing bugs, removing duplicates,
 186 validating that the issues described are reproducible, ensuring that
 187 the exact behavior is properly documented, diagnosing the cause of
 188 each issue, and working with developers to ensure that critical bugs
 189 get addressed. In many cases, developers do this kind of work as a
 190 matter of course, but one need not be able to code in order to help
 191 working with bugs.
 192
 193 To triage bugs, go to the `bug tracker <http://bugs.foocorp.net/projects/mediagoblin>`_
 194 and begin reviewing the open issues. If you are able, attempt to:
 195
 196 - ensure that one or two people in addition to the initial reporter
 197   have been able to reproduce the issue.
 198
 199 - document the issue more clearly. If you had any trouble reproducing
 200   the issue, provide any elucidating information that you can to help
 201   others solve the problem more effectively.
 202
 203 - find a way to resolve the problem or provide a workaround.
 204
 205 For help, instructions, and suggestions be in touch with the
 206 development community on the list or in the IRC channel for more
 207 information. With many eyes, all bugs are shallow.
 208
 209 How to Get Help with MediaGoblin
 210 ================================
 211
 212 The usual channels, the IRC channel, the listserv, the bug tracker,
 213 are all great ways to be in touch with us. Check the `web site <http://mediagoblin.org/pages/join.html>`_
 214 for more specific contact information.
 215