Ductus Contributor Guide

Interacting with the project team

#wikiotics on FreeNode. Two google groups: ductus-developers (for discussion of use/development of ductus itself) and wikiotics (for broader community aspects). A semi-serious developer should be on both lists at this point.

Coding style

  • PEP 8 describes the ideal style for Python programs. All python developers should be familiar with this document, as most everyone follows this style. We follow it with only a few exceptions.
  • It seems that we mostly follow Google’s JavaScript style guide. Major differences: we currently use underscores instead of camelCase for variables, functions, and methods. And we don’t use jsdoc for anything at the moment.

Also, we generally don’t commit to the repository any code that contains trailing whitespace after lines. And a file should end with precisely one newline; there should be no extraneous newlines at the end of a file.

Indentation should be done with spaces, never with tabs. Tabs are evil The only place we should have tabs is when we have copied and pasted code from another project and that project uses tabs. In this case, we should use tabs only (and not mix spaces with them) when we modify that code. Getting indentation correct the first time is a Good Thing because it messes up the diff/blame history any time you change indentation.

A useful resource for staying away from JavaScript pitfalls is the Javascript Garden. Douglas Crockford’s book, Javascript: The Good Parts, can also be a useful reference.

See also Mozilla’s Secure Coding Guidelines, which can be generally useful. Another useful link.

We are pretty serious about the DRY principle. To avoid repeating ourselves, and to hide complexity in parts of the API, we make heavy use of python’s metaprogramming features, particularly in the “ductmodels” layer. In general, if you are copying and pasting code, there is probably a better way to do it. That’s fine for prototyping, but before submitting code for inclusion in the main development branch, it’s generally best to make the code as maintainable as possible.

We try to fix broken windows as we go.

Some random notes

  • use optipng on all PNG files before adding them to the repository

Patch submission

Patches can either be uploaded to the corresponding ticket on trac, or a developer can tell us to pull a patch (or patch series) from a git repository. The pull will only occur if the maintainer is satisfied with everything in the patch series. Ductus is registered on gitorious], which provides workflow mechanisms with which we can experiment. Keep in mind, though, that garrison doesn’t push code to gitorious as often as he pushes to git.garrison.cc, so it’s best to pull from git.garrison.cc any time you want the latest code.

If using git, never ever ever commit unrelated changes in the same changeset. Each commit should be one logical change. And it should attempt to break nothing and to introduce no additional brokenness. The same is true for patches submitted to trac.

If a commit fixes a ticket, the summary should be formatted as follows:

Fixed #25. Users can now enter their email addresses.

If a commit references a ticket but does not fix it, the summary should formatted as so:

[#203] Add border to table cells in editor and widen them.

This will allow the referenced ticket to be clickable at http://code.ductus.us.

Documentation for ductus

This is the doc about the doc :)

The docs use sphinx and reStructuredText.

There are two ways to access the docs:

  • The main documentation is built at http://ductus.readthedocs.org/en/latest/ and updated every few hours. The file <ductus_root>/doc/conf.py has a special section (look for READTHEDOCS in there) to deal with their specific build process.

  • You can build your own local copy of the docs from the source code by running:

    cd <ductus_root>/doc
    make html SPHINXBUILD=../ductusenv/bin/sphinx-build

    This assumes sphinx is installed in your virtualenv. If not, you will get a copious amount of warnings about libraries/packages not found.

If you want to write additional documentation, awesome! Just be aware that when building the docs, a number of files are created/overwritten by sphinx-apidoc. Just run the build to get the list of files (right after “running apidoc” in the output).

Documentation for software/specifications we use and depend on

Other “required” reading

See also