From 9f659c6a62d7f97f58a84b9dc4e4fc2d1a626824 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 27 Sep 2016 04:59:40 +0200 Subject: Document subdirectory note format (for keeping extra materials) --- README.cli | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'README.cli') diff --git a/README.cli b/README.cli index 91ae0f2..63c2e2f 100644 --- a/README.cli +++ b/README.cli @@ -116,10 +116,14 @@ The body of a note is free-form. However, for clarity, it makes sense to avoid using '\c{-}' for lists in the body ('\c{*}' for the first level and '\c{~}' 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 \c{list} files. These files can appear at the top level or in any subdirectory. More complex notes -can be placed in their own files. +can be 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 \c{list} file, then its body must be indented two spaces to align with the start of the summary. Notes are separated with blank @@ -167,7 +171,8 @@ 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 \c{list} file. Or we can move a note from \c{list} to its own -file. For example, if we start expanding on our \"Implement pluggable +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 \c{git} sense) changes to the database, use a separate @@ -188,7 +193,8 @@ If you only have a single issue added in the database then you can use the \c{add} script to automate it. This script will commit the new issues with the correct message and, unless the \c{-c} option is specified, push the result to \c{origin}. This should make filing new notes a fairly burdenless process: -write a note using your favorite text editor and run the \c{add} script. +write a note using your favorite text editor and run the \c{add} script. Note +that the \c{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 -- cgit v1.1