{"id":22293636,"url":"https://github.com/xi/git-tickets","last_synced_at":"2025-03-25T22:18:22.289Z","repository":{"id":150048260,"uuid":"97397312","full_name":"xi/git-tickets","owner":"xi","description":"track tickets in a plain text format within a git repository","archived":false,"fork":false,"pushed_at":"2017-07-16T17:43:35.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-30T19:24:27.893Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-16T16:53:12.000Z","updated_at":"2020-04-09T16:36:05.000Z","dependencies_parsed_at":"2023-04-25T00:03:15.015Z","dependency_job_id":null,"html_url":"https://github.com/xi/git-tickets","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xi%2Fgit-tickets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xi%2Fgit-tickets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xi%2Fgit-tickets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xi%2Fgit-tickets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xi","download_url":"https://codeload.github.com/xi/git-tickets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245550681,"owners_count":20633883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T17:30:08.856Z","updated_at":"2025-03-25T22:18:22.270Z","avatar_url":"https://github.com/xi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# git-tickets\n\nThis repository contains a spec to track tickets (bugs, pull-requests, …) in a\nplain text format within a git repository.\n\n\n## Spec\n\nTickets are tracked in a dedicated branch named \"tickets\".\n\nThe \"tickets\" branch contains one file per ticket. The filenames are\nincrementing numbers starting with 1. There are no other files or directories\nin the \"tickets\" branch.\n\nA ticket file is a minimal [mbox]-like file. Metadata is encoded as headers in\nthe first message:\n\n-\t`Subject`: The title of the ticket [required]\n-\t`Author`: The author of the ticket (probably the same as mentioned in the\n\t`From_` line) [requried]\n-\t`State`: Either \"open\", \"closed\", or some custom value [default: \"open\"]\n-\t`Assignee`: The person this ticket is assigned to\n-\t`Labels`: A comma-separated list of labels (e.g. \"bug\", \"duplicate\",\n\t\"wontfix\")\n-\t`Branch`: Associate this ticket with the given branch, making this a\n\tpull-request\n\nHeaders SHOULD be capitalized.  They SHOULD NOT be folded to allow simple\nline-based operations on them.  The `Orig-Date` and `From` headers SHOULD be\nomitted.\n\nAny subsequent messages (\"comments\") SHOULD NOT contain any of these headers.\nMessages SHOULD be separated with two blank lines.\n\nThe body of a messages SHOULD use the [commonmark] format.\n\nCommit messages related to tickets SHOULD conform to the general format\n`{Action} #{Number} [- {Title}]`, e.g. `Open #12 - Add mail support`.\n\n\n## Example ticket file\n\n\tFrom someone@example.com Mon Jul 17 13:00:00 2017\n\tSubject: Add mail support\n\tAuthor: someone@example.com\n\tState: closed\n\tLabels: enhancement,wontfix\n\n\tIf it ain't got mail support, I won't use it!\n\n\n\tFrom xi@example.com Tue Jul 18 14:00:00 2017\n\n\tIt was a design decision to not do this. Closing as wontfix.\n\n\n## Tooling\n\n-\tRun `git checkout --orphan tickets` to create the \"tickets\" branch.\n-\tRun `git fetch origin tickets \u0026\u0026 git diff tickets origin/tickets` to see what\n\tchanged since your last pull.\n-\tRun `mutt -R -f {ticket}` to read the conversation in [mutt].\n-\tThe script `git-tickets` included in this repository is useful to filter and\n\tlist tickets. It will only list open tickets by default.\n-\tThe script `import-github.py` included in this repository can be used to\n\timport issues and pull-requests from github.\n-\tIf you are using gitolite, add the line `RW tickets = @all` to a repo's\n\tconfig in order to allow people to create tickets.\n\n\n## Design and Reasoning\n\nThe main idea behind the design is simplicity. This is expressed on different\nlevels:\n\n-\tNo tools other than git and a text editor should be required.\n-\tAdditional (optional) tools should be simple to create and use.\n-\tThe structures are very much inspired by github, notably:\n\t-\tlinear discussions\n\t-\tcustomizable labels instead of complex taxonomies\n\t-\tticket IDs are incrementing numbers\n\t-\tformatting with commonmark\n\t-\tsimple references to tickets, users, and code [not yet done]\n\n\n## FAQ\n\n### `ls` just shows me a list of numbers. How am I supposed to find relevant tickets?\n\nThis format was chosen so that conflicts are automatically detected by git. It\nis true that it is somewhat ugly though. This is why I wrote the `git-tickets`\nscript.\n\n### I can change old messages, even by other people! That must be a bug, right?\n\nThis is actually intentional. In the case of metadata, this is even the only\nway to do it.\n\nSometimes people create badly formatted (or even invalid) tickets. And of\ncourse there is the problem of spam. There could be a sophisticated moderation\nsystem, but just editing plain text files is so much simpler.\n\nAlso note that any changes can be tracked in the git history.\n\n### How can I edit code and tickets at the same time.\n\nThis is a clear disadvantage of this approach: You cannot easily switch\nbetween regular code and the \"tickets\" branch. You can have a second clone of\nthe repo though.\n\n### Using git for authentication is a high barrier for reporters.\n\nYes and no.\n\nMany people who write bug reports or pull requests know git. Other people\ntypically prefer other means of communication, e.g. support forums.\n\nStill, adding an ssh-key to a repo is some work. Not much more work than\nsubscribing to a mailing list, but still a lot to ask for just fixing a typo.\n\n### Why is there no email support\n\nJust as plain text files and git, mail is another system that developers\nuse on a daily basis. However, I did not want to require an additional server.\n\nAdditionally, mail is a baroque system with many options. I did not want to\ndeal with HTML-email, MIME, encryption, different encodings, ….\n\n### Why are there no threaded discussions? Even github has them!\n\nGithub does not have threaded discussions in general. However, you can comment\ncode lines in pull requests, which results in something very similar to\nthreads.\n\nUnfortunately, it is quite hard to represent threads in a human readable plain\ntext file. You may use the `In-Reply-To` header, but I believe that extensive\nquoting should be sufficient for most cases.\n\n### When the zombie apocalypse starts and the github engineers are among the first victims (god behold!) and github goes down immediately, will this be our saviour?\n\nYes.\n\n### How does git-tickets compare to github?\n\ngit-tickets is very much inspired by the ticket system on github. However,\nthere are some key differences:\n\n-\t[github] is much more than a ticket system and offers (among other things)\n\thosting, a web interface, permission management, and project discovery.\n-\tA web interface is used instead of editing plain text files.\n-\tA separate authentication system is used.\n-\tGithub is a single point of failure. You cannot easily migrate to another\n\thoster.\n\n### How does git-tickets compare to mailing lists?\n\nMailing lists have been around for decades. They are still very much in use for\nsending in patches and discussing code. Archives allow to publicly reference\nthese discussions.\n\nSimilar to git-tickets, this workflow relies on established protocols and\nfree-text communication. But there are some important differences:\n\n-\tNo ticket-specific filters.\n-\tTools do not implicitly know about the code that is discussed.\n-\tA separate authentication system is used.\n-\tA separate server is needed.\n\n### How does git-tickets compare to debbugs?\n\n[debbugs] is basically a mailing list optimized for tickets. It solves the\nissue of filtering tickets. The other differences still apply.\n\n### How does git-tickets compare to bugseverywhere?\n\n[bugseverywhere] is a project with goals very similar to this one. It already\nhas a rich ecosystem of tools. Main differences:\n\n-\tIt stores the tickets in the same branches as code. This has some cool\n\tproperties, but also adds complexity. This also means that you need full\n\twrite access to create a ticket.\n-\tA command line tool is used instead of editing plain text files.\n\n### How does git-tickets compare to fossil?\n\n[fossil] is a CVS like git, but it comes with a ticket system, a web server,\nand a wiki included. Main differences:\n\n-\tNot compatible with other versioning systems (e.g. git)\n-\tA command line tool is used instead of editing plain text files.\n\n\n[mbox]: https://tools.ietf.org/html/rfc4155\n[commonmark]: https://spec.commonmark.org/\n[github-refs]: https://help.github.com/articles/autolinked-references-and-urls/\n\n[suckless]: http://lists.suckless.org/dev/1201/10574.html\n[RFC 1297]: https://tools.ietf.org/html/rfc1297\n\n[github]: https://github.com/\n[sit]: https://github.com/maandree/sit\n[fossil]: https://www.fossil-scm.org/index.html/doc/trunk/www/bugtheory.wiki\n[bugseverywhere]: http://www.bugseverywhere.org/\n[debbugs]: https://bugs.debian.org/debbugs-source/mainline/README.md\n\n[stagit]: https://git.2f30.org/stagit/\n[tig]: https://jonas.github.io/tig/\n[tig-feature-request]: https://github.com/jonas/tig/issues/299\n[mutt]: http://www.mutt.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxi%2Fgit-tickets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxi%2Fgit-tickets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxi%2Fgit-tickets/lists"}