# Designing an issue tracker on gemini

Why do we want to consolidate issue trackers and kanban boards using gemini+git? Several reasons:

* Get rid of external web service dependencies (in our case github issue tracker and trello kanban)
* Track issues in text files - edit with your favourite editor
* Provide our own viewer - the github issue tracker and trello boards are not very configurable, e.g. what to do with a stale issue - why do we need to run an action?
* Clean up history
* Own the trackers

Now the last one may be the most important. Currently anyone can post on github issue trackers and you get issues like

=> https://github.com/genetics-statistics/GEMMA/issues/250 Not read the docs example

Where someone posts who has clearly not bothered read the manual (sorry). Or from another project I am involved in as a maintainer:

=> https://github.com/vcflib/vcflib/issues/206 Rude example

or from the same person

=> https://github.com/konradjk/loftee/issues/23 Another one

where someone is rude and lacks obvious knowledge about the free software effort (not so sorry about exposing this one --- luckily this concerns a small minority). One glaring problem is that github does not allow removing these controversial tracks. The problem with service providers, such as Microsoft owned github, is that you are bound by *their* rules.

With our new gemini tracker we own the issue reporting space. People can submit a request to report an issue and we can decide whether it belongs there or not. Takes a little more effort on the submitter too! But not too much - you have to know git or edit, fork or clone in github. The downside may be that some normal users feel they need to do too much. In that case one can always send an E-mail to the mailing list instead - or we create a web form that does that. In the next step we can file E-mails as issues ourselves.

Key point is that the issue tracker is meant to track issues owned by the project.

## Example

I added a first issue here:

=> https://github.com/genenetwork/gn-gemtext-threads/blob/main/issues/database-not-responding.gmi

## Process

We leverage git to pull out dates and people contributions (pjotrp wrote ...) for display in a document/web page. This page is generated:

=> ../tracker.gmi

To create the tracker we add tags:

* assigned: pjotrp, zachs
* keywords: critical bug, in progress
* milestone: 1.1

Which we can use to generate lists of links.

Make sense?

For the kanban board we can simply use the keywords. Override/add with a separate

* kanban: Brain storm

Keywords are fairly flexible, but common ones are

* request
* bug
* critical bug
* enhancement
* in progress
* testing
* later
* documentation
* help wanted
* closed

the keyword statement may have aliases, such as tag and kanban. To undo a keyword simply remove them from the file.

Can't think of anything more to add to make it really useful :)

## Tracking information

Git can do all of that. A viewer may benefit from serial git information, therefore it is recommended to add information at the end of the file. Though, unlike other issue trackers, this is not obligatory. One can insert notes using the '>' prefix

> This is a comment

Or one can simply use git blame to figure out who did what.

## Closing issues

Moving an issue file will disconnect the git record. Therefore simple add

* closed

## Converting github issues

### Converting issues from a github issue tracker

=> https://github.com/mattduck/gh2md Github to markdown dump