Hacker's Guide To DITrack

$Id$
$HeadURL$

Q: Where should I start from if I wish to hack DITrack?

A:

0. Read this file completely.
1. Read the user manual.
2. Try DITrack yourself!
3. Read the design document (https://svn.xiolabs.com/ditrack/doc/design.txt).
4. Take a look at the following commands implementation (in order): cat, new,
commit. This will give you a high level idea of how things are organized.


=============================================================================

General conventions
-------------------

* We refer to issues (in commit logs, e-mail messages, other issue records) as
'i#123', that is small 'i', followed by a pound sign '#' and followed by an
issue number.


Message conventions
-------------------

* Don't use print() for output, use sys.std{err,out}.write() instead.

* Do not abbreviate: use 'identifier' instead of 'id'.

* Identifiers can NOT be 'local' or 'firm'; it is entities that can.

* How to craft up an error message about issue/comment/etc?

	* Can you parse the identifier?
		- if no, say "Invalid identifier..."

	* If it's not critical to exactly specify the details ('name'/'number',
	'issue'/'comment'), use more general terms ('identifier', 'entity').

	* Are you expecting specific type of the identifier?
		- if yes, say "...name..." or "...number...";
		- if no, say "...identifier...".

	* Are you expecting specific type of the entity?
		- if yes, say "...issue..." or "...comment...";
		- if no, say "...entity...".

	* If an entity cannot be found, say "No such..."

	* Say what you were expecting and display offending argument enclosed
	in single qoutes, e.g.:
		"Local identifier expected: '1.1'"

Coding conventions
------------------

* We do not use tabs; our indentaion step is 4 spaces.

* We align our code so that it doesn't wrap when being viewed in 80 column
terminal window. Also, the 80th character position should not be filled.

* We avoid trailing whitespace.

* We mostly use double quotes to denote strings. Yes, it's not Pythonic, it's
historic. If you don't like it, feel free to convert the whole codebase and
make sure all the tests pass. There is always space for exceptions, of course:
if the string contains several double qoutes, it makes sense to use single
qoutes as delimiters. Use your judgement: it's not about purism, it's all about
consistency and readability.

* Do NOT put a space between a function name and the opening brace:
	WRONG: sys.stdout.write ("\n")
	RIGHT: sys.stdout.write("\n")

* Do not put extra braces in conditional operators, unless the expression is
compound and the braces improve readability:
	WRONG: if(a > b):
	RIGHT: if a > b:

* Put statements following a contidional expression on separate line:
	WRONG: if a > b: greater = True
	RIGHT: if a > b:
	           greater = True

* Lists of all kinds should be sorted if there is no obvious reason against it.
This includes module import lists.

* Put spaces on both sides of an operator:
	WRONG: if a>b: 
	RIGHT: if a > b

* Do NOT put spaces around the '=' sign in a parameter specification in a
function call:
	WRONG:	func(1, value = 2)
	RIGHT:	func(1, value=2)

* Place comments on separate lines if possible. Sticking statements and 
comments together makes the code harder to edit.
	WRONG:	a = 1 # just a magic number
	RIGHT:	# 1 is a magic number
		a = 1

Commit scope and commig logs
----------------------------

Please take your time to make commit messages as meaningful as possible. 
Remember that what you write stays [almost] forever, so spend an extra minute
to save man-hours of decrypting vague or meaningless commit logs later.

Generally, each commit log should answer two questions:
 * Why was it necessary to make the change?
 * What was the change?

...thus you are expected to write at least two sentences in a commit log.

The answer to the "why" question should contain the issue number, if there is
relevant one.

Anyways, use your judgement: some obvious changes do not need verbose 
explanations and something fairly simple would suffice ("Doc typo fix", 
"Cosmetics", etc).

Make sure that your commit logs make sense (or are at least readable) without 
looking at the actual diff. Give some higher level context, not just describe
the details of the change. How does your small fix affect the user-visible 
behaviour of the system? Can you expain that in a few words to someone new in
the development team? Write down those few words into the commit log.

Another important topic, the commit scope, goes close here. When you are 
committing your changes, try to separate them into small independent parts. 
This is especially important with changes that affect both code logic and 
layout.

The usual rule of thumb when deciding on how to group changes is to answer the
question: "Is it convenient to review this set of changes?" If you wouldn't
feel comfortable reviewing the whole set, you should probably split it into
parts.

At the same time, you should try (but not obliged to) to keep the trunk working
at all times: e.g. more often than not the functional changes should be grouped
with the test changes. This also gives a reviewer a better insight on what the
changes are.


Reverting/resurrecting changes
------------------------------

When reverting changes use exact revision numbers in the commit log message.
"Reverted r1234" is preferred to "Reverted last fix".

When resurrecting changes _on_the_same_branch_, avoid using copies: this makes
history nonlinear complicating merging and tracking history later. In a 
scenario like:
$ touch file; svn add file; svn ci file -m "Added file"
...
Committed revision 1234.
$ svn merge -c -1234 .; svn ci -m "Reverted r1234"
...
Committed revision 1235.

...to resurrect 'file', use
$ svn merge -c 1234
$ svn ci -m "Resurrected r1234 which was reverted in r1235"
...
Committed r1236.

...instead of:
$ svn cp -r1234 file . # WRONG


Temporary changes
-----------------

Avoid committing temporary changes. This includes in particular blocks of
commented-out code.


The GOLDEN coding rule
----------------------

Never EVER duplicate any code. If you find yourself copying and modifying 
code snippets, or, even worse, copying them verbatim, stop right away. This is
usually a sign of poor design or lack of thourough thinking before making 
changes. Take the opportunity to refactor. It WILL payoff.

XXX: standardize the docstring format