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.
- 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.
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.
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.
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¶
- git documentation - useful for development, and for understanding the inspiration behind Ductus’ ResourceDatabase
- Django (very good tutorials, API reference) Keep in mind we don’t use Django’s Model system for much, but Ductus’ model system is inspired by Django.
- html5 spec, dive into html5
- The HTML media capture API will allow users to submit audio, pictures, etc. directly from the web browser
- jQuery, and we use a few things from jQueryUI