Source

circuits / docs / Contributing.wiki

Full commit
= Contributing to Circuits =

[[TOC]]

||'''status'''||Work in Progress||

If you want to help out, we want to help you help out! The goal of
this document is to help you get started and answer any questions you
might have.

== Installing the Development Version of Circuits ==

=== Pre-requisites ===
 1. [http://python.org/ Python] 2.5 or better.
 1. [http://peak.telecommunity.com/DevCenter/setuptools setuptools]
 1. [http://www.selenic.com/mercurial/ Mercurial]

If you haven't already, please download and follow the installation
instructions for each of the aboave required software for your platform.

=== Installing Circuits from Source ===
 1. Get the latest source code from the Mercurial respository:
{{{
#!sh
$ hg clone http://hg.softcircuit.com.au/projects/circuits/
}}}

 1. (Optionally) create a new branch:
{{{
#!sh
hg clone circuits circuits-mybranch
}}}

 1. Tell setuptools to use this version:
{{{
#!sh
$ python setup.py develop
}}}

Congratulations! You now have a source installation of Circuits.
Happy Hacking!

=== Troubleshooting ===
''No known issues''

== Coding style ==
Since it's hard to argue with someone who's already written a code style
document, Circuits follows
[http://www.python.org/peps/pep-0008.html PEP 8] conventions with some minor
exceptions:

 1. Use tabs instead of spaces. ('''Tab Spacing''': 3)
 1. No line of code must exceed 70 characters in length.
 1. Double-Quotes must be used for all strings. {{{"}}} not {{{'}}}.

== Testing ==
Automated unit tests are better than good. They make future growth of the
project possible.

Circuits uses [http://somethingaboutorange.com/mrl/projects/nose/ Nose]
which makes testing easy. You can run the tests just by running
{{{nosetests}}} or {{{make tests}}} in the top-level of the source tree.

Any '''enhancements''', '''fixes''' or '''modifications''' must under go the
full unit test suite before it is approved and applied to the main development
branch of circuits.

== Documentation ==
As mentioned in the [wiki:docs/Philosoph Project Philosophy] document, a
feature doesn't truly exist until it's documented. Tests can serve as
good documentation, because you at least know that they're accurate,
but, it's also nice to have some information in English.

The Circuits Documentation is available at:
 * http://trac.softcircuit.com.au/circuits/wiki/docs

Please document your own work. It doesn't have to be Shakespeare, but
the editors don't enjoy writing documentation any more than you do
(''we'd rather be coding'') and it's much easier to edit an existing
document than it is to figure out your code and write something from scratch.

To contribute documentation you can:
 1. Write a page in the SandBox section of the [/wiki Circuits wiki].
 1. Request a review of it by submitting a [/newticket Ticket].

One of the documentation editors will then pull your
document into the official documentation, possibly doing
a bit of editing in the process so that the style and tone
match the rest of the official documents.

== Documenting Changes ==
The [http://trac.softcircuit.com.au/circuits/ Circuits Trac] is mostly
used for tracking upcoming changes and tasks required before release
of a new version.
The [http://trac.softcircuit.com.au/circuits/wiki/docs/ChangeLog ChangeLog]
provides the human readable list of changes.

Updating the [wiki:docs/ChangeLog ChangeLog] right before a release just slows
down the release. Please '''update the !ChangeLog as you make changes''', and
this is '''especially''' critical for '''backwards incompatibilities'''.

== How to Submit a Patch ==
Please make sure that you read and follow the
[wiki:docs/PatchingGuidelines Patching Guidelines]
----
[.. Up]