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 where we list all the
  12 project infrastructure including:
  13
  14 * the mailing list
  15 * the IRC channel
  16 * the bug tracker
  17
  18 Additionally, we have information on how to get involved, who to talk
  19 to, what needs to be worked on, and other things besides!
  20
  21
  22 How to set up and maintain an environment for hacking
  23 =====================================================
  24
  25
  26 Getting requirements
  27 --------------------
  28
  29 First, you need to have the following installed before you can build
  30 an environment for hacking on GNU MediaGoblin:
  31
  32 * Python 2.6 or 2.7  - http://www.python.org/
  33
  34   You'll need Python as well as the dev files for building modules.
  35
  36 * python-lxml        - http://lxml.de/
  37 * git                - http://git-scm.com/
  38 * MongoDB            - http://www.mongodb.org/
  39
  40 If you're running Debian GNU/Linux or a Debian-derived distribution
  41 such as Mint or Ubuntu, running the following should install these
  42 requirements::
  43
  44     sudo apt-get install mongodb git-core python python-dev \
  45          python-lxml
  46
  47
  48 Running bootstrap and buildout
  49 ------------------------------
  50
  51 After installing the requirements, follow these steps:
  52
  53 1. Clone the repository::
  54
  55        git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
  56
  57 2. Bootstrap and run buildout::
  58
  59        cd mediagoblin
  60        python bootstrap.py && ./bin/buildout
  61
  62
  63 That's it!  Using this method, buildout should create a ``user_dev``
  64 directory, in which certain things will be stored (media, beaker
  65 session stuff, etc).  You can change this, but for development
  66 purposes this default should be fine.
  67
  68
  69 .. Note::
  70
  71    We used `zc.buildout <http://www.buildout.org/>`_ because it
  72    involves fewer steps to get things running and less knowledge of
  73    Python packaging.  However, if you prefer to use `virtualenv
  74    <http://pypi.python.org/pypi/virtualenv>`_, that should work just
  75    fine.
  76
  77
  78 Updating dependencies
  79 ---------------------
  80
  81 While hacking on GNU MediaGoblin over time, you'll eventually have to
  82 update your development environment.  To do that, run::
  83
  84     ./bin/buildout
  85
  86
  87 Wiping your environment for a clean-slate
  88 -----------------------------------------
  89
  90 Delete the following directories:
  91
  92 * bin/
  93 * develop-eggs/
  94 * eggs/
  95 * mediagoblin.egg-info/
  96 * parts/
  97 * user_dev/
  98
  99 FIXME - how to drop data from mongodb?
 100
 101
 102 Running the server
 103 ==================
 104
 105 Run::
 106
 107     ./bin/paster serve mediagoblin.ini --reload
 108
 109
 110 Running the test suite
 111 ======================
 112
 113 Run::
 114
 115     ./bin/nosetests
 116
 117
 118 What's where
 119 ============
 120
 121 After you've run buildout, you're faced with the following directory
 122 tree::
 123
 124     mediagoblin/
 125     |- mediagoblin/              source code
 126     |  |- tests/
 127     |  |- templates/
 128     |  |- auth/
 129     |  \- submit/
 130     |- docs/                     documentation
 131     |
 132     |        the rest of these directories are generated by
 133     |        buildout.
 134     |
 135     |- bin/                      scripts
 136     |- develop-eggs/
 137     |- eggs/
 138     |- mediagoblin.egg-info/
 139     |- parts/
 140     |- user_dev/                 sessions, etc
 141
 142
 143
 144 Quickstart for Django programmers
 145 =================================
 146
 147 FIXME - write this
 148
 149
 150 Bite-sized bugs to start with
 151 =============================
 152
 153 FIXME - write this