[schwabrak.git] / README

schwabrak -- simple flat file based issue tracker

I want a relatively simple issue/ticket tracker. Something like Trac,
Redmine or Fossil. But they require heavy dependencies (Python, Ruby),
database and they are centralised. You can not work with them offline
and it is relatively complicated to replicate data to a locally running
copy of any of those trackers (well, except for Fossil I believe). And
is a web-interface necessary at all?

What is a ticket/issue? Just some plain text descriptions, with
attached enumerations (statuses, assignments, priorities, projects,
subsystems, severities, resolutions, etc) and a pile of append-only
comments, possibly with another file attachments. Can all of that
live in a directory with several plain text files? Can it be linked
with other issues just by making a symbolic links in deps/ subdirectory?
Do Git commits provide supplementary metainformation about when and
by whom any of the change is made in that directory? Definitely yes!
And because of DVCS you get ability to keep the whole distributed copy
of the tracker on each developer's machine. You can send changes to it
asynchronously as a patch or bundle.

Basically schwabrak is mainly about a convention how to keep issues in
files, loosely similar to https://github.com/driusan/PoormanIssueTracker,
from which I borrowed idea of replacing spaces with dashes in issue names.

Issues are kept in the issues/ directory. Each issue can be a part of
projects hierarchy: main-project/sub-proj/issue-name. Directory's name
is the issue's brief name. Dashes should be interpreted as spaces and
n > 1 dashes should be interpreted as n-1 dashes when converting the
directory name to a human readable issue title, as PoormanIssueTracker
suggests. The "about" file contains the description of the issue. The
"result" (initially empty) contains the closed issue resolution
information.

The "created" issue's file contains the datetime it was created. It is
used to help sort issues by date. Unfortunately Git does not keep and
restore mtimes, which would probably eliminate the need of separate
files with the timestamps.

Each issue can have attached tags. For keeping their set in consistent
well-defined state, the tags/ directory above the issues/ contains
available tags for your projects.

    $ for tag in status:open status:done assignee:alice assignee:bob
        doc db test:integration severity:high severity:low ... ; do
            touch tags/$tag
    done

It is your choice how to name and deal with them. Want to find all
issues in done state? for i (issues/**/tags/status:done) print $i:h:h.
This kind of information are all just enumerations.

The deps/ subdirectory in each issue can contain symbolic links to
another issues, referencing it. Create another kind of links between
them as you wish.

Want to search among the issues? Just use git grep, or ordinary grep!
Want to search through attached PDFs or other kind of documents? You are
free to index issues/ directory with something like recoll. Want to see
the whole history of changes related to specific issues? Just run
git log issues/issue-name! You can add a tag by simply touching
issues/issues-name/tags/tag, but "tag-add" included in schwabrak creates
symbolic links to tags/tag and checks if the tag is known beforehand,
to keep the tags set consistent. Want to remove a tag? (git) rm
issues/issues-name/tags/tag!

The "comment" issue's file is intended to keep the last comment related to
the issue. By committing it you automatically accompany it with your
(commit's author) name and the time it was added.

    $ cat > issues/issues-name/comment <<EOF
    Here are my thoughts:
    * bla bla bla
    EOF
    $ git commit issues/issues-name/comment

And you can view all comments/authors history later just with:

    $ git log -p issues/issues-name/comment

Or by using "comment-list" command included in that distribution.
And of course you can add additional files with each commit.

schwabrak includes a bunch of utilities to slightly ease dealing with
all of that data. Personally I "hash -d" schwabrak's directory to be
able to quickly call commands from it:

    $ hash -d s=~/work/schwabrak
    $ cd my/issues
    $ ~s/add proj/issue name to create

To ease the creation of the new issue's directory structure, you can
use "add" command as seen above. And yes, it is intended that
"proj/issue" and "name", "to", "create" can be passed as separate
arguments, but proj/issue-name-to-create will be created as expected.

All utilities strip off possible "issues/" prefix from the issues
name, so you can easily complete issue names with something like fzf.
"cd" utility exactly runs fzf to show you available issues, outputting
path to selected one.

"list" lists all issues in tab separated format, sorting by descending
creation date and showing their tags. Optional arguments acts like a
filter for the issue's tags.

    $ ~s/list open stargrave !hidden

That will list all issues with the tags including "status:open" AND
"assignee:stargrave", AND excluding issues with the tags containing
"hidden". Each argument is an expression each issue's tag is compared to
(zsh'es "=~" test). Tag with "!"-prefix means that no tag should be in
issue's set.

"tag-list issue" prints issue's tags if any.
"tag-add issue [tags/]tag" adds a tag, as was noticed before.
"dep-add issue-dst issue-src" will link issue-src in issues-dst's deps/.
"show issue" shows most of issue's information in human friendly way.
"comment" allows you to conveniently add comment.

comment-list, recfile-export and recfile-export-all produces
recutils'es compatible recfile output, which is machine friendlier.