9d952fdc79
I chatted with Asheesh on IRC today and asked him to look over the contributer howto. He had a lot of thoughts and I factored most/all of them in. It's much better now.
209 lines
5.0 KiB
ReStructuredText
209 lines
5.0 KiB
ReStructuredText
.. _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.
|