HackingHowto

= 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:


 * the IRC channel
 * the mailing list
 * the issue tracker

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

Second thing to do is take a look at codebase chapter where we've started documenting how GNU MediaGoblin is built and how to add new things. If you're planning on contributing in python, you should be aware of PEP-8, the official Python style guide, which we follow.

Third you'll need to get the requirements.

Fourth, you'll need to build a development environment. We use an in-package checkout of virtualenv. This isn't the convenional way to install virtualenv (normally you don't install virtualenv inside the package itself) but we've found that it's significantly easier for newcomers who aren't already familiar with virtualenv. If you *are* already familiar with virtualenv, feel free to just install mediagoblin in your own virtualenv setup... the necessary adjustments should be obvious.

Python 2 vs Python 3
GNU MediaGoblin was originally written for Python 2, and much of the documentation on the wiki reflects that. However, since release v0.9.0, GNU MediaGoblin has attempted to provide support for Python 3. Unfortunately, not everything is working for Python 3 environments yet. Below is a non-exhaustive list of things that might not work if you set up GNU MediaGoblin a Python 3 environment.

Python 3 Issues

 * fcgi - none of the flup packages (flup, flup-py3, flup6) appear to have proper support for Python 3.5.
 * audio file spectrographs - scikits.audiolab appears to not work in Python 3.
 * Rackspace storage - the cloudfiles plugin may not work with Python 3.

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


 * Python 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/
 * SQLAlchemy 0.7.0 or higher  - http://www.sqlalchemy.org/
 * Pillow - http://python-pillow.org/
 * virtualenv        - http://www.virtualenv.org/
 * Python GStreamer Bindings - http://gstreamer.freedesktop.org/modules/gst-python.html
 * Node.js
 * RabbitMQ server

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

On CentOS7:
epel-release is the prerequisite for most of the below listed packages

for video to work correctly (as per Enabling Media-Types Video) you may choose to install AWEL 3rd party repo which provides with the latest gstreamer bindings and more:


 * AWEL Repo,AWEL Gstreamer

once installed:

openSUSE
This instructions might be incomplete. Try on openSUSE 13.2 or 13.1:

ArchLinux / Parabola
The following command should work ( not tested on a new ArchLinux / Parabola install . tested, it works):

Mac OS X Lion
Download the Newest Python.

Git is already installed.


 * Note for Pillow and lxml, you can: pip install Pillow lxml

Python-lxml: http://muffinresearch.co.uk/archives/2009/03/05/install-lxml-on-osx/ with sudo

Pillow: http://pillow.readthedocs.org/en/3.0.x/installation.html#os-x-installation

Libjpeg & Libpng: http://ethan.tira-thompson.com/Mac_OS_X_Ports.html Combo Installer

Mac OS X Snow Leopard

 * 1) You will probably want to install MacPorts this will give you access to many free software packages in the same manner to apt-get and yum: https://www.macports.org/install.php
 * 2) Ensure you install Git and the command line tools: https://help.github.com/articles/set-up-git#platform-mac
 * 3) Once both of those are installed type this in your terminal and enter your password when prompted for it

Microsoft Windows
Thanks wctype!

Getting requirements

 * Python 2.7 -  Download
 * git - Download
 * python-lxml - Tarball Binaries
 * Pillow - Download
 * virtualenv - Download
 * OSSBuild project provides reasonably up-to-date binaries of GStreamer - Download
 * py-bcrypt - Download
 * Node JS

You can help:

If you have instructions for other GNU/Linux distributions, Windows, or Mac OS X to set up requirements, let us know!

How to set up and maintain an environment for hacking with virtualenv
Requirements

No additional requirements.

Create a development environment

After installing the requirements, follow these steps:


 * Clone the repository:
 * Make the environment:
 * If you want to use audio or video, this is the time to add the appropriate plugins to mediagoblin.ini
 * Init the database:

That's it!

If you want to make sure things are working, consider running the test suite:

(If you have troubles in the remaining steps, consider try installing virtualenv with one of the flags --setuptools, --distribute or possibly --no-site-packages. Additionally, if your system has python3.X as the default, you might need to do virtualenv --python=python2.7 or --python=python2.6)

If you have problems, please let us know!

Updating an existing environment
Updating for dependency changes

While hacking on GNU MediaGoblin over time, you'll eventually have to update your development environment because the dependencies have changed.

To do that, run:

Updating for code changes

NOTE: MediaGoblin used to be hosted on gitorious.org, but that is moving to read-only mode, so we're now on Savannah. If you have an old checkout, please update it by running the following:

Running the server
If you want to get things running quickly and without hassle, just run:

This will start up a python server where you can begin playing with mediagoblin, listening on 127.0.0.1:6543. It will also run celery in "always eager" mode so you don't have to start a separate process for it.

By default, the instance is not sending out confirmation mails. Instead they are redirected to the standard output (the console) of lazyserver.sh.

You can change this behavior setting  to   in mediagoblin.ini

This is fine in development, but if you want to actually run celery separately for testing (or deployment purposes), you'll want to run the server independently:

Running celeryd
If you aren't using ./lazyserver.sh or otherwise aren't running celery in always eager mode, you'll need to do this if you want your media to process and actually show up. It's probably a good idea in development to have the web server (above) running in one terminal and celeryd in another window.

Run:

Running the test suite
See also UnitTests and Manual Functional Testing.

Run:

Running a shell
If you want a shell with your database pre-setup and an instantiated application ready and at your fingertips ......

Run:

Troubleshooting
If you see a python error, search for the full line in trac to find issues that mention the same. If it has not been fixed, you can update corresponding bug reports or open a new one.

For developers it is a special pleasure to test and apply user submitted patches. Here is a good minimal git workflow as example.

Wiping your user data
You can completely wipe all data from the instance by doing:

Note:

Unless you're doing development and working on and testing creating a new instance, you will probably never have to do this.

Quickstart for Django programmers
We're not using Django, but the codebase is very Django-like in its structure.


 * routing.py is like urls.py in Django
 * models.py has SQLAlchemy ORM definitions
 * views.py is where the views go

We're using SQLAlchemy, which is semi-similar to the Django ORM, but not really because you can get a lot more fine-grained. The SQLAlchemy ORM tutorial is a great place to start.

YouCanHelp

If there are other things that you think would help orient someone new to GNU MediaGoblin but coming from Django, let us know!

Showing off your work with PageKite
If you're doing development with MediaGoblin, it's sometimes helpful to show off your work to gather feedback from other contributors. A number of the MediaGoblin developers use something called PageKite, which is a fellow free software web service which makes temporarily showing off work on your machine easy. There's a tutorial on how to use PageKite and MediaGoblin together available on the PageKite wiki.

If you are doing a lot of MediaGoblin development, the PageKite people have graciously offered us a good amount of bandwidth at no cost in an effort to help out fellow free software projects. If you've been making significant contributions, PM Chris Webber on freenode (who is paroneayea there) and ask if you can be added to our group plan.

Bite-sized bugs to start with
Now you should visit our latest list of bite-sized issues because squishing bugs is messy fun. If you're interested in other things to work on, or need help getting started on a bug, let us know on the mailing list or on the IRC channel.