# xpit - cross-platform issue tracker

Inspired by [tsoding's task system](https://youtu.be/QH6KOEVnSZA?si=uXGNx4ZifkuUJaAA&t=385).

# Dependencies

- Python 3.10+
- cryptography (`pip install cryptography` or something like 'python-cryptography' on your system package manager)

# Usage

Initialize xpit by running `xpit init`. This creates a new issue-tracker/ folder
in the current directory. Then use `xpit create` to create an issue (`xpit create -h` to print help).

# Why xpit?

The issue tracker is a large source of friction when migrating to a different VCS or
hosting provider (or moving to self-hosted). Relying on a platform's issue tracker
effectively creates a vendor lock-in with that specific platform.

Since we're already using version control, we might as well store the issue tracker inside
the repo and let the VCS handle the rest. xpit is designed to be text- and line-based and thus
compatible with virtually any VCS.

# Format

## issue-tracker/

Every issue has its own folder inside issue-tracker/. The name of the folder is the issue ID.
Each issue folder must contain an issue.md file. The issue.md file may reference files inside
the issue folder.

## issue.md

The basic syntax is regular markdown. Every issue.md file must start with a header in
the form of an INI code block:
```ini
author=<USER_NAME>#<IDENTITY>
status=<open|closed>
labels=<comma-separated list>
```
where USER_NAME is some name which may be changed, and IDENTITY is an identifier
to uniquely identify a user, regardless of name. USER_NAME and IDENTITY are separate
concepts to allow multiple users with the same name to exist inside the same project.

The issue title is the first heading of the file. Everything from the start of the file
to the end of file, or the first triple-dash (\n---\n) (whichever comes first) is considered to
be the initial issue post.

Subsequent posts/replies are delimited by triple-dashes and must themselves contain an
INI header:
```ini
author=<USER_NAME>#<IDENTITY>
id=<ID>
```
The ID is used to allow users to reply to a specific post via:
```ini
...
reply=<ID>
```

## issue-tracker/_config.ini

INI file containing:
    - id_format: format of newly created IDs. Uses strftime syntax (UTC).
    - allowed_labels: comma-separated list of labels that are allowed to be used in issues.

# Contributing

If you have any ideas or issues, send them to steven@vandorp.lu.

If you want to modify code, make your changes in a separate branch,
generate the patch(es) (`git format-patch master` from inside your branch)
and send the patch file(s) to steven@vandorp.lu.

# License

MIT License

Copyright (c) 2026 Steven Van Dorp

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.