aboutsummaryrefslogtreecommitdiff
Version 1.0 This document describes the change development database and process. The main premise of the approach described here is that planning changes in code should be handled in the same way as changing the code itself; that is, using git(1) and our favorite text editors, rather than some external database accessible via a web interface (which what most bug trackers are these days). To be usable, the database format and process must not be burdensome. As a result, there is minimum notation as well as helper tools to automate common operations, for example, adding a new item (called a note). The database can either be stored in the git repository of the project itself or, if the project consists of multiple git repositories, in a repository of its own. In the former case it is recommended to place the database in the top-level subdirectory of a project and call it change. In the latter case it is recommended to call the repository change, potentially with a prefix denoting the overall project name, for example, hello-change. The change database is a collection of notes stored in plain text files that use a certain notation. The files are organized in subdirectories which are used to group notes that affect a certain subproject or an area of a project. For a database that covers multiple git repositories it is common to have top-level subdirectories named after those repositories. As an example, let's say we have a "Hello, World!" project that consists of two git repositories: the libhello library and the hello program. The resulting directory structure then could be: hello/ libhello/ change/ | |--hello/ | `--libhello/ Continuing with this example, inside libhello/ we could have subdirectories for major functionality areas: change/ | |--hello/ | `--libhello/ | |--format/ | `--print/ It seldom makes sense to have more than two levels of subdirectories. At the top level the subdirectory called reference is reserved for storing notes that have been acted upon. Its usage is described in more detail below. A note consists of a header and an optional body separated with a blank line. All lines in a note should be no longer than 78 characters. The header is always the first line and contains the note's severity, summary, and optional labels. The header has the following format (literal values are quoted): ['-'|'!'|'?'|'+'] [ '['