Merge branch 'master' into celerysubmit

[mediagoblin.git] / docs / hackinghowto.rst

.. _hacking-howto:

===============
 Hacking HOWTO
===============


So you want to hack on GNU MediaGoblin?
=======================================

First thing to do is check out the `Web site
<http://mediagoblin.org>`_ where we list all the project
infrastructure including:

* the mailing list
* the IRC channel
* the bug tracker

Additionally, we have information on how to get involved, who to talk
to, what needs to be worked on, and other things besides!


How to set up and maintain an environment for hacking
=====================================================


Getting requirements
--------------------

First, you need to have the following installed before you can build
an environment for hacking on GNU MediaGoblin:

* Python 2.6 or 2.7  - http://www.python.org/

  You'll need Python as well as the dev files for building modules.

* python-lxml        - http://lxml.de/
* git                - http://git-scm.com/
* MongoDB            - http://www.mongodb.org/

If you're running Debian GNU/Linux or a Debian-derived distribution
such as Mint or Ubuntu, running the following should install these
requirements::

    sudo apt-get install mongodb git-core python python-dev \
         python-lxml


Running bootstrap and buildout
------------------------------

After installing the requirements, follow these steps:

1. Clone the repository::

       git clone http://git.gitorious.org/mediagoblin/mediagoblin.git

2. Bootstrap and run buildout::

       cd mediagoblin
       python bootstrap.py && ./bin/buildout


That's it!  Using this method, buildout should create a ``user_dev``
directory, in which certain things will be stored (media, beaker
session stuff, etc).  You can change this, but for development
purposes this default should be fine.


.. Note::

   We used `zc.buildout <http://www.buildout.org/>`_ because it
   involves fewer steps to get things running and less knowledge of
   Python packaging.  However, if you prefer to use `virtualenv
   <http://pypi.python.org/pypi/virtualenv>`_, that should work just
   fine.


Updating dependencies
---------------------

While hacking on GNU MediaGoblin over time, you'll eventually have to
update your development environment.  To do that, run::

    ./bin/buildout


Wiping your environment for a clean-slate
-----------------------------------------

.. Note::

   Unless you're doing development and working on and testing creating
   a new instance, you will probably never have to do this.  Will
   plans to do this work and thus he documented it.


Delete the following directories:

* bin/
* develop-eggs/
* eggs/
* mediagoblin.egg-info/
* parts/
* user_dev/

FIXME - how to drop data from mongodb?  we should probably write a
script.


Running the server
==================

Run::

    ./bin/paster serve mediagoblin.ini --reload


Running the test suite
======================

Run::

    ./bin/nosetests


What's where
============

After you've run buildout, you're faced with the following directory
tree::

    mediagoblin/
    |- mediagoblin/              source code
    |  |- tests/
    |  |- templates/
    |  |- auth/
    |  \- submit/
    |- docs/                     documentation
    |
    |        the rest of these directories are generated by
    |        buildout.
    |
    |- bin/                      scripts
    |- develop-eggs/
    |- eggs/
    |- mediagoblin.egg-info/
    |- parts/
    |- user_dev/                 sessions, etc



Quickstart for Django programmers
=================================

FIXME - write this


Bite-sized bugs to start with
=============================

FIXME - write this


Tips for people new to coding
=============================

Python
------

GNU MediaGoblin is written using a programming language called `Python
<http://python.org/>`_.

There are two different incompatible iterations of Python which I'll
refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
Python 2 and requires Python 2.6 or 2.7.  At some point, we might
switch to Python 3, but that's a future thing.

You can learn how to code in Python 2 from several excellent books
that are freely available on the Internet:

* `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
* `Dive Into Pyton <http://diveintopython.org/>`_
* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
* `A Byte of Python <http://www.swaroopch.com/notes/Python>`_

These are all excellent texts.

FIXME - are there good quality Python tutorial videos?


Libraries
---------

GNU MediaGoblin uses a variety of libraries in order to do what it
does.  These libraries are listed in the :ref:`beardomatic-chapter`
along with links to the project Web sites and documentation for the
libraries.

There are a variety of Python-related conferences every year that have
sessions covering many aspects of these libraries.  You can find them
at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.

.. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
   Community.

If you have questions or need help, find us on the mailing list and on
IRC.