Outlying System Design

Table of Contents

  1. jiancha (检查)
    1. Concept
    2. Goals
    3. To do list
    4. Code Name
      1. jiancha
  1. 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
  1. Functional Specifications Document
    1. Review Commentary
    2. Review Process
    3. Rules Engine
  1. Jian Cha Research
    1. Code Review Research
    2. Code Review Systems
    3. Subversion access
    4. Repository Abstractions
      1. Properties
  1. 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 technical design of 检查.

Design Goals

The goal of 检查 is to introduce direct integration into trac, and in the spirit of trac, a number of source code management systems. Jiancha will support, wherever possible, criteria based enforcements by the Rules Engine for action automation.

SCM Abstraction

The future goal of supporting multiple SCM systems will need to be planned for *now*. Research for 检查 has determined that no suitable existing abstraction to either subversion or general SCM access exists. Our own read/write data repository access abstraction will be created.

SCM Interface

The SCM Interfaces need to abstract data access and planning from the actual code used to read the repository directly. The current plan of attack for the design of this API is to provide a series of interfaces modeling an object-oriented model of the C subversion API. Thanks to the hard work of the subversion developers, the API is quite consistent and wrapped into an object oriented interface by a direct datastructure/function mapping.

Here is the breakdown of existing datastructures, as referred to by the subversion API documentation, mapped to the interface names which will be created to represent this API.

C Implementation 检查 Abstraction
Data Structure Function Interface Method
svn_fs_root_t svn_fs_file_contents Revision open_read(path)
svn_fs_root_t svn_fs_apply_text Transaction open_write(path)
svn_fs_root_t svn_fs_copy Transaction copy()
svn_fs_root_t svn_fs_delete Transaction remove()
svn_fs_txn_t svn_fs_commit_txn Transaction commit()
svn_fs_txn_t svn_fs_abort_txn Transaction rollback()

Note: This is an incomplete list.

Subversion Abstraction

Subversion being the initial target of 检查, the SCM Interface_ has been designed with the requirements of supporting subversion in mind. Research has not determined that major requirements for other SCM systems will be overlooked given this approach.

Shelving

There is a popular feature called "shelves" that is a part of Microsoft Studio Team System. From the website:

Shelving allows you to place your checked out code in a "shelveset" located on the server, where it is maintained until you are ready to take it off the shelf. Essentially, this allows you to store work-in-progress code on a "shelf" in the server, without overwriting or corrupting existing code in the live tree.

The concept is quite similar to a development branch. This is the origin of the name for the process which will be used to manage changesets in 检查. In 检查 changes will be shelved, set aside in a datastore separate from the target SCM system. Unlike the shelves described on the MSDN website, 检查 shelves will consist of a set of changesets alone. Subsequent shelved changesets being considered a proposed change, and follow up proposed changes.

Shelving changesets in subversion

Subversion being the only target of concern for 检查's initial release, changesets in subversion can easily be intercepted using a precommit hook. Precommit hooks recieve information regarding the a current transaction, and have the opportunity to inspect this transaction and potentially, reject it.

Given critera that the Rules Engine determines to require a review, 检查 will extract the complete contents of all modified files from a transaction and store them creating a shelf. Once this shelf is created, the transaction can be aborted.

Rules Engine

A configuration based rules engine is required, which will determine, at minimum, the following.

Review requirements

During the inspection of a transaction_, the Rules Engine will determine whether or not a given review is required. The following criteria, at minimum, should be potentially subject to inspection.

  1. File type
  2. File meta-data (subversion properties)
  3. Author of changeset
  4. Full filename
  5. Contents modified

Commit passing

The process of determining when to create a review, disallowing a commit, must be accompanied by a similar rule check process which determines when a commit can be allowed. This includes possible forced error checking, such as the following.

  1. Referenced review exists
  2. Referenced review's last follow up matches transaction changeset
  3. Referenced review is of a satisfied state

Review satisfaction

During the review process, the [wiki:projects/JianCha/OSD#RulesEngine Rules Engine] given each modification to the state of a shelf will inspect the current state and perform an action_. The following criteria, at minimum, should be potentially subject to inspection.

  1. The number of currently unanswered comments
  2. The status of the shelf
    1. The number of reviewers which have approved the modification.
    2. The reviewers who have approved the code
  3. The authors of currently unanswered comments.