Start by geting the latest source with
bzr branch lp:objgraph
Run the test suite with
make test
The test suite is mostly smoke tests (i.e. crashes will be noticed, subtly wrong output will be missed). I hope to improve that in the future, but don’t hold your breath. Most of the testing is done manually or semi-automatically, e.g. by running make images and eyeballing the results (imgdiff is handy there).
Bazaar branches and merge proposals are probably the best way to send me patches. Or just attach the pathces to a bug in Launchpad. Or email them to <marius@gedmin.as>.
I’d appreciate bugs in launchpad for each proposed change, be it a bug or a feature request.
Python 2.4 through 2.7, as well as 3.x.
You can run the test suite for all supported Python versions with
make test-all-pythons
An easy way to get Pythons 2.4 through 2.7 (and 3.1) on Ubuntu is to use Felix Krull’s “deadsnakes” PPA:
sudo add-apt-repository ppa:~fkrull/deadsnakes
sudo apt-get install python2.{4,5,6,7} python3.1
As I mentioned, the tests are mostly smoke tests, and even then they’re incomplete. Install coverage to see how incomplete they are with
make coverage
I use a vim plugin to higlight lines not covered by tests while I edit
mkdir -p ~/.vim/plugin
cd ~/.vim/plugin
wget http://mg.pov.lt/vim/plugin/py-coverage-highlight.vim
cd ...
make coverage
vim objgraph.py
:HighlightCoverage
If you prefer HTML reports, run
make coverage
coverage html
and then browse htmlcov/index.html.
To fully rebuild the documentation, run
make clean images docs
Please bzr revert the png files that haven’t changed significantly. (Many of the images include things like memory addresses which tend to change from run to run.)
imgdiff is useful for comparing the images with older versions:
bzr diff --using imgdiff *.png
When you add a new doctest file, remember to include it in docs/index.txt.
When you add a new function, make sure it has a PEP-257-compliant docstring and add the appropriate autodoc directive to objgraph.txt.
I insist on one departure from PEP-257: the closing """ should not be preceded by a blank line. Example:
def do_something():
"""Do something.
Return something valuable.
"""
If Emacs is broken, fix emacs, do not make my docstrings ugly.
On the other hand, if the last thing in a docstring is an indented block quote/doctest section, it should be surrounded by blank lines. Like this:
def do_something():
"""Do something.
Return something valuable.
Example:
>>> do_something()
42
"""
I find restview very handy for documentation writing: it lets me see how the text looks by pressing Ctrl-R in a browser window, without having to re-run any documentation building commands. The downside is that restview doesn’t support Sphinx extensions to ReStructuredText, so you end up with error messages all over the place. Then again this is useful for bits that can’t use Sphinx extensions, like the PyPI long description.
To preview the PyPI long description (which is generated by concatenating README.txt and CHANGES.txt) with restview, use this handy command:
make preview-pypi-description
because typing
restview -e "python setup.py --long-description"
is tedious, and bash has tab-completion for makefile rules.
You need write access to the PyPI package and to the Bazaar branch on Launchpad. At the moment of this writing, this means you must be me.
Run make release and follow the instructions. It is safe to run this command at any time: it never commits/pushes/uploads to PyPI, it just tells you what to do.
It is important to keep MANIFEST.in up to date so that source tarballs generated with python setup.py sdist aren’t missing any files, even if you don’t have the right setuptools version control plugins installed. You can run
make distcheck
to be sure this is so, but it’s not necessary – make release will do this every time.