gemtext in tissue issue tracker
2024-06-01 @rrobin
The tissue issue tracker stores issues as gemtext files in a git repository, it serves them as a web page and provides a CLI tool to manage them.
Gemtext is not a very powerfull format, it only supports text, bullet points, titles, links and blocks.
Tissue overcomes its limitations with some conventions. Metadata is encoded in bullet points, these have special meaning:
The other convention encodes tasks, their description and state:
There are also some shorthand forms e.g. this is also valid to close a ticket
Issues
Issues are read by the read-gemtext-issue function:
I am not familiar with guile's define-class, but these seem to be the components of an issue:
that is
- a gemtext document as read by the read-gemtext-document function
- who is assigned to the issue
- a list of keywords
- number of tasks and completed tasks
I find this easier to read in the issue read function
That is the following information
- the path of the file
- a title whith fallback to filename
- the assigned handler for the ticket
- a list of keywords (from which "closed" is excluded)
- the status of the ticket i.e. it is open unless the closed keywork exists
- the number of tasks and completed tasks
- the commits associated with this issue
- a text snippet
The function that extracts this metatadata from the file is file-details
file-details
As the documentation states this function returns an hash-table, generated from the file contents:
I am not familiar with transducers in guile/scheme but port-transduce seems to be processing one line at a time (get-line-dos-or-unix) from the input and using the provided lambda on each line:
this function goes along mutating the result hashtable
- preformatted blocks of lines are ignored
- tasks are counted
- keywords are added to the keywords list (see hashtable-prepend!)
- the first title in the file is used as title
There are some special rules in place as well
- 'assign' and 'assigned' are equivalent (stored as status)
- likewise for 'keyword', 'keywords', 'severity', 'status' (stored as keywords)
Finally there is a search for keywords in lists of keywords separated by commas:
file-document-commits
There also a reference to file-document-commits that is used to get a list of commits that relate to the gemtext file. This is first seen in the file-document class definition
and it is initialized during document creation based on commits-affecting-file
I did not look deeper into this but it seems to be derived from a map of files to related commits created by file-modification-table:
References
https://git.systemreboot.net/tissue/
https://tissue.systemreboot.net/
https://tissue.systemreboot.net/manual/dev/en/
https://www.gnu.org/software/guile/manual/html_node/SRFI_002d171.html
Metadata
- commit: 62116be7fca25c78d1a72ddbc19282676b2ac729
- keywords: review, scheme