Merge remote-tracking branch 'origin/master' into is315

[mediagoblin.git] / docs / hackinghowto.rst

diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst
index 26267b7fa54526048d5febac4688e2fe1c876c8a..911f2340b3ad0d2de58cae40792667eb1e9ac4ed 100644 (file)
--- a/docs/hackinghowto.rst
+++ b/docs/hackinghowto.rst
@@ -4,28 +4,40 @@
  Hacking HOWTO
 ===============
 
  Hacking HOWTO
 ===============
 

+.. contents:: Sections
+   :local:
+

 
 So you want to hack on GNU MediaGoblin?
 =======================================
 
 First thing to do is check out the `Web site
 
 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:
 
 infrastructure including:
 

-* the mailing list

 * the IRC channel
 * 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!
 
 
 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>`.

 
 

-How to set up and maintain an environment for hacking
-=====================================================
+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>`_.

 
 
 
 

+.. _get-requirements-section:
+

 Getting requirements
 Getting requirements

---------------------
+====================

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


@@ -45,9 +57,24 @@ requirements::
     sudo apt-get install mongodb git-core python python-dev \
          python-lxml
 
     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:
 
 
 After installing the requirements, follow these steps:
 


@@ -67,53 +94,63 @@ session stuff, etc).  You can change this, but for development
 purposes this default should be fine.
 
 
 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
 
 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
 ==================
 
 
 
 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::
 
 Run::
 

-    ./bin/paster serve mediagoblin.ini --reload
+    CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd

 
 
 Running the test suite
 
 
 Running the test suite


@@ -121,45 +158,84 @@ Running the test suite
 
 Run::
 
 
 Run::
 

-    ./bin/nosetests
+    ./runtests.sh

 
 
 
 

-What's where
-============
+Running a shell
+===============
+
+If you want a shell with your database pre-setup and an instantiated
+application ready and at your fingertips....
+
+Run::
+
+    ./bin/gmg shell
+
+
+Troubleshooting
+===============

 
 

-After you've run buildout, you're faced with the following directory
-tree::
+pymongo.errors.AutoReconnect: could not find master/primary
+-----------------------------------------------------------

 
 

-    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
+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
 =================================
 
 
 
 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
 =============================
 
 
 
 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
 
 
 Tips for people new to coding


@@ -186,7 +262,10 @@ that are freely available on the Internet:
 
 These are all excellent texts.
 
 
 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!

 
 
 Learning Libraries GNU MediaGoblin uses
 
 
 Learning Libraries GNU MediaGoblin uses


@@ -228,6 +307,8 @@ getting the hang of it:
   it easier to get the hang of git if you're coming from other version
   control systems
 
   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
 ------------------------
 
 Learning other utilities
 ------------------------


@@ -236,5 +317,5 @@ 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.
 
 `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 and patch, we highly recommend you sign up
-with OpenHatch and do the missions.
+If you're new to tar, diff, patch and git, we highly recommend you sign
+up with OpenHatch and do the missions.