aboutsummaryrefslogtreecommitdiff
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
parent257029ab098eccb41e26d2291ac99ee48f40d058 (diff)
Document subdirectory note format (for keeping extra materials)
-rw-r--r--README18
-rw-r--r--README.cli14
2 files changed, 22 insertions, 10 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
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