Requirements

This document will itemize the interface, business and technical requirements (and desirable functionality) of jian cha.

Interface Requirements

These are the requirements of interacting with the application, through UI, APIs CLIs or forms of interfaces.

Automated Submission

Currently being discussed is automated submission of reviews through subversion precommit hooks. An automated submission mechanism (one that does not require logging in to trac) is definitely a functional requirement in order to facilitate the adoption of jiancha.

Per change review commentary

The ability to comment on a line of an incoming diff and create a thread of comments regarding an initial comment is required.

Notes

• It appears as though the diff changeset component of trac may be sufficiently reusable to employ for this purpose.
• It appears that the mechanism for acquiring diffs being used here is implemented in python using the built in Sequence Matcher component.
• It also appears some subclassing and general hackery may be required to actually use the diff extracted from the transaction. The subversion transaction has a short lifespan. This is required in order to render each review.
• It also appears that enough work as gone into this piece of code that using it probably favorable regardless of exchanges with code clarity.

Suggested modifications

An interface is required for tracking suggested modifications. Depending upon the level of difficulty, it might be worth while to have the ability to simply make these changes through the user interface.

Viewing change context

Shelved changesets currently being reviewed should be viewable within the full context of the given file. Additionally, a complete copy of the repository at a given root, with the shelved changeset applied to the transaction root, should be downloadable as an archive. Currently, trac's browser has a large subset of these features.

Providing this feature will greatly increase the usability of this system, as it's difficult to both verify changes are accurate without the context and test them without being able to download an archive.

Additionally, downloading the given changeset as unified diff should be a requirement.

Multiple attempts per review

The ability to link a series of changes to an existing review ("Ok, I fixed it") is a hard requirement.

Ideas

• Current thinking is that this will best be implemented by allowing a user to resubmit a review, putting in the commit message a review id. The review id will be looked up in the pre-commit hook, and if the review isn't approved then it would submit the transaction as a follow up to the existing review.

Business Requirements

These are (potentially and probably flexible) business rules for the application.

Criteria for Automated Committal

Given a set of criteria for a review, when the criteria are met (appropriate level of signoff) automated committal of the change being reviewed is to take place.

This mechanism should be circumventable

Ideas

• If the submission is implemented through an svn precommit hook, we can arbitrarily "suspend" the commit by creating a review from the proposed changes. This hook would ignore incoming commits which either fit the criteria of something that doesn't require a review or links to a valid review.
• Changes signed off on should get a tag inserted into the commit message which links directly to a given review. The trac component architecture should support this relatively well, by creating a review: trac link.

Follow up committal

Given a suitable "approval" where the approval requires a follow up (say a small scale change such as, "Change X and then go ahead") it should be allowable to commit, tagging the commit with the given review. The jiancha would possibly verify at this point that the same file modification set was made, and optionally that the MD5 sum of the file(s) with suggested modifications do not match. This change could automatically post as a follow up to the existing review without re-opening it.

Suitable review trail

There should be a simple and easy to use method for tracing a change back to its review (given a review existed for it's change), including any commentary from the review and who signed off on the changes.

Repository Abstraction

System should use a dynamic data access strategy for from or writing to the repository filesystem under any and all circumstances. This will promote the possibility of exposing various other revision control systems in the future.

Note that the requirements of jiancha are greater than that of trac, and such trac's read-only abstractions cannot be used. The possible simulation of transactionality should be core to the abstraction, although it's implemented in subversion directly it may not be in other systems. The ability to abort modifications and build transactions ourself if need be is key. Additionally, the ability to look up an existing transaction and modify or abort it is required by our subversion requirements.

Technical Requirements

These are few. This section is mostly used for assessing feasability of technical ideas before they get into the OSD.

Changeset Storage

Currently, it's considered entirely too difficult to store the actual delta of a changeset, as opposed to the contents of files changed.

Applying a raw delta to a given revision root requires a transaction to be created, and thus will not work repeatedly when changesets go stale. Additionally, the expense of storing the entire contents of a file may not be excessively great. So for the sake of simplicity, storing the actual file contents at the point of the shelved changeset is created is preferable.

Applying a changeset delta to a given revision root would be required for support of the interface requirements above, unless a ground-up implementation was created. Reason being the trac hdf_diff() function accepts two entire file contents in order to generate context, and rewriting the functionality of hdf_diff() and the other diff generating utilities is likely not even nearly worthwhile for the initial release.