X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fhackinghowto.rst;h=911f2340b3ad0d2de58cae40792667eb1e9ac4ed;hb=78c0744077b58fb4c20a965fdbbb52055922d793;hp=26267b7fa54526048d5febac4688e2fe1c876c8a;hpb=3dca2776a63886adcaac4bde188fb9ec8e74cfe2;p=mediagoblin.git diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 26267b7f..911f2340 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -4,28 +4,40 @@ Hacking HOWTO =============== +.. contents:: Sections + :local: + So you want to hack on GNU MediaGoblin? ======================================= First thing to do is check out the `Web site -`_ where we list all the project +`_ 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 +`. -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 `_. +.. _get-requirements-section: + Getting requirements --------------------- +==================== 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 +.. 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: @@ -67,53 +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. 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 @@ -121,45 +158,84 @@ Running the test suite 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 + `_. 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 `_ or +on the `IRC channel `_. Tips for people new to coding @@ -186,7 +262,10 @@ that are freely available on the Internet: 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 @@ -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 +There's also a git mission at `OpenHatch `_. + Learning other utilities ------------------------ @@ -236,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.