path: root/posts/2009-11-17-sd-the-peer-to-peer-bug-tracking-system.org

SD is a peer to peer bug tracking system build on top of Prophet.
Prophet is A grounded, semirelational, peer to peer replicated,
disconnected, versioned, property database with self-healing conflict
resolution. SD can be used alone, on an existing bug tracking system
(like RT or redmine or github) and it plays nice with git.

Why should you use SD ? Well, at
$work</a> we are using <a href="http://www.redmine.org/">redmine</a> as our ticket tracker. I spend a good part of my time in a terminal, and checking the ticket system, adding a ticket, etc, using the browser, is annoying. I prefer something which I can use in my terminal and edit with my <a href="http://www.vim.org/">$EDITOR.
So if you recognize yourself in this description, you might want to take
a look at SD.

#+BEGIN_QUOTE
  In the contrib directory of the SD distribution, you will find a SD
  ticket syntax file for vim.
#+END_QUOTE

** how to do some basic stuff with sd

We will start by initializing a database. By default

#+BEGIN_EXAMPLE
    % sd init
#+END_EXAMPLE

will create a /.sd/ directory in your $HOME. If you want to create in a
specific path, you will need to set the SD\_REPO in your env.

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd sd init
#+END_EXAMPLE

The init command creates an sqlite database and a config file. The
config file is in the same format as the one used by git.

Now we can create a ticket:

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd ticket create
#+END_EXAMPLE

This will open your $EDITOR, the part you need to edit are specified.
After editing this file, you will get something like this:

#+BEGIN_QUOTE
  Created ticket 11 (437b823c-8f69-46ff-864f-a5f74964a73f) Created
  comment 12 (f7f9ee13-76df-49fe-b8b2-9b94f8c37989)
#+END_QUOTE

You can view the created ticket:

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd ticket show 11
#+END_EXAMPLE

and the content of your ticket will be displayed.

You can list and filter your tickets:

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd ticket list
    % SD_REPO=~/code/myproject/sd search --regex foo
#+END_EXAMPLE

You can edit the SD configuration using the config tool or editing
directly the file. SD will look for three files : /etc/sdrc, $HOME/.sdrc
or the config file in your replica (in our exemple,
~/code/myproject/sd/config).

For changing my email address, I can do it this way:

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd config user.email-address franck@lumberjaph.net
#+END_EXAMPLE

or directly

#+BEGIN_EXAMPLE
    % SD_REPO=~/code/myproject/sd config edit
#+END_EXAMPLE

and update the user section.

** sd with git

SD provides a script for git: /git-sd/.

Let's start by creating a git repository:

#+BEGIN_EXAMPLE
    % mkdir ~/code/git/myuberproject
    % cd ~/code/git/myuberproject
    git init
#+END_EXAMPLE

SD comes with a git hook named "git-post-commit-close-ticket" (in the
contrib directory). We will copy this script to .git/hooks/post-commit.

now we can initialize our sd database

#+BEGIN_EXAMPLE
    % git-sd init
#+END_EXAMPLE

git-sd will try to find which email you have choosen for this project
using git config, and use the same address for it's configuration.

Let's write some code for our new project

#+BEGIN_SRC perl
    #!/usr/bin/env perl
    use strict;
    use warnings;
    print "hello, world\n";
#+END_SRC

then

#+BEGIN_EXAMPLE
    % git add hello.pl
    % git commit -m "first commit" hello.pl
#+END_EXAMPLE

now we can create a new entry

#+BEGIN_EXAMPLE
    % git-sd ticket create # create a ticket to replace print with say
#+END_EXAMPLE

We note the UUID for the ticket: in my exemple, the following output is
produced:

#+BEGIN_QUOTE
  Created ticket 11 (92878841-d764-4ac9-8aae-cd49e84c1ffe) Created
  comment 12 (ddb1e56e-87cb-4054-a035-253be4bc5855)
#+END_QUOTE

so my UUID is 92878841-d764-4ac9-8aae-cd49e84c1ffe.

Now, I fix my bug

#+BEGIN_EXAMPLE
    #!/usr/bin/env perl
    use strict;
    use 5.010;
    use warnings;
    say "hello, world";
#+END_EXAMPLE

and commit it

#+BEGIN_EXAMPLE
    % git commit -m "Closes 92878841-d764-4ac9-8aae-cd49e84c1ffe" hello.pl
#+END_EXAMPLE

If I do a

#+BEGIN_EXAMPLE
    % git ticket show 92878841-d764-4ac9-8aae-cd49e84c1ffe
#+END_EXAMPLE

The ticket will be marked as closed.

** sd with github

Let's say you want to track issues from a project (I will use Plack for
this exemple) that is hosted on github.

#+BEGIN_EXAMPLE
    % git clone git://github.com/miyagawa/Plack.git
    % git-sd clone --from "github:http://github.com/miyagawa/Plack"
    # it's the same as
    % git-sd clone --from "github:miyagawa/Plack"
    # or if you don't want to be prompted for username and password each time
    % git-sd clone --from github:http://githubusername:apitoken@github.com/miyagawa/Plack.git
#+END_EXAMPLE

It will ask for you github username and your API token, and clone the
database.

Later, you can publish your sd database like this:

#+BEGIN_EXAMPLE
    % git-sd push --to "github:http://github.com/$user/$project"
#+END_EXAMPLE

Now you can code offline with git, and open/close tickets using SD :)