+.. _hacking-howto:
+
===============
Hacking HOWTO
===============
-So you want to hack on GNU MediaGoblin
-======================================
-First thing to do is check out the Web site where we list all the
-project infrastructure including:
+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
to, what needs to be worked on, and other things besides!
-How to set up an environment for hacking
-========================================
+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::
-The following assumes you have these things installed:
+ sudo apt-get install mongodb git-core python python-dev \
+ python-lxml
-1. virtualenv:
- http://pypi.python.org/pypi/virtualenv
+Running bootstrap and buildout
+------------------------------
-2. virtualenv wrapper:
+After installing the requirements, follow these steps:
- http://www.doughellmann.com/projects/virtualenvwrapper/
+1. Clone the repository::
-3. git:
+ git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
- http://git-scm.com/
+2. Bootstrap and run buildout::
+ cd mediagoblin
+ python bootstrap.py && ./bin/buildout
-Follow these steps:
-1. clone the repository::
+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.
- git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
-2. create a virtual environment::
+.. Note::
- mkvirtualenv mediagoblin
+ 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.
-3. if that doesn't put you in the virtual environment you created,
- then do::
- workon mediagoblin
+Updating dependencies
+---------------------
-4. run::
+While hacking on GNU MediaGoblin over time, you'll eventually have to
+update your development environment. To do that, run::
- python setup.py develop
+ ./bin/buildout
-When you want to work on GNU MediaGoblin, make sure to enter your
-virtual environment::
+Wiping your environment for a clean-slate
+-----------------------------------------
- workon mediagoblin
+.. 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::
-Any changes you make to the code will show up in your virtual
-environment--there's no need to continuously run ``python setup.py
-develop``.
+ ./bin/paster serve mediagoblin.ini --reload
Running the test suite
Run::
- python setup.py test
+ ./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>`_
-Creating a new file
-===================
+These are all excellent texts.
-All new files need to have license/copyright information.
+FIXME - are there good quality Python tutorial videos?
-The following kinds of files get the GNU AGPL header:
-* Python files
-* JavaScript files
-* templates
-* other files with code in them
+Libraries
+---------
-The following files get a CC BY header:
+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.
-* CSS files
+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]_.
-The following files don't get a header because that's hard, but are
-under the CC BY license:
+.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro
+ Community.
-* image files
-* video files
+If you have questions or need help, find us on the mailing list and on
+IRC.
projects / mediagoblin.git / blobdiff