PyBlosxom - main site

Summary
How to contribute
Contributors
Subversion
Coding style guide
Release instructions

Summary

This page covers how to contribute to PyBlosxom development, what our coding conventions (or should be), our mission, lists a non-comprehensive list of contributors, and then ends with a short blurb that will eventually be replaced with the processes we use to do things.

If you plan on contributing to PyBlosxom, please read this guide in its entirety.

Having said that, this guide is a draft and can change at any time--we update it as necessary.

How to contribute

Some folks want to become part of the development. Other folks just want to send us a patch that fixes something that bugged them. We appreciate both groups of folks and ... well, we'll take whatever we can get.

If you want to send us a patch, send it to the pyblosxom-devel mailing list. Make sure it's clear what the patch is fixing and why you fixed it that way. Please note any issues there might be and how much testing it went through. Details on the pyblosxom-devel mailing list are on the contact page.

All contributions are appreciated even if they aren't directly used. Sometimes the patch will start a conversation that might end up in a different fix.

If you want to become a PyBlosxom developer we ask that you join the pyblosxom-devel mailing list, tell us your intentions and what your mission is, and then the conversation will go from there.

If you want to contribute but have no coding skills--that's ok! There's all kinds of other ways people can contribute: fixing/editing/adding documentation, finding bugs, contributing tutorials, helping folks who are new to PyBlosxom come up to speed, ...

PyBlosxom has a sophisticated callback framework allowing for plugins to modify existing PyBlosxom behavior. Many problems can be solved by writing a plugin rather than adding more code to the PyBlosxom core.

Contributors

Note from Will: I don't have a list of contributors. If you've contributed to PyBlosxom but don't see your name here (or if you want your name modified or even removed), let us know on the pyblosxom-devel mailing list.

This list is in no particular order:

Wari, Blake, Ted, Will, Bill, Robert, LionKimbro, Limdou, Steven, David, and Matej.

Subversion

Our code is in a Subversion repository on SourceForge.

Browse Subversion Repository through your web-browser.

For anonymous read-only access to PyBlosxom trunk code do:

svn co https://pyblosxom.svn.sourceforge.net/svnroot/pyblosxom/trunk/pyblosxom/ pyblosxom

For anonymous read-only access to PyBlosxom contributed plugins code do:

svn co https://pyblosxom.svn.sourceforge.net/svnroot/pyblosxom/trunk/contrib/ contrib

If you are a registered PyBlosxom developer with Subversion access, you can check out the code using the above methods. When you go to commit things, use the form:

svn commit --username your-username files...

Notes about checkin comments: PLEASE provide comprehensive checkin comments that describe what you did, why you did it, any known ramifications of what you did to users/developers, related bug numbers, and any other notes. We use the checkin comments to figure out the CHANGELOG for releases and also to tell users what changes they have to make to their installation when they upgrade.

Coding Style Guide

This document describes PyBlosxom coding conventions and development processes.

Tabstops and spacing

Indentation is done in multiples of 4. All spacing shall be done with spaces--no tabs. Indent when you need to per Python syntax.

Maximum line length

Try not to jam everything into one line.

Naming

File, module, and package names are all lowercase with no punctuation except underscores:

cache.py
pyblosxom.py
base.py
__init__.py

Constants are all uppercase with _ between words:

BIGNUM
VAR_REGEXP

Classnames are mixed case starting with an uppercase letter:

Entry
Request
BlosxomRenderer

Methods are mixed case with the first letter being lowercased:

runCallback
initialize

Functions and variables are all lowercase with underscores:

blosxom_handler
var2

Private functions and variables start with one underscores and consist solely of lowercase letters and underscores:

_internal_cache
_internal_wrap

Comments

There are three mortal sins regarding comments:

code with no comments
Punishable by early bedtime--unless your code is so unbelievably good that it reads like English. Even then it should be commented.
comments that are poorly written
Comments should be written in English and should be either well-formed sentences or well-formed phrases. They should be informative--not reduntant. They should be poetic--revel in your commenting.
comments should not contradict the code
This usually happens when you change the code but forget to change the comment. Always check comments around code you're editing and adjust them accordingly.

Docstrings

All modules, classes, functions, and methods should have doc strings. We run an out of line documentation generater against these doc strings and thus they become part of the online html documentation of the code. They help us--they make it easier to look things up and to understand what the code does. Docstrings should be terse, informative, and beneficial. They should answer the questions:

What is this?
How do I use it?
What does it take in as input and return as output?

Docstrings are denoted by the use of """ around the docstring. Anything else is just a regular comment or string. Docstrings should be sentences--not phrases.

Docstrings should be written in Epytext (http://epydoc.sourceforge.net) which is a simple markup that has some characteristics found in Javadoc. We generate our API documentation from the docstrings and having it in the right format makes prevents someone from going in and fixing it later.

Docstrings for functions and methods should denote the types and descriptions of any arguments passed in and any return values.

Examples of docstrings:

   def what_ext(extensions, filepath):
       """
       Takes in a filepath and a list of extensions and tries them all until
       it finds the first extension that works.

       @param extensions: the list of extensions to test
       @type  extensions: list of strings

       @param filepath: the complete file path (minus the extension) to test
       @type  filepath: string

       @return: the extension that was successful or None
       @rtype: string
       """
       for ext in extensions:
           if os.path.isfile(filepath + '.' + ext):
               return ext
       return None

   def is_year(s):
       """
       Checks s to see if it's likely to be a year or not.  In order to be
       considered to be a year, it must pass the following criteria:

        1. four digits
        2. first two digits are either 19 or 20.

       @param s: the string to check for "year-hood"
       @type  s: string

       @return: 1 if s is likely to be a year or 0 if it is not
       @rtype: boolean
       """
       if not s: return 0

       if len(s) == 4 and s.isdigit() and (s.startswith("19") or s.startswith("20")):
           return 1
       return 0

Tests

Tests go in the tests/ directory. From PyBlosxom 1.4 on, write tests for new functionality.

Documentation

The PyBlosxom manual is in the docs/ directory. Documentation is in restructured text format.

Release Instructions

First, the checklist:

make sure everything is checked in and there are no outstanding issues
make sure MANIFEST.in is correct

build the tar ball:

python setup.py sdist

run the tar ball through Cheesecake:

cheesecake_index --verbose -p pyblosxom/pyblosxom-1.4tar.gz -s ./tmp \
   > pybl_1.4.log

run a test install

run tests:

nosetests --verbose --include unit
nosetests --verbose --include functional

make sure the API docs build correctly:

/usr/bin/epydoc \
   --html \
   -o "./api/" \
   --name "Pyblosxom (1.4)" \
   --url "http://pyblosxom.sourceforge.net/" \
   --inheritance grouped \
   --css white \
   -v \
   Pyblosxom

make sure the manual builds correctly (run buildhtml in the docs directory)

Now the instructions:

change VERSION in pyblosxom/Pyblosxom/pyblosxom.py to something like this: "1.4"
change VERSION_DATE in pyblosxom/Pyblosxom/pyblosxom.py to something like: VERSION + " 7/2/2007" (m/d/yyyy)
check in all changes

tag the release

svn cp https://pyblosxom.svn.sourceforge.net/svnroot/pyblosxom/branches/PYBLOSXOM_1_4 \
       https://pyblosxom.svn.sourceforge.net/svnroot/pyblosxom/tags/pyblosxom_1.4.3/

run:
```
python setup.py sdist
```
use ReleaseForge to create the new release with the resulting .tar.gz
1. launch releaseforge
2. log in
3. select "pyblosxom" from the projects list
4. select "pyblosxom" from the packages list
5. press the "create new release" button
  - Release name: 1.4
  - Release notes: specify what the release is about
  - ChangeLog: (anything in the CHANGELOG for that version)
6. press the "next" button
  - press the "Add Files" button
  - choose pyblosxom-1.4.tar.gz file
  - processor: platform-independent
  - file type: source .gz
7. press the "next" button
8. press the "submit" button
send an announcement email to pyblosxom-announce at lists dot sourceforge dot net
write up a blog entry for the web-site in /releases

Development HOWTO

Table of Contents