Developer's Guide to the Code

Overview

This page serves as an introduction to and tour of the GCD code base. It attempts to stay high-level in an effort to avoid becoming out of date immediately as details change. The GCD is implemented as a Django-based web application, using MySQL as a database. Elasticsearch together with haystack for django is used for general search capability, and at some point we will be using one of the major JavaScript libraries. The general layout is based on what seemed to be Django best practices circa late 2007. Some things might not make much sense, and we'd generally like to fix those, but we have very limited resources and the nature of the server crisis that led to the current code's deployment caused us to accept some choices we might not have otherwise made.

gcd-django

Our code is hosted at github as gcd-django. The master branch is the currently deployed site. The beta branch, containing new features which haven't been extensively tested, is usually deployed on beta, if it's deployed at all. You can read more in our guidelines for git branches and clones.

Django

If you do not know about django, please read at least the overview for it. This should give you an idea about models, views and templates. With that one can understand the workflow of how a specific web-server URL request goes through the system and how the data can be accessed.

We have several different so-called apps for our website:

• gcd for display of our content, this is what a visitor will see
• oi for editing of our content, this is what an indexer will see
• voting for handling votes for the GCD
• projects for some database clean-up projects
• my_comics for tracking collections of users
• indexer for user handling
• select for selecting database objects during editing
• stats for handling states of the database
• stddata includes models for standard data such as countries, languages, currencies

gcd-historical-archive

We also keep a gcd-historical-archive at github. The top level of it reflects the speedy development and deployment, the following info is kept is historical information.

• branches

  Various release and development branches of the pydjango tree. One of these is usually deployed on production. There are also some branches for exploring new UI designs and search tools. Inquire on the mailing list for the current status of those trees.

• bugzilla-patch

  The GCD uses two different modified versions of Bugzilla 3.0.3- one for tracking data errors and one for technical bugs. This directory holds the patches used to create those versions from a base 3.0.3 installation.

• database

  MySQL migration scripts, schema definitions and scripts involving dumping data in various formats. The scripts for each release are in a sub-directory numbered and named after that release. The scripts in the 0.4_littlenemo directory are a bit more complicated. The "0" scripts (0, 0a, 0b) are for migrating the 0.3 release to the "pre-nemo" branch which was in production leading up to the release of 0.4. The scripts numbered 1 and higher are for migrating pre-nemo to the full 0.4 little nemo schema.

• gcd

  This was a re-start of the project, intended to supersede the prototype that was developed in the pydjango tree. It has what Henry considers to be a better Python package layout. But then the server went down and the previous admin felt it was better to end support for that system, and we had to resurrect the prototype. This has useful stuff about the eventual schema direction but is otherwise a dead end.

• pydjango

  The "trunk" version of the currently deployed site. Usually deployed on beta, if it's deployed at all. The pydjango project was originally a proof-of-concept intended to show that a system written in Python using the Django framework was the right way to go (as opposed to a content management system such as Drupal, or a Microsoft-based solution such as ASP.NET). Of course, there was a crisis and the prototype ended up in production. It did get almost entirely rewritten between the initial proof of concept and the production version, but there's still more legacy weirdness than Henry would like to have in a "new" project.