README

   1 schwabrak -- simple flat file based issue tracker
   2
   3 Note: this is the second version/iteration/suggestion.
   4 Look for previous one in older commits.
   5
   6 I want a relatively simple issue/ticket tracker. Something like Trac,
   7 Redmine or Fossil. But they require heavy dependencies (Python, Ruby),
   8 database and they are centralised. You can not work with them offline
   9 and it is relatively complicated to replicate data to a locally running
  10 copy of any of those trackers (well, except for Fossil I believe). And
  11 is a web-interface necessary at all?
  12
  13 What is a ticket/issue? Just some plain text descriptions, with attached
  14 enumerations (statuses, assignments, priorities, projects, subsystems,
  15 severities, resolutions, etc) and a pile of append-only comments,
  16 possibly with another file attachments. Can all of that live in a
  17 directory with several plain text files? Do Git commits provide
  18 supplementary metainformation about when and by whom any of the change
  19 is made in that directory? Definitely yes! And because of DVCS you get
  20 ability to keep the whole distributed copy of the tracker on each
  21 developer's machine. You can send changes to it asynchronously as a
  22 patch or bundle.
  23
  24 Basically schwabrak is mainly about a convention how to keep issues in
  25 files, loosely similar to
  26 https://github.com/driusan/PoormanIssueTracker
  27 https://github.com/driusan/IssueTrackerTools
  28 https://github.com/aaiyer/bugseverywhere
  29
  30 Each issue is kept in separate directory. Directory's name is the
  31 issue's brief name. Dashes should be interpreted as spaces and n > 1
  32 dashes should be interpreted as n-1 dashes when converting the directory
  33 name to a human readable issue title, as PoormanIssueTracker suggests.
  34
  35 The "about" file contains the description of the issue. The "result"
  36 (initially empty) contains the resolved issue information. The "meta"
  37 file contains metainformation in recfile format, having at least
  38 "created" fields. https://www.gnu.org/software/recutils/
  39
  40 Root directory should contain *.rec files with the schema of the
  41 records. For example:
  42
  43     person.rec:
  44         %rec: person
  45         %key: id
  46         %unique: name
  47         %mandatory: name email
  48         %type: id line
  49         %type: name line
  50         %type: email email
  51
  52         id: stargrave
  53         name: Сергей Матвеев
  54         email: stargrave@stargrave.org
  55
  56     task.rec:
  57         %rec: task
  58         %key: id
  59         %mandatory: name created
  60         %unique: name created about result
  61         %allowed: about result ass proj status
  62         %sort: created
  63         %type: id line
  64         %type: name line
  65         %type: created date
  66         %type: ass rec person
  67         %type: proj enum
  68         + c (C99)
  69         + go (Go)
  70         + py (Python3)
  71         + tcl (Tcl)
  72         %type: status enum
  73         + done (task is finished)
  74         + reject
  75         + wip (work in progress)
  76
  77 Schema of the issues/tasks must be trailing *.rec file after the sort.
  78
  79 Want to search among the issues? Just use git grep, or ordinary grep!
  80 Want to search through attached PDFs or other kind of documents? You are
  81 free to index issues directory with something like recoll. Want to see
  82 the whole history of changes related to specific issues? Just run
  83 git log issue-name!
  84
  85 You can edit meta files either manually (it is trivial text-based
  86 human-friendly format) or with recset utility. Add "deps: foo-bar" field
  87 and press "gf" in your Vi editor to go to "foo-bar" directory of the
  88 dependant issue.
  89
  90 "metas" script exports the whole issues database without about/result
  91 fields. "show" includes them. "full" also prepends *.rec files to the
  92 output. They are expected to be filtered with recsel/recdel utilities.
  93 "cd" lists all issues piped to "fzf" utility, that previews each one
  94 with "show" script.
  95
  96 The "comment" issue's file is intended to keep the last comment related to
  97 the issue. By committing it you automatically accompany it with your
  98 (commit's author) name and the time it was added.
  99
 100     $ cat >issues-name/comment <<EOF
 101     Here are my thoughts:
 102     * bla bla bla
 103     EOF
 104     $ git commit issues-name/comment
 105
 106 And you can view all comments/authors history later just with:
 107
 108     $ git log -p issues-name/comment
 109
 110 Personally I "hash -d" schwabrak's directory to be able to quickly call
 111 commands from it:
 112
 113     $ hash -d s=~/work/schwabrak
 114     $ cd my/issues
 115     $ ~s/add issue name to create
 116
 117 To ease the creation of the new issue's directory structure, you can use
 118 "add" command as seen above. And yes, it is intended that "issue" and
 119 "name", "to", "create" can be passed as separate arguments, but
 120 issue-name-to-create will be created as expected.