aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2016-09-27 04:59:40 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2016-09-27 05:01:20 +0200
commit9f659c6a62d7f97f58a84b9dc4e4fc2d1a626824 (patch)
tree82260d204d985d49f0c625a9c535e8855b418eff /README
parent257029ab098eccb41e26d2291ac99ee48f40d058 (diff)
Document subdirectory note format (for keeping extra materials)
Diffstat (limited to 'README')
-rw-r--r--README18
1 files changed, 12 insertions, 6 deletions
diff --git a/README b/README
index 0ef2788..c75e205 100644
--- a/README
+++ b/README
@@ -93,10 +93,14 @@ The body of a note is free-form. However, for clarity, it makes sense to avoid
using '-' for lists in the body ('*' for the first level and '~' for the second
level are good options).
-Notes can be saved in two ways. Simple notes without a body or with a body
+Notes can be saved in three ways. Simple notes without a body or with a body
containing one or two paragraphs can be written in the list files. These files
can appear at the top level or in any subdirectory. More complex notes can be
-placed in their own files.
+placed in their own files. Finally, notes that have addition material (what
+traditional bug trackers would call "attachments") should be placed into their
+own subdirectories with both the directory and the note file (inside that
+subdirectory) having the same name. Other than that, such a subdirectory is
+free form; it can contain other files and subdirectories.
If a note is written in the list file, then its body must be indented two
spaces to align with the start of the summary. Notes are separated with blank
@@ -139,9 +143,10 @@ to bump at least the minor version.
Note also that we can move notes freely between files. For example, we may add
a new subdirectory and move all the notes that affect this functionality from
-the top-level list file. Or we can move a note from list to its own file. For
-example, if we start expanding on our "Implement pluggable formatter" idea,
-then it probably makes sense to move it into its own file.
+the top-level list file. Or we can move a note from list to its own file or
+from a file to a subdirectory if we need to keep some additional files with the
+note. For example, if we start expanding on our "Implement pluggable formatter"
+idea, then it probably makes sense to move it into its own file.
When committing (in the git sense) changes to the database, use a separate
commit for each note. When committing a newly added note, the commit message
@@ -157,7 +162,8 @@ If you only have a single issue added in the database then you can use the add
script to automate it. This script will commit the new issues with the correct
message and, unless the -c option is specified, push the result to origin. This
should make filing new notes a fairly burdenless process: write a note using
-your favorite text editor and run the add script.
+your favorite text editor and run the add script. Note that the add script
+currently cannot handle notes with extra files.
Once a note is acted upon (implemented or you have decided not to do anything
about it), you can either delete it or move it to the reference. Simply