Process Proposal

Micah's Section

Introduction

This is basically an elaborated version of what I wrote up on Bonnie's whiteboard on Monday. (I currently have a more detailed version up on the whiteboard in my room, if you prefer a visual representation).

Some of this we have already been doing informally and less systematically. I think it is valuable to explicitly state and formalize our process, so that we can more easily see areas that could use improving.

Below I will give a basic overview of the general process, followed by a more in-depth description of how each step in the process might be executed.

Process Overview

The basic process for new tasks is as follows: Task Creation -> Requirements Specification -> High-level Technical Design -> Implementation -> User feedback -> Documentation -> Project completed

Each task is represented as a ticket on trac. The ticket is the central location to keep track of all information related to the task. As the ticket moves through the various phases, information from each phase is either linked to or directly posted on the ticket.

Note that for minor bug fixes, this process is not applicable, since fixing bugs generally does not involve user requirements gathering, high-level design, or significant documentation. Minor bug fixes should simply be posted (with detailed bug report info), implemented, and tested. This document refers to more involved projects.

Task Creation

In the task creation phase we know we want something, but we haven't formally worked out any of the details surrounding it. This isn't so much an active step as it is a starting point. It could be something like "I want a layercake visualization", or "we need to have a preferences system". At this point a ticket for the task is added to trac.

Requirements Specification

At this stage we investigate the task, and determine exactly how we want it to be done from a user perspective. For new features, this most likely involves developers discussing or somehow communicating with the end-user (usually Katy), and determining how exactly we want the feature to work. The developers and the end-user should agree on which features are reasonable to implement, and in what way those features should be exposed to the user (use cases). The developer should understand what the end-user wants.

Preferably at this point some sort of written requirements will have been generated, which can then be attached to the corresponding trac ticket. Moving a trac ticket out of this stage signifies that the requirements are final, and should not be changed until the user feedback stage (of course if the developer requests some clarification or re-evaluation during the design or implementation phase, requirements can still be altered. This should not be used as an excuse for inadequately specifying requirements from the beginning however).

If the project is large enough, at either the beginning or end of the requirements specification phase we may want to break the project into sub-tasks, where each sub-task has its own ticket, and possibly its own unique requirements information. Projects of this scale are somewhat outside the scope of this document, but should be easy to incorporate into the process.

Technical Design

At this stage, the developer(s) come up with a high-level technical design for the project. The level of up-front design required will depend on how large the project is. If the project is non-trivial the initial design should be attach to the trac ticket, and the proposed design should be checked over by an outside party. Only once there is consensus on the design should the ticket be moved to the implementation phase.

Implementation

At this stage we do the actual coding. The exact methodology should be up to the developer, but in general it will most likely look something like the following:

1. Do an appropriate amount of level-level design. 2. Write the actual code. 3. Test the code. 4. Repeat until you believe the code does what it is suppose to do.

Depending on the size of the project, we may want to implement peer-review of the code itself, either during the writing of the code, or at the end of the implementation phase. The peer-reviewer should either review the code through the repository, or preferably go through the code with the original developer in person. The original developer should discuss the overall design of the code, and the peer-reviewer should look for any possible issues or improvements. After (or during) the review session, the original developer should make appropriate changes to the code, and then have it peer reviewed again. When the peer-reviewer believes the code to be of a high enough quality, the peer-reviewer "signs off" on the code, and the trac ticket is moved to the user feedback phase.

User Feedback

In this phase the developer presents the finished product to the original end-user. If the end-user is satisfied with the result, we move the trac ticket to the documentation phase. If the end-user is not satisfied, we determine what needs to be changed, going as far back in the process as is necessary to implement those changes (If it is a minor change, simply re-implement without a peer-review. If the end-user requests a major change we may need to treat it as a whole new task. etc...).

Documentation

In this phase we write documentation for the project, and put it in the necessary places, adding user documentation for user-facing features, and adding developer documentation. If the feature is mainly used by developers, the developer documentation should be significant, however if it is mainly for use by users only a very high-level brief documentation should be needed. Any documentation at a lower level than this should probably be found in the code itself.

Depending on how significant the documentation was, the documentation may need to be reviewed by an outside party, and rewritten until it is of a high enough quality. At the point the project is completed. The documentation should be linked to on the trac ticket, after which the trac ticket can be closed.

(Check Russell's section for details on what documentation we need, and how it should be managed).

Project completed

We're done!

Russell's Section

===Parts ===

Specification covers what needs to be done to get work started on a proposal, including how that proposal is updated during other parts of the process.

Implementation deals with practices involved in programming, writing, and editing materials that implement a proposal.

Evaluation specifies the vetting of implementation artifacts.

Deliverables enumerates the implementation artifacts that must pass vetting before a proposal is completed.

Specification

Specification documents should always end up attached to bug reports, and will often be based on bug reports. For certain sorts of fixes, the initial bug report is sufficient. There isn't some hard and fast rule for when that is so. Judgement will be required.

Implementation

Evaluation

Most types of items for evaluation should probably have an 'owner'. For instance, one person should 'own' evaluation of development pages, since those have similar requirements, and a certain consistency is easiest to come about among multiple author if there is one enforcer. For wiki'd docs, this person should be keeping on eye on recently changed pages in their demesne as well as evaluating when pages are newly completed by an author.

For any major functionality (starting at major alterations to algorithms and new algorithms, and going upwards), part of the evaluation should be the author(s) walking one or two people through a workflow involving the functionality. For many algorithms, this workflow will be simple -- load graph, run algorithm -- but people are encouraged to do something a bit more complex, using a 'real' data set if available, and going for a 'useful' outcome.

Deliverables

For new algorithms (and other plugins), the following deliverables:

• An implementation of the plugin
• A development page for the plugin on the Trac wiki, with the changeset showing (once the appropriate Trac plugin is installed)
• if the plugin is to be used by developers in some way, the start of documentation (particularly a howto) on the developer documentation part of whatever wiki the developer documentation goes on
  • this should link to the development page, which should link to this
• For all public-facing plugins, a description page on the community wiki
  • this should link to the development page, and vice versa
• If the plugin is a core part of a workflow, the start of documentation (particularly a tutorial) on the user guide part of whatever wiki the user guide goes on
  • there should be links between this and the description page
  • if it fits well into one or more other workflows, it should be added to those