Code design workflow

This page describes the process for introducing large changes into PARPG.

Relevance
A large change is anything that requires design and discussion. Examples

Small changes
 * Fixing typos in comments.
 * Fixing graphical glitches.
 * Minor AI tweaks or parameter changes.
 * Whitespace changes.

Large changes
 * New module
 * Substantial refactoring

Obviously there is some grey area; but changes deemed large won't be accepted without going through this process (even if you have the code written).

Step one: Write a proposal

 * This doesn't have to be initially hugely detailed, it just has to give an idea of what it is you're trying to do, and how it will be structured.
 * Place your proposal in a wiki page called e.g. Proposal:, for example Proposal:VirtualFilesystem.
 * Flag the page with so other developers will be encouraged to review it and comment.

Step two: Post to the forums

 * Start a thread in the programming forums, and post a link to the page in the forums.
 * If what you're proposing impacts other departments (e.g. you want to change what kinds of graphical effects we can support, you want to change how the mechanics work) you should start a thread in those boards too.

Step three: Iterate

 * Refine your design in response to feedback.
 * This takes as long as it takes, until there's an agreement that
 * What you want to do is sensible.
 * What you want to do fits with the rest of the effort.
 * You're doing it in a useful way.

Step four: Upload patches

 * At some point you wrote the code for this feature, now's the time to make a patch and send it to the tracker.

Step five: Iterate

 * Your patch probably contains errors and poor code. Everyone's patches suffer from this sometimes. This is why we emphasise code review.

Step six: Document

 * Describe the design of what you've implemented.
 * Focus on the key objects and structures and the "big picture".
 * This should follow fairly straightforwardly from your proposal.
 * Don't emphasise the particular line by line coding.
 * Do include any particular reasons why things are as they are (e.g. "weird bug in this routine," "takes 50 times as long using this other algorithm i tried")

Step seven: Committed

 * After there's documentation, an agreed upon design, and an agreed upon patch, it will be committed to svn.