Web Site Project Page

GCD Web Site Project Master Page

The GCD is currently implementing a new web site to reflect the growth of the project and changes in available technology. This page summarizes the project status and provides links to information on various aspects of the work.

We welcome assistance from programmers and non-programmers alike (yes, we have tasks for non-technical people!).

Releases and Status

Projected releases are named after comic books, and are planned in detail on their own pages. Release numbering is tentative as intermediate releases may be added or removed as plans and features are revised.

GCD Site Releases by Code Name

Name	#	Purpose	Status	Next Milestone	Next Date	Comments
New Fun	1.0	First functional, production-ready release. Will contain the minimum functionality needed to migrate from the old site.	Planning	Detailed Requirements	2008-11-02	Named for the first U.S. comic book with all-new content.
More Fun	1.1	Minor release for small items that are not critical for inclusion in New Fun, or that require us to already have control of the database.	Planning			As the comic "New Fun" became "More Fun", this release is just a small next step.
The Dandy	TBD	First release to include major steps towards the new schema. There may be one or more small releases between More Fun and The Dandy				Named for the very long-running British Weekly comic. Also, this release should be quite dandy :-)

Development Environment

• Mailing List: gcd-tech at Google Groups
• Bug Tracking: Bugzilla (GCD Tech version)
• Source Code: Subversion hosted by SourceForge
• Code Reviews: Review Board (GCD Tech installation) (please read the User Documentation and How to Use post-review)

Note that the first Review Board documentation page tells you (buried in the text) how to get post-review, and the second tells you how to use it. But they're not linked. The docs need a bit of work, so we might put some tips here soon.

How to set up a development environment:

• MacOS
• Windows

Please join the mailing list and email us if you would like to help out!

3rd-party Documentation

• Python
• Django
• MySQL
• Selenium

Standards and Best Practices

Code submitted to the project should follow these standards. Review Board has been set up for code reviews, and all changes must go through code review and be approved before being checked in. Some of these guidelines are covered in places such as the Django documentation, but the ones restated below are items we feel are important enough to be called out here.

For Python

Write Python 2.4 compatible code.

This is in part because of compatibility problems with a dependent package on Mac OS 10.4. But also because hosting environments might not all be up to 2.5 yet (although that is less of a concern as time goes on). Your code should be compatible with Python 2.4-2.6.

Follow the Python Style Guide. Read the whole thing, as it is full of useful advice.

This saves us from arguing over which of our personal styles should be used. Code that does not meet these guidelines will not be allowed through code review. If you find existing code that does not comply, please consider cleaning it up. Do not consider it an excuse to write more non-compliant code.

Read Python Idioms and Anti-Idioms

And do what it says :-)

Read the Docstring Guide

And do what it says :-)

Always place one space after each comma separating function arguments.

Unless of course there's a newline. For some reason this is not mentioned in the style guide, although all examples there follow it.

When breaking a statement across two lines, if there is no obvious way to indent it, indent two characters more than the start of the statement.

This makes it clear that the continued statement is not another indented block. When possible, line up continued statements by lining up arguments vertically, or the continued operand in an expression with the operand on the previous line. But when no such rule applies, use two extra spaces. Examples:

Breaking with an "obvious" indentations scheme of lining up operands vertically:

   foo = (bar.some_numeric_thingy +
          some_other_number)

Breaking when there is no obvious indentations scheme (so two spaces are used):

   SomeClass.some_list_of_things[indexy_bit].big_long_method_call(
     some_long_variable_name)

Note that it's often better to just break things up into multiple statements by using a few local varaibles in these situations:

   thingy = SomeClass.some_list_of_things[indexy_bit]
   thingy.big_long_method_call(some_long_variable_name)

Do not use global variables. Ever.

If for some reason you feel you must do this, you must get approval from the Head Programmer first. The current acting Head Programmer is unlikely to approve such a thing. If 3rd-party libraries or frameworks rely on global variables, you may of course use them as required.

Make everything portable, and especially use os.path when working with files and directories.

The project currently has only three active developers and a shared test are, but already needs to run on MacOS, Windows and Linux. We also do not yet know what our hosting environment will be. So don't do anything that will limit us.

When capturing from regular expressions, use named capture groups, not positional groups.

This make regular expressions more robust if the string ever changes and capture groups get reorderd. Additionally, while the regexp itself is a bit more cluttered, the intention of the capture groups is much more clear. Examples:

Bad:

   m = re.search(r'foo:\s*(\w*), (\w*)', target)
   foo = m.groups()[1]
   bar = m.groups()[2]

Good:

   m = re.search(r'foo:\s*(?P<foo>\w*), (?P<bar>\w*)', target)
   foo = m.group('foo')
   bar = m.group('bar')

For Django Models

Do not refer to Views, Templates or site URLs.

Models are pure data representation. They should present what is in the database, and sometimes expose methods that make that data easier to work with. But they should essentially be unaware of the higher layers of the application. Note that model fields that contain URLs because the database contains URLs are OK. These are generally external links anyway (like the URL field for publishers).

For Django Views

Use named groups in the URL conf for argument passing.

This makes view invocation more robust.

Use named URLs to disambiguate reverse mappings.

This supports better abstraction when code needs to look up URLs.

For Django Templates

We need a style guide for templates!

Suggestions appreciated. For now, stick with the following rules:

Please try to keep content within 80 columns, but do not go through confusing contortions in the process.

In other words, if you've got long URLs or if you need to string things together due to the vagaries of how Django's template engine performs substitutions, go ahead and let the line be as long as it needs to be. However, don't put

For HTML

Use 2-character indentation for each nesting level.

For CSS

All CSS goes in external style sheets.

When modifying styles dynamically, it is better to modify the element's class(es) than set styles directly.

Classes and IDs are always lower_case_separated_by_underscores.

Colors are always associated with class names that define an elements role in the color scheme.

i.e. background, foreground, hilight, etc. Actual list TBD.

For JavaScript

We have not yet determined how and to what extend we want to use JavaScript. Please discuss any ideas with the Head Programmer first. Input on this topic is welcome.