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/join/>`_ where we list all the project
  13 infrastructure including:
  14
  15 * the IRC channel
  16 * the mailing list
  17 * the issue 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 Second thing to do is take a look at :ref:`codebase-chapter` where
  23 we've started documenting how GNU MediaGoblin is built and how to add
  24 new things.
  25
  26
  27 How to set up and maintain an environment for hacking
  28 =====================================================
  29
  30
  31 Getting requirements
  32 --------------------
  33
  34 First, you need to have the following installed before you can build
  35 an environment for hacking on GNU MediaGoblin:
  36
  37 * Python 2.6 or 2.7  - http://www.python.org/
  38
  39   You'll need Python as well as the dev files for building modules.
  40
  41 * python-lxml        - http://lxml.de/
  42 * git                - http://git-scm.com/
  43 * MongoDB            - http://www.mongodb.org/
  44
  45 If you're running Debian GNU/Linux or a Debian-derived distribution
  46 such as Mint or Ubuntu, running the following should install these
  47 requirements::
  48
  49     sudo apt-get install mongodb git-core python python-dev \
  50          python-lxml
  51
  52 After getting the requirements, there are two ways to build a development environment:
  53
  54 1. Running bootstrap and buildout, OR
  55 2. Creating a virtual environment
  56
  57 Pick one---don't do both!
  58
  59
  60 Creating a dev environment with bootstrap and buildout
  61 ------------------------------------------------------
  62
  63 .. Note::
  64
  65    Either follow the instructions in this section OR follow the ones
  66    in the next one---don't do both!
  67
  68
  69 After installing the requirements, follow these steps:
  70
  71 1. Clone the repository::
  72
  73        git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
  74
  75 2. Bootstrap and run buildout::
  76
  77        cd mediagoblin
  78        python bootstrap.py && ./bin/buildout
  79
  80
  81 That's it!  Using this method, buildout should create a ``user_dev``
  82 directory, in which certain things will be stored (media, beaker
  83 session stuff, etc).  You can change this, but for development
  84 purposes this default should be fine.
  85
  86
  87 .. Note::
  88
  89    We used `zc.buildout <http://www.buildout.org/>`_ because it
  90    involves fewer steps to get things running and less knowledge of
  91    Python packaging.  However, if you prefer to use `virtualenv
  92    <http://pypi.python.org/pypi/virtualenv>`_, that should work just
  93    fine.
  94
  95 While hacking on GNU MediaGoblin over time, you'll eventually have to
  96 update your development environment because the dependencies have
  97 changed.  To do that, run::
  98
  99     ./bin/buildout
 100
 101 .. Note::
 102
 103     You only need to do this when dependencies are updated.  You don't
 104     need to do this when you've made code changes.
 105
 106
 107 Creating a dev environment with virtualenv
 108 ------------------------------------------
 109
 110 .. Note::
 111
 112    Either follow the instructions in this section OR follow the ones
 113    in the previous one---don't do both!
 114
 115 The following assumes you have these things installed:
 116
 117 1. virtualenv:
 118
 119    http://pypi.python.org/pypi/virtualenv
 120
 121 2. virtualenv wrapper:
 122
 123    http://www.doughellmann.com/projects/virtualenvwrapper/
 124
 125 3. git:
 126
 127    http://git-scm.com/
 128
 129
 130 Follow these steps:
 131
 132 1. Clone the repository::
 133
 134        git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
 135
 136 2. Create a virtual environment::
 137
 138        mkvirtualenv --no-site-packages mediagoblin
 139
 140 3. If that doesn't put you in the virutal environment you just created, then do::
 141
 142        workon mediagoblin
 143
 144 4. Run::
 145
 146        python setup.py develop
 147
 148
 149 That's it!
 150
 151 When you want to work on GNU MediaGoblin, you need to activate the
 152 virtual environment like this::
 153
 154     workon mediagoblin
 155
 156 If you want to deactivate it, you can do this::
 157
 158     deactivate
 159
 160 .. Note::
 161
 162    You don't have to do anything additional to move changes you're
 163    making to your virtual environment because the virtual environment
 164    is pointing at the actual code files.
 165
 166
 167 Running the server
 168 ==================
 169
 170 Run::
 171
 172     ./bin/paster serve mediagoblin.ini --reload
 173
 174
 175 Running celeryd
 176 ===============
 177
 178 You need to do this if you want your media to process and actually
 179 show up.  It's probably a good idea in development to have the web
 180 server (above) running in one terminal and celeryd in another window.
 181
 182 Run::
 183
 184     CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd
 185
 186
 187 Running the test suite
 188 ======================
 189
 190 Run::
 191
 192     ./bin/nosetests
 193
 194
 195 Wiping your environment for a clean-slate
 196 -----------------------------------------
 197
 198 .. Note::
 199
 200    Unless you're doing development and working on and testing creating
 201    a new instance, you will probably never have to do this.  Will
 202    plans to do this work and thus he documented it.
 203
 204
 205 Delete the following directories:
 206
 207 * bin/
 208 * develop-eggs/
 209 * eggs/
 210 * mediagoblin.egg-info/
 211 * parts/
 212 * user_dev/
 213
 214
 215 .. YouCanHelp::
 216
 217    If you're familiar with MongoDB, we'd love to get a `script that
 218    removes all the GNU MediaGoblin data from an existing instance
 219    <http://bugs.foocorp.net/issues/296>`_.  Let us know!
 220
 221
 222 Quickstart for Django programmers
 223 =================================
 224
 225 We're not using Django, but the codebase is very Django-like in its
 226 structure.
 227
 228 * ``routing.py`` is like ``urls.py`` in Django
 229 * ``models.py`` has mongokit ORM definitions
 230 * ``views.py`` is where the views go
 231
 232 We're using MongoDB.  Basically, instead of a relational database with
 233 tables, you have a big JSON structure which acts a lot like a Python
 234 dict.
 235
 236
 237 .. YouCanHelp::
 238
 239    If there are other things that you think would help orient someone
 240    new to GNU MediaGoblin but coming from Django, let us know!
 241
 242
 243 Bite-sized bugs to start with
 244 =============================
 245
 246 **May 3rd, 2011**:  We don't have a list of bite-sized bugs, yet, but
 247 this is important to us.  If you're interested in things to work on,
 248 let us know on `the mailing list <http://mediagoblin.org/join/>`_ or
 249 on the `IRC channel <http://mediagoblin.org/join/>`_.
 250
 251
 252 Tips for people new to coding
 253 =============================
 254
 255 Learning Python
 256 ---------------
 257
 258 GNU MediaGoblin is written using a programming language called `Python
 259 <http://python.org/>`_.
 260
 261 There are two different incompatible iterations of Python which I'll
 262 refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
 263 Python 2 and requires Python 2.6 or 2.7.  At some point, we might
 264 switch to Python 3, but that's a future thing.
 265
 266 You can learn how to code in Python 2 from several excellent books
 267 that are freely available on the Internet:
 268
 269 * `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
 270 * `Dive Into Pyton <http://diveintopython.org/>`_
 271 * `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
 272 * `A Byte of Python <http://www.swaroopch.com/notes/Python>`_
 273
 274 These are all excellent texts.
 275
 276 .. YouCanHelp::
 277
 278    If you know of other good quality Python tutorials and Python
 279    tutorial videos, let us know!
 280
 281
 282 Learning Libraries GNU MediaGoblin uses
 283 ---------------------------------------
 284
 285 GNU MediaGoblin uses a variety of libraries in order to do what it
 286 does.  These libraries are listed in the :ref:`codebase-chapter`
 287 along with links to the project Web sites and documentation for the
 288 libraries.
 289
 290 There are a variety of Python-related conferences every year that have
 291 sessions covering many aspects of these libraries.  You can find them
 292 at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.
 293
 294 .. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
 295    Community.
 296
 297 If you have questions or need help, find us on the mailing list and on
 298 IRC.
 299
 300
 301 .. _hacking-howto-git:
 302
 303 Learning git
 304 ------------
 305
 306 git is an interesting and very powerful tool.  Like all powerful
 307 tools, it has a learning curve.
 308
 309 If you're new to git, we highly recommend the following resources for
 310 getting the hang of it:
 311
 312 * `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub
 313   intro to git
 314 * `Pro Git <http://progit.org/book/>`_ --- fantastic book
 315 * `Git casts <http://gitcasts.com/>`_ --- screencast covering git
 316   usage
 317 * `Git Reference <http://gitref.org/>`_ --- Git reference that makes
 318   it easier to get the hang of git if you're coming from other version
 319   control systems
 320
 321
 322 Learning other utilities
 323 ------------------------
 324
 325 The `OpenHatch <http://openhatch.org/>`_ site has a series of
 326 `training missions <http://openhatch.org/missions/>`_ which are
 327 designed to help you learn how to use these tools.
 328
 329 If you're new to tar, diff and patch, we highly recommend you sign up
 330 with OpenHatch and do the missions.