Hi,
I want to share some over-arching themes and ideas as well as be more
explicit about certain development processes. The easiest place to start
is to emphasize certain well known patterns (so please excuse the
sprinkling of 'buzz words') that I feel are of particular importance.
When evaluating contributions, these five things should be considered by
the reviewerin addition to their standard review criteria:
- loose coupling and high cohesion: "Cohesion of a single
module/component is the degree to which its responsibilities form a
meaningful unit; higher cohesion is better. Coupling between
modules/components is their degree of mutual interdependence; lower
coupling is better."[1]We should aim to be highly resilient.
- less code: Less code provides a number of benefits such as reducing
risk, making it easier to find what you're looking for, etc. We should
look to use as little code as possible without compromising the
readability of our code.
- DRY (Don't Repeat Yourself). "Every piece of knowledge must have a
single, unambiguous, authoritative representation within a system."//[2]
- consistency: Highly important to be consistent at all levels;
compromising consistency should not occur.
- simplicity: Code should be self-documenting (and interfaces / APIs
should be documented in docstrings of course). We should aim to have a
very easy to read codebase. Keep things simple. You can always come back
and make things more complicated later when doing so actually provides
value.
Some of our over-arching architectural themes (some of which are not
realized) include:
- Via loose coupling, high cohesion, and the 'django application'
construct I'd like to be able to easily mash-up different discrete
pieces of functionality to provide Offspring instances that are highly
configured to a specific paradigm or use case.
- Offspring is not a TDD project but TDD is recognized as an effective
tool in the toolbox.
- The trunk should be 'pristine' / 'clean'. This is to say that we
should try to keep trunk in a "releasable" state. This is especially
important since we currently do not perform discrete releases. New
features and non-trivial bug fixes should be developed in a separate
branch and only merged into trunk in complete, logical chunks that
provide substantial value. People should be able to run production sites
against the trunk at any time.
- Code should be written defensively. Don't code in a hurry, trust no
one, predict possible error scenarios, and write code for clarity
instead of brevity.
- Write tests but remember that every decision we make every day is a
multivariate optimization problem. Choose to capitalize or mitigate risk
as appropriate and avoid writing tests that actual have a greater
cost/risk than value.
When it comes to actually contributing code to the Offspring project,
here are the important bits:
- For any medium-to-big changes (such as a new feature), please bring it
up on this mailing list before moving forward with making the changes.
I'll aim to respond within a week on the feasibility / possible road map
for the changes to make it into trunk if the change were implemented.
- Separate bug fixes (including aesthetic changes) from feature changes.
- Limit commits to the most granular change that makes sense. When
merging into trunk, apply a similar principle - split into complete,
logical chunks that provide substantial value.
- We use bzr for revision control. It is a distribution revision control
system. It is highly encouraged to take advantage of the features this
provides when developing changes you'd like to see incorporated into
Offspring trunk. Sometimes changes can not be immediately accepted into
trunk and by keeping trunk a common denominator we make it easy for
folks to follow and base their deployments off of trunk.
- Trivial changes do not require code review but all other changes do.
Any developer with commit access may review and approve for landing
small-to-medium changes. Larger changes and all new features need to be
discussed on the mailing list and should receive an architectural review
from myself.
- Merge proposals should have a 'cover letter' that describes the
changes and explains any design decisions, assumptions, etc. made by the
implementer. Additionally, a commit message should be set.
- To have your code accepted into trunk, the author must have signed the
Canonical contributor agreement (either directly or via an agreement
with their employer as appropriate).
Additionally, I'd like to note the following:
- The private Launchpad project used to manage Offspring development
before it was open sourced still contains bugs related to Offspring. It
is my intention to move these over to the public Offspring project this
month as appropriate.
- There have been some commits to trunk recently that don't quite meet
some of the requirements I've discussed above (which I'll discuss
further in a separate e-mail).
- This year I'd like to work towards producing actual, discrete releases
of Offspring that are easy to install and setup.
[1] http://c2.com/cgi/wiki?CouplingAndCohesion
[2] http://c2.com/cgi/wiki?DontRepeatYourself
Cheers,
--
Cody A.W. Somerville
Release Engineer
Commercial Engineering
Canonical Canada Ltd.
Phone: +1 781 850 2087
Cell: +1 613 401 5141
Fax: +1 613 687 7368
Email: cody.somervi...@canonical.com
--
Mailing list: https://launchpad.net/~offspring-hackers
Post to : offspring-hackers@lists.launchpad.net
Unsubscribe : https://launchpad.net/~offspring-hackers
More help : https://help.launchpad.net/ListHelp
