Development

Table of Contents

1. Summary
2. How to send us a patch
3. Coding style guide
4. Tests
5. Documentation

---

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 send us a patch

Tie your changes to an issue in the issue tracker!

It vastly simplifies the work if your work is tied to an issue in the tracker. If there isn't an issue, yet, for the work you want to do, please create one. If there is an issue, then assign it to yourself, do the work, and comment on that issue when you're done.

Use bugfix branches!

It's important to use a workflow that puts changes related to a single bug/feature in a separate branch. We call this a bugfix branch. You can name it something like issue_101. Generally, short branch names are easier to use.

If you're working on two different features, you should have a different branch for each of them. This greatly simplifies things when I accept patches, reject patches, make changes, etc in the master branch. This way, when you fetch, your master branch isn't wildly diverged from the Pyblosxom master branch which requires some tinkering to get aligned again.

Properly document your changes!

Three things to do to make it easier for us to use your hard work!:

1. describe the problem you're solving with your patch
2. describe how your patch solves the problem
3. include unit tests

How to create a bugfix branch

Here's how to clone the repository and create a bugfix branch:

1. clone the repository:
   

   $ git clone git://github.com/willkg/pyblosxom.git
   

2. set the user.name and user.email config bits:
   

   $ git config user.name "your name"
   $ git config user.email "your@email.address"
   

3. create a bug/feature focused branch for the change you want to make

   $ git checkout -b BRANCHNAME origin/master
   

4. make the changes you want to make in that bug/feature focused branch and commit them
5. when you're done, send us the changes

How to send us your changes

There are a few ways to send us your changes:

1. do:

   $ git format-patch -o patches origin/master
   

   tar up the directory and attach it to the issue it relates to, OR
2. push your changes to a publicly available repository and add a comment to the issue with the url of your repository, the branch the changes are in, and what you did, OR
3. push your changes to a clone on GitHub and create a pull request between Pyblosxom master and your bugfix branch

If you're new to git

The Git site has a great page covering documentation and tutorials. Please check out their resources and spend some time learning how to use git.

If you have questions

If you have questions, please ask us on the pyblosxom-devel mailing list.

Coding Style Guide

Follow PEP-8.

Tests

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

Tests are written using the unittest module.

Documentation

The Pyblosxom manual is in the docs/ directory. Documentation is in restructured text format and built with Sphinx.