Hacking HOWTO
===============
+.. contents:: Sections
+ :local:
+
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
+<http://mediagoblin.org/join/>`_ where we list all the project
infrastructure including:
-* the mailing list
* the IRC channel
-* the bug tracker
+* 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 :ref:`codebase-chapter` where
+we've started documenting how GNU MediaGoblin is built and how to add
+new things.
+
+Third you'll need to :ref:`get the requirements
+<get-requirements-section>`.
+
+Fourth, you'll need to build a development environment. We use buildout,
+but if you want to use virtualenv, there's a set of mediocre not-very-supported
+steps in the `wiki <https://gitorious.org/mediagoblin/pages/Home>`_.
-How to set up and maintain an environment for hacking
-=====================================================
+.. _get-requirements-section:
Getting requirements
---------------------
+====================
First, you need to have the following installed before you can build
an environment for hacking on GNU MediaGoblin:
sudo apt-get install mongodb git-core python python-dev \
python-lxml
+.. YouCanHelp::
+
+ If you have instructions for other GNU/Linux distributions to set
+ up requirements, let us know!
+
+
+.. _hacking-with-buildout:
+
-Running bootstrap and buildout
-------------------------------
+How to set up and maintain an environment for hacking with buildout
+===================================================================
+
+**Requirements**
+
+No additional requirements.
+
+
+**Create a development environment**
After installing the requirements, follow these steps:
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
----------------------
+**Updating for dependency changes**
While hacking on GNU MediaGoblin over time, you'll eventually have to
-update your development environment. To do that, run::
+update your development environment because the dependencies have
+changed. To do that, run::
- ./bin/buildout
+ ./bin/buildout && ./bin/gmg migrate
-Wiping your environment for a clean-slate
------------------------------------------
+**Updating for code changes**
-.. Note::
+You don't need to do anything---code changes are automatically
+available.
- 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.
+**Deleting your buildout**
-Delete the following directories:
+At some point, you may want to delete your buildout. Perhaps it's to
+start over. Perhaps it's to test building development environments
+with buildout.
-* bin/
-* develop-eggs/
-* eggs/
-* mediagoblin.egg-info/
-* parts/
-* user_dev/
+To do this, do::
-FIXME - how to drop data from mongodb? we should probably write a
-script.
+ rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev
Running the server
==================
+If you want to get things running quickly and without hassle, just
+run::
+
+ ./lazyserver.sh
+
+This will start up a python server where you can begin playing with
+mediagoblin. It will also run celery in "always eager" mode so you
+don't have to start a separate process for it.
+
+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::
+
+ ./bin/paster serve paste.ini --reload
+
+
+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::
- ./bin/paster serve mediagoblin.ini --reload
+ CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd
Running the test suite
Run::
- ./bin/nosetests
+ ./runtests.sh
+
+Running a shell
+===============
+
+If you want a shell with your database pre-setup and an instantiated
+application ready and at your fingertips....
-What's where
-============
+Run::
-After you've run buildout, you're faced with the following directory
-tree::
+ ./bin/gmg shell
- 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
+Troubleshooting
+===============
+
+pymongo.errors.AutoReconnect: could not find master/primary
+-----------------------------------------------------------
+
+If you see this::
+
+ pymongo.errors.AutoReconnect: could not find master/primary
+
+then make sure mongodb is installed and running.
+
+If it's installed, check the mongodb log. On my machine, that's
+``/var/log/mongodb/mongodb.log``. If you see something like::
+
+ old lock file: /var/lib/mongodb/mongod.lock. probably means...
+
+Then delete the lock file and relaunch mongodb.
+
+
+Wiping your user data
+=====================
+
+.. 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.
+
+.. YouCanHelp::
+
+ If you're familiar with MongoDB, we'd love to get a `script that
+ removes all the GNU MediaGoblin data from an existing instance
+ <http://bugs.foocorp.net/issues/296>`_. Let us know!
Quickstart for Django programmers
=================================
-FIXME - write this
+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 mongokit ORM definitions
+* ``views.py`` is where the views go
+
+We're using MongoDB. Basically, instead of a relational database with
+tables, you have a big JSON structure which acts a lot like a Python
+dict.
+
+
+.. YouCanHelp::
+
+ If there are other things that you think would help orient someone
+ new to GNU MediaGoblin but coming from Django, let us know!
Bite-sized bugs to start with
=============================
-FIXME - write this
+**May 3rd, 2011**: We don't have a list of bite-sized bugs, yet, but
+this is important to us. If you're interested in things to work on,
+let us know on `the mailing list <http://mediagoblin.org/join/>`_ or
+on the `IRC channel <http://mediagoblin.org/join/>`_.
Tips for people new to coding
=============================
-Python
-------
+Learning Python
+---------------
GNU MediaGoblin is written using a programming language called `Python
<http://python.org/>`_.
These are all excellent texts.
-FIXME - are there good quality Python tutorial videos?
+.. YouCanHelp::
+ If you know of other good quality Python tutorials and Python
+ tutorial videos, let us know!
-Libraries
----------
+
+Learning Libraries GNU MediaGoblin uses
+---------------------------------------
GNU MediaGoblin uses a variety of libraries in order to do what it
-does. These libraries are listed in the :ref:`beardomatic-chapter`
+does. These libraries are listed in the :ref:`codebase-chapter`
along with links to the project Web sites and documentation for the
libraries.
If you have questions or need help, find us on the mailing list and on
IRC.
+
+
+.. _hacking-howto-git:
+
+Learning git
+------------
+
+git is an interesting and very powerful tool. Like all powerful
+tools, it has a learning curve.
+
+If you're new to git, we highly recommend the following resources for
+getting the hang of it:
+
+* `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub
+ intro to git
+* `Pro Git <http://progit.org/book/>`_ --- fantastic book
+* `Git casts <http://gitcasts.com/>`_ --- screencast covering git
+ usage
+* `Git Reference <http://gitref.org/>`_ --- Git reference that makes
+ it easier to get the hang of git if you're coming from other version
+ control systems
+
+There's also a git mission at `OpenHatch <http://openhatch.org/>`_.
+
+
+Learning other utilities
+------------------------
+
+The `OpenHatch <http://openhatch.org/>`_ site has a series of
+`training missions <http://openhatch.org/missions/>`_ which are
+designed to help you learn how to use these tools.
+
+If you're new to tar, diff, patch and git, we highly recommend you sign
+up with OpenHatch and do the missions.
projects / mediagoblin.git / blobdiff