Table of Contents

  1. Participating in the community
  2. Code to read
  3. Directory layout
  4. Coding style
  5. Secure coding guidelines
  6. Documentation
    1. Document Everything
    2. Public API Documentation
  7. Automated tests
  8. Writing test cases before code
  9. Tracking down memory leaks
  10. Writing log messages
  11. Crediting

Hacker's Guide to PyAMF

If you are contributing code to the PyAMF project, please read this first.

Participating in the community

PyAMF is a true open-source project under a MIT-style license. A number of developers work for small and large companies, and many others are simply excellent volunteers who are interested in building a better AMF library.

The community exists mainly through mailing lists and a Subversion repository. To participate:

Go to http://pyamf.org/ and

  • Join the "dev", "commits", and "announce" mailing lists. The dev list, dev@…, is where almost all discussion takes place. All development questions should go there, though you might want to check the list archives first. The "commits" list receives automated commit emails.

There are many ways to join the project, either by writing code, or by testing and/or helping to manage the bug database. If you'd like to contribute, then look at:

To submit code, simply send your patches to dev@… after reading the rest of this file.

To help manage the issues database, read over the issue summaries, looking and testing for issues that are either invalid, or are duplicates of other issues. Both kinds are very common, the first because bugs often get unknowingly fixed as side effects of other changes in the code, and the second because people sometimes file an issue without noticing that it has already been reported. If you are not sure about an issue, post a question to dev@…

Another way to help is to set up automated builds and test suite runs of Subversion on some platform, see the BuildBot page for more info.

Code to read

Before you can contribute code, you'll need to familiarize yourself with the existing code base and interfaces.

Check out a copy of PyAMF (anonymously, if you don't yet have an account with commit access) — so you can look at the code.

  • the basic building blocks: ...
  • utilities: ...
  • encoder/decoder: ...
  • client-side interfaces: ...
  • gateways: ...

Directory layout

A rough guide to the source tree:

  • doc/ -- User and Developer documentation.
  • examples/ -- Sample applications.
  • www/ -- Web pages (live content at http://pyamf.org).
  • cypamf -- C implementation for PyAMF, see ticket #225.
  • pyamf -- Source code to PyAMF itself.

Coding style

todo

Secure coding guidelines

todo

Documentation

Document Everything

Every function, whether public or internal, must start out with a documentation comment that describes what the function does. The documentation should mention every parameter received by the function, every possible return value, and (if not obvious) the conditions under which the function could return an error.

For actual source code, internally document chunks of each function, so that someone familiar with PyAMF can understand the algorithm being implemented. Do not include obvious or overly verbose documentation; the comments should help understanding of the code, not hinder it.

Public API Documentation

We use the Eypdoc format for public interface documentation. Snapshots of the public API documentation are generated from the latest Subversion sources after each commit.

We use only a small portion of the available epydoc commands to markup our source. When writing epydoc documentation, the following conventions apply:

  • Use complete sentences and prose descriptions of the function, preceding parameter names with @param and @type.
  • C{} for markup, U{} for URLS and L{} for references

See the epydoc manual for a complete list of commands.

Automated tests

We have arranged for the automated test framework to run at regular intervals on several machines, sending the results to the pyamf.org Buildmaster. The more different platforms the tests run on, the more quickly we can detect portability bugs in PyAMF. If you'd like to provide as buildslave as well read the BuildBot page.

Our BuildBot build/test farm can be found at http://buildbot.pyamf.org

Writing test cases before code

Tracking down memory leaks

Writing log messages

Every commit needs a log message.

The intended audience for a log message is a developer who is already familiar with PyAMF, but not necessarily familiar with this particular commit. Usually when someone goes back and reads a change, he no longer has in his head all the context around that change. This is true even if he is the author of the change! All the discussions and mailing list threads and everything else may be forgotten; the only clue to what the change is about comes from the log message and the diff itself. People revisit changes with surprising frequency, too: for example, it might be months after the original commit and now the change is being ported to a maintenance branch.

The log message is the introduction to the change. Start it off with one line indicating the general nature of the change, and follow that with a descriptive paragraph if necessary. This not only helps put developers in the right frame of mind for reading the rest of the log message, but also plays well with the "commit bot" that echoes the first line of each commit to realtime forums like IRC. However, if the commit is just one simple change to one file, then you can dispense with the general description and simply go straight to the detailed description.

Throughout the log message, use full sentences, not sentence fragments. Fragments are more often ambiguous, and it takes only a few more seconds to write out what you mean. Certain fragments like "Doc fix", "New file", or "New function" are acceptable because they are standard idioms, and all further details should appear in the source code.

Crediting

It is very important to record code contributions in a consistent and parseable way. This allows us to write scripts to figure out who has been actively contributing — and what they have contributed — so we can spot potential new committers quickly. The PyAMF project uses human-readable but machine-parseable fields in log messages to accomplish this.

When committing a patch written by someone else, use "Patch by: " at the beginning of a line to indicate the author: 

Fix issue #129: Don't crash because of a missing file.

Patch by: J. Random <jrandom@example.com>

If someone found the bug or pointed out the problem, but didn't write the patch, indicate their contribution with "Found by: ": 

Fix issue #129: Don't crash because of a missing file.

Found by: J. Random <jrandom@example.com>

If someone suggested something useful, but didn't write the patch, indicate their contribution with "Suggested by: ": 

Fix issue #129: Don't crash because of a missing file.

Suggested by: feisley

If someone reviewed the change, use "Review by: " (or "Reviewed by: " if you prefer): 

Fix issue #129: Don't crash because of a missing file.

Review by: Eagle Eyes <eeyes@example.com>

A field may have multiple lines, and a log message may contain any combination of fields: 

Fix issue #129: Don't crash because of a missing file.

Patch by:            J. Random <jrandom@example.com>
Suggested by:  feisley
Review by:        Eagle Eyes <eeyes@example.com>