X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fhackinghowto.rst;h=911f2340b3ad0d2de58cae40792667eb1e9ac4ed;hb=78c0744077b58fb4c20a965fdbbb52055922d793;hp=ef49fc431c42655acb1f54d33cb2dac8b458e6a6;hpb=30d216aedce6d2b4696f2213c20c77dffae9b477;p=mediagoblin.git diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index ef49fc43..911f2340 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -4,6 +4,9 @@ Hacking HOWTO =============== +.. contents:: Sections + :local: + So you want to hack on GNU MediaGoblin? ======================================= @@ -23,13 +26,18 @@ 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 +`. + +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 `_. -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: @@ -49,9 +57,24 @@ requirements:: 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: @@ -71,36 +94,63 @@ session stuff, etc). You can change this, but for development purposes this default should be fine. -.. Note:: - - We used `zc.buildout `_ because it - involves fewer steps to get things running and less knowledge of - Python packaging. However, if you prefer to use `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 because the dependencies have changed. To do that, run:: - ./bin/buildout + ./bin/buildout && ./bin/gmg migrate -.. Note:: - You only need to do this when dependencies are updated. You don't - need to do this when you've made code changes. +**Updating for code changes** + +You don't need to do anything---code changes are automatically +available. + + +**Deleting your buildout** + +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. + +To do this, do:: + + 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 @@ -108,34 +158,54 @@ Running the test suite Run:: - ./bin/nosetests + ./runtests.sh -Wiping your environment for a clean-slate ------------------------------------------ +Running a shell +=============== -.. Note:: +If you want a shell with your database pre-setup and an instantiated +application ready and at your fingertips.... - 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. +Run:: + + ./bin/gmg shell + + +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. -Delete the following directories: +If it's installed, check the mongodb log. On my machine, that's +``/var/log/mongodb/mongodb.log``. If you see something like:: -* bin/ -* develop-eggs/ -* eggs/ -* mediagoblin.egg-info/ -* parts/ -* user_dev/ + 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 and bash, we'd love to get a - `script that removes all the GNU MediaGoblin data from an existing - instance `_. Let us know! + If you're familiar with MongoDB, we'd love to get a `script that + removes all the GNU MediaGoblin data from an existing instance + `_. Let us know! Quickstart for Django programmers @@ -237,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 +There's also a git mission at `OpenHatch `_. + Learning other utilities ------------------------ @@ -245,5 +317,5 @@ The `OpenHatch `_ site has a series of `training 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.