X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=docs%2Fhackinghowto.rst;h=911f2340b3ad0d2de58cae40792667eb1e9ac4ed;hb=78c0744077b58fb4c20a965fdbbb52055922d793;hp=8356f43586c915b9f4ec91882417b522f7fafb46;hpb=56d507b60bf2393dbeed8b81524b6b922dbc6ad0;p=mediagoblin.git diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 8356f435..911f2340 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -1,67 +1,156 @@ +.. _hacking-howto: + =============== Hacking HOWTO =============== -So you want to hack on GNU MediaGoblin -====================================== +.. contents:: Sections + :local: -First thing to do is check out the Web site where we list all the -project infrastructure including: -* the mailing list +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 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 +`. + +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: + +* Python 2.6 or 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/ +* MongoDB - http://www.mongodb.org/ + +If you're running Debian GNU/Linux or a Debian-derived distribution +such as Mint or Ubuntu, running the following should install these +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: + + +How to set up and maintain an environment for hacking with buildout +=================================================================== + +**Requirements** -How to set up an environment for hacking -======================================== +No additional requirements. -The following assumes you have these things installed: -1. virtualenv: +**Create a development environment** - http://pypi.python.org/pypi/virtualenv +After installing the requirements, follow these steps: -2. virtualenv wrapper: +1. Clone the repository:: - http://www.doughellmann.com/projects/virtualenvwrapper/ + git clone http://git.gitorious.org/mediagoblin/mediagoblin.git -3. git: +2. Bootstrap and run buildout:: - http://git-scm.com/ + cd mediagoblin + python bootstrap.py && ./bin/buildout -Follow these steps: +That's it! Using this method, buildout should create a ``user_dev`` +directory, in which certain things will be stored (media, beaker +session stuff, etc). You can change this, but for development +purposes this default should be fine. -1. clone the repository:: - git clone http://git.gitorious.org/mediagoblin/mediagoblin.git +**Updating for dependency changes** -2. create a virtual environment:: +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:: - mkvirtualenv mediagoblin + ./bin/buildout && ./bin/gmg migrate -3. if that doesn't put you in the virtual environment you created, - then do:: - workon mediagoblin +**Updating for code changes** -4. run:: +You don't need to do anything---code changes are automatically +available. - python setup.py develop +**Deleting your buildout** -When you want to work on GNU MediaGoblin, make sure to enter your -virtual environment:: +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. - workon mediagoblin +To do this, do:: -Any changes you make to the code will show up in your virtual -environment--there's no need to continuously run ``python setup.py -develop``. + 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:: + + CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd Running the test suite @@ -69,23 +158,164 @@ Running the test suite Run:: - python setup.py test + ./runtests.sh + + +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 +=============== + +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 + `_. Let us know! + + +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 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 +============================= + +**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 +============================= + +Learning Python +--------------- + +GNU MediaGoblin is written using a programming language called `Python +`_. + +There are two different incompatible iterations of Python which I'll +refer to as Python 2 and Python 3. GNU MediaGoblin is written in +Python 2 and requires Python 2.6 or 2.7. At some point, we might +switch to Python 3, but that's a future thing. + +You can learn how to code in Python 2 from several excellent books +that are freely available on the Internet: + +* `Learn Python the Hard Way `_ +* `Dive Into Pyton `_ +* `Python for Software Design `_ +* `A Byte of Python `_ + +These are all excellent texts. + +.. YouCanHelp:: + + If you know of other good quality Python tutorials and Python + tutorial videos, let us know! + + +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:`codebase-chapter` +along with links to the project Web sites and documentation for the +libraries. + +There are a variety of Python-related conferences every year that have +sessions covering many aspects of these libraries. You can find them +at `Python Miro Community `_ [0]_. + +.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro + Community. + +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. -Creating a new file -=================== +If you're new to git, we highly recommend the following resources for +getting the hang of it: -All new files need to have the standard GNU MediaGoblin -license/copyright header. +* `Learn Git `_ --- the GitHub + intro to git +* `Pro Git `_ --- fantastic book +* `Git casts `_ --- screencast covering git + usage +* `Git Reference `_ --- Git reference that makes + it easier to get the hang of git if you're coming from other version + control systems -For Python files, include the license/copyright header at the top such -that each line of the header starts with ``#``. +There's also a git mission at `OpenHatch `_. -For Jinja2 template files, FIXME. -For JavaScript files, FIXME. +Learning other utilities +------------------------ -For CSS files, FIXME. +The `OpenHatch `_ site has a series of +`training missions `_ which are +designed to help you learn how to use these tools. -If you're doing the copy-paste thing, make sure to update the -copyright year. +If you're new to tar, diff, patch and git, we highly recommend you sign +up with OpenHatch and do the missions.