docs/hackinghowto.rst

   1 .. _hacking-howto:
   2
   3 ===============
   4  Hacking HOWTO
   5 ===============
   6
   7
   8 So you want to hack on GNU MediaGoblin?
   9 =======================================
  10
  11 First thing to do is check out the `Web site
  12 <http://mediagoblin.org>`_ where we list all the project
  13 infrastructure including:
  14
  15 * the mailing list
  16 * the IRC channel
  17 * the bug tracker
  18
  19 Additionally, we have information on how to get involved, who to talk
  20 to, what needs to be worked on, and other things besides!
  21
  22
  23 How to set up and maintain an environment for hacking
  24 =====================================================
  25
  26
  27 Getting requirements
  28 --------------------
  29
  30 First, you need to have the following installed before you can build
  31 an environment for hacking on GNU MediaGoblin:
  32
  33 * Python 2.6 or 2.7  - http://www.python.org/
  34
  35   You'll need Python as well as the dev files for building modules.
  36
  37 * python-lxml        - http://lxml.de/
  38 * git                - http://git-scm.com/
  39 * MongoDB            - http://www.mongodb.org/
  40
  41 If you're running Debian GNU/Linux or a Debian-derived distribution
  42 such as Mint or Ubuntu, running the following should install these
  43 requirements::
  44
  45     sudo apt-get install mongodb git-core python python-dev \
  46          python-lxml
  47
  48
  49 Running bootstrap and buildout
  50 ------------------------------
  51
  52 After installing the requirements, follow these steps:
  53
  54 1. Clone the repository::
  55
  56        git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
  57
  58 2. Bootstrap and run buildout::
  59
  60        cd mediagoblin
  61        python bootstrap.py && ./bin/buildout
  62
  63
  64 That's it!  Using this method, buildout should create a ``user_dev``
  65 directory, in which certain things will be stored (media, beaker
  66 session stuff, etc).  You can change this, but for development
  67 purposes this default should be fine.
  68
  69
  70 .. Note::
  71
  72    We used `zc.buildout <http://www.buildout.org/>`_ because it
  73    involves fewer steps to get things running and less knowledge of
  74    Python packaging.  However, if you prefer to use `virtualenv
  75    <http://pypi.python.org/pypi/virtualenv>`_, that should work just
  76    fine.
  77
  78
  79 Updating dependencies
  80 ---------------------
  81
  82 While hacking on GNU MediaGoblin over time, you'll eventually have to
  83 update your development environment.  To do that, run::
  84
  85     ./bin/buildout
  86
  87
  88 Wiping your environment for a clean-slate
  89 -----------------------------------------
  90
  91 .. Note::
  92
  93    Unless you're doing development and working on and testing creating
  94    a new instance, you will probably never have to do this.  Will
  95    plans to do this work and thus he documented it.
  96
  97
  98 Delete the following directories:
  99
 100 * bin/
 101 * develop-eggs/
 102 * eggs/
 103 * mediagoblin.egg-info/
 104 * parts/
 105 * user_dev/
 106
 107 FIXME - how to drop data from mongodb?  we should probably write a
 108 script.
 109
 110
 111 Running the server
 112 ==================
 113
 114 Run::
 115
 116     ./bin/paster serve mediagoblin.ini --reload
 117
 118
 119 Running the test suite
 120 ======================
 121
 122 Run::
 123
 124     ./bin/nosetests
 125
 126
 127 What's where
 128 ============
 129
 130 After you've run buildout, you're faced with the following directory
 131 tree::
 132
 133     mediagoblin/
 134     |- mediagoblin/              source code
 135     |  |- tests/
 136     |  |- templates/
 137     |  |- auth/
 138     |  \- submit/
 139     |- docs/                     documentation
 140     |
 141     |        the rest of these directories are generated by
 142     |        buildout.
 143     |
 144     |- bin/                      scripts
 145     |- develop-eggs/
 146     |- eggs/
 147     |- mediagoblin.egg-info/
 148     |- parts/
 149     |- user_dev/                 sessions, etc
 150
 151
 152
 153 Quickstart for Django programmers
 154 =================================
 155
 156 FIXME - write this
 157
 158
 159 Bite-sized bugs to start with
 160 =============================
 161
 162 FIXME - write this
 163
 164
 165 Tips for people new to coding
 166 =============================
 167
 168 Learning Python
 169 ---------------
 170
 171 GNU MediaGoblin is written using a programming language called `Python
 172 <http://python.org/>`_.
 173
 174 There are two different incompatible iterations of Python which I'll
 175 refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
 176 Python 2 and requires Python 2.6 or 2.7.  At some point, we might
 177 switch to Python 3, but that's a future thing.
 178
 179 You can learn how to code in Python 2 from several excellent books
 180 that are freely available on the Internet:
 181
 182 * `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
 183 * `Dive Into Pyton <http://diveintopython.org/>`_
 184 * `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
 185 * `A Byte of Python <http://www.swaroopch.com/notes/Python>`_
 186
 187 These are all excellent texts.
 188
 189 FIXME - are there good quality Python tutorial videos?
 190
 191
 192 Learning Libraries GNU MediaGoblin uses
 193 ---------------------------------------
 194
 195 GNU MediaGoblin uses a variety of libraries in order to do what it
 196 does.  These libraries are listed in the :ref:`beardomatic-chapter`
 197 along with links to the project Web sites and documentation for the
 198 libraries.
 199
 200 There are a variety of Python-related conferences every year that have
 201 sessions covering many aspects of these libraries.  You can find them
 202 at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.
 203
 204 .. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
 205    Community.
 206
 207 If you have questions or need help, find us on the mailing list and on
 208 IRC.
 209
 210
 211 .. _hacking-howto-git:
 212
 213 Learning git
 214 ------------
 215
 216 git is an interesting and very powerful tool.  Like all powerful
 217 tools, it has a learning curve.
 218
 219 If you're new to git, we highly recommend the following resources for
 220 getting the hang of it:
 221
 222 * `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub
 223   intro to git
 224 * `Pro Git <http://progit.org/book/>`_ --- fantastic book
 225 * `Git casts <http://gitcasts.com/>`_ --- screencast covering git
 226   usage
 227 * `Git Reference <http://gitref.org/>`_ --- Git reference that makes
 228   it easier to get the hang of git if you're coming from other version
 229   control systems
 230
 231
 232 Learning other utilities
 233 ------------------------
 234
 235 The `OpenHatch <http://openhatch.org/>`_ site has a series of
 236 `training missions <http://openhatch.org/missions/>`_ which are
 237 designed to help you learn how to use these tools.
 238
 239 If you're new to tar, diff and patch, we highly recommend you sign up
 240 with OpenHatch and do the missions.