From a0ae430f01bb8ab0a98cce2203435a286dd89ff7 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 15 Sep 2016 03:29:20 +0200 Subject: Initial spec version and add script --- README | 238 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..0ef2788 --- /dev/null +++ b/README @@ -0,0 +1,238 @@ +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): + +['-'|'!'|'?'|'+'] [ '['