Functional Specifications Document

Table of Contents

  1. jiancha (检查)
    1. Concept
    2. Goals
    3. To do list
    4. Code Name
      1. jiancha
  2. Requirements
    1. Interface Requirements
      1. Automated Submission
      2. Per change review commentary
      3. Suggested modifications
      4. Viewing change context
      5. Multiple attempts per review
    2. Business Requirements
      1. Criteria for Automated Committal
      2. Follow up committal
      3. Suitable review trail
      4. Repository Abstraction
    3. Technical Requirements
      1. Changeset Storage
  3. Functional Specifications Document
    1. Review Commentary
    2. Review Process
    3. Rules Engine
  4. Jian Cha Research
    1. Code Review Research
    2. Code Review Systems
    3. Subversion access
    4. Repository Abstractions
      1. Properties
  5. Outlying System Design
    1. Design Goals
    2. SCM Abstraction
      1. SCM Interface
      2. Subversion Abstraction
    3. Shelving
      1. Shelving changesets in subversion
    4. Rules Engine

This document will outline the functional requirements of 检查.

Review Commentary

The review commentary should provide nearly real time discussion of suggested changes as well as provide alternative suggestions.

The commentary approach may require users to super-impose a review on top of another. This may quickly become very difficult to handle if not properly approached and necessarily optimized from the beginning. For instance, applying a 10 level deep series of patches to patches in order to display not only a review but it's suggested changes could quickly become a runtime responsiveness challenge.

Note: This may not be worthwhile for initial release, to be determined

Review Process

The goal the actual process is for it to be re-definable and have a variable amount of ceremony. Low ceremony isn't precisely the goal, but flexible ceremony is. It's desired to offer a re-arrangable review process, for the time being I believe this may be accomplished from creating a powerful and flexible enough rules engine alone.

Rules Engine

A part of Jian Cha is a required rules engine. This rules engine must read a configuration (static, or dynamic) which is user managed to dictate the requirements for review submission and the unconditional requirements for approval. There also should more than likely be atleast some level of "warnings", a way to create a criteria that flags an approved commit as fitting all unconditional requirements but not all suggested requirements.

The complexity of this rules engine can grow rapidly and this is quite obviously a screaming area for the introduction of feature creep. For the time being and to avoid feature creep the rules engine is required to do very little other than provide required criteria based upon specific data stored about each review, such as it's flags — number of comments — approvals (and level(s) of approval) — and similar rules that are static and low overhead in nature. The initial rules engine should do no source code analysis, no negative keyword or other scanning, but allow flexible rules to be defined.

This should hopefully be a flexible enough engine to introduce in the near future the ability to greatly extending the rules engine, however nothing is currently required of it other than a well planned API that can be maintained and hopefully will not require major revision when more flexibility is introduced to the engine.