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 "dep: foo-bar" field
  87 and press "gf" in your Vi editor to go to "foo-bar" directory of the
  88 dependant issue.
  89
  90           ------------------------ >8 ------------------------
  91
  92 "metas" script exports the whole issues database without about/result
  93 fields. "show" includes them. "full" also prepends *.rec files to the
  94 output. They are expected to be filtered with recsel/recdel utilities.
  95 "cd" lists all issues piped to "fzf" utility, that previews each one
  96 with "show" script.
  97
  98 Personally I "hash -d" schwabrak's directory to be able to quickly call
  99 commands from it:
 100
 101     $ hash -d s=~/work/schwabrak
 102     $ cd my/issues
 103     $ ~s/add issue name to create
 104
 105 To ease the creation of the new issue's directory structure, you can use
 106 "add" command as seen above. And yes, it is intended that "issue" and
 107 "name", "to", "create" can be passed as separate arguments, but
 108 issue-name-to-create will be created as expected.
 109
 110           ------------------------ >8 ------------------------
 111
 112 Person:         ~s/schemas | recsel -t person -e 'email ~ "stargrave"'
 113 Unfinished tasks: ~s/metas | recsel -e 'status != "done"'
 114 Full tasks info for person and project: ~s/full |
 115     recsel -t task -e 'ass = "stargrave" && proj = "tcl"'
 116
 117           ------------------------ >8 ------------------------
 118
 119 The "comment" issue's file is intended to keep the last comment related to
 120 the issue. By committing it you automatically accompany it with your
 121 (commit's author) name and the time it was added.
 122
 123     $ cat >issue-name/comment <<EOF
 124     Here are my thoughts:
 125     * bla bla bla
 126     EOF
 127     $ git commit issues-name/comment
 128
 129 And you can view all comments/authors history later just with:
 130
 131     $ git log -p issues-name/comment
 132