Basic process

The trunk for Amara & Akara are on github. If you're not sure how to proceed with contributing, please work with a core developer. You should also make sure you are set up to sign git tags.

Basic, typical flow:

• Developer makes changes on a read+write clone, and decides these are significant (i.e. they represent a state we'd like to be able to recover)
• Developer commits (i.e. locally in git clone)
• Developer creates a tag object against the commit representing the version bump (e.g. named "2.0.0a5")
• Developer commits and tags changes

• Developer runs python setversion.py to enshrine the version number based on the new tag

• Developer commits change to lib/version.py

• Developer moves the tag to the new commit
• Developer pushes commits to trunk

Notes:

• Please make a release version tag in the form "v<version>", e.g. "v2.0.0a5" which will allow us to separate this from other uses of tag names such as "merge_spam" or even "very_big_advance". The latter will not cause confusion because the second character is not numerical.

• When selecting version numbers please be sure you're familiar with the conventions emerging for distutils2

Some useful tips:

• Use git tag -l to list the tags

• Make sure you use git tag -s <tagname> -m "<tagmessage>" or at least the -a flag to make a proper tag object. Add the -f flag for the second tagging command (to force a move)

• Use git describe liberally to be clear on the state of things

• Use git push --tags to push changes as well as tags

See also:

• Intro to git tagging

• Brief on git describe

Work in progress

• Amara/Developer_notes/Test_migration

• Amara/Developer_notes/Porting

To do

Next release (2.0a3)

• node.xml_write and node.xml_encode -- Completed by amk

• XHTML writer
• accumulated fixes
• example or demo of XML parsing from incremental feed
• Windows build by user with Microsoft compiler or 32-bit MinGW
• Available Windows installer in 32-bit and 64-bit

Note: we've already moved the test suite to nose, and moved the main code source dir from amara to lib.

Longer term

• Make XPath even more lazy (i.e. full expression results lazy iterators rather than just internal steps)

Post 2.0

• Consider subclassing XSLT instruction nodes from core Amara nodes

• * Refactor XSLT instruction node API to match core Amara nodes (e.g. appendChild -> xml_append_child)

• Rename core nodes Document to Entity and update the API, along the lines of DOM Level 3

General notes

Follow PEP 8 for the most part. Modified naming conventions:

• public, global constants: SPAM_EGGS

• Exception classes: SpamError, all derived from amara.Error

• Everything else: spam_eggs (yes, even class names)

Mercurial

See Akara/Developer_notes/Mercurial

Releases

Amara/Release_process

Test sandbox

There are some instructions for setting up separated Amara 2.x installs at: Amara1/Quick_start

You should probably rename the local folder to reflect the branch, and make sure you edit its .hg/hgrc to make its default destination the branch rather than main

Debugging tips

• "finding memory leak in edgewall trac 0.11" - Has many general notes for memory leak finding in protocol servers

Profiling

To run a script file and gather the stats:

python -m cProfile -o <statsfile> <scriptfile>

For an interactive profile statistics browser:

python -m pstats <statsfile>

e.g.:

echo "from amara import bindery; bindery.parse('http://intertwingly.net/blog/index.atom')" > /tmp/foo.py
python -m cProfile -o /tmp/foo.stats.txt /tmp/foo.py
python -m pstats /tmp/foo.stats.txt

Some useful commands in the browser:

• sort cumulative

• stats 10

See also:

• Amara/Performance

• http://docs.python.org/library/profile.html

• http://www.python.org/doc/2.5.2/lib/module-profile.html

i18n

Start by following the example of OLPC: http://wiki.laptop.org/go/Python_i18n

In particular make sure all display strings are wrapped for l10n, and we'll figure out the framework as needed.