139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# Personal Issue Tracker
|
|
|
|
This is [Jonathan Bernard's](mailto:jonathan@jdbernard.com) personal issue
|
|
tracker. In it's current form it is essentially a way to keep an curated list of
|
|
TODO's, organizing them by workflow category (todo, todo-today, dormant, etc.)
|
|
and context (Personal, Work, etc.).
|
|
|
|
## Categories
|
|
|
|
`pit` organizes issues into the following workflow categories:
|
|
|
|
- `current` - actively in progress
|
|
- `todo` - to be addressed in the future
|
|
- `todo-today` - chosen to be addressed today
|
|
- `pending` - blocked by some third party
|
|
- `dormant` - long-term things I don't want to forget but don't need in front
|
|
of me every day.
|
|
- `done`
|
|
|
|
In my typical workflow the `todo` category serves as a collection point for
|
|
things I want to keep track of. Then on a a daily basis I review issues in the
|
|
`todo` category and move a selection to the `todo-today` category. I also try
|
|
to keep the total number of issues in the `todo` below about a dozen. If there
|
|
are more than a dozen things in my `todo` category I will identify the lowest
|
|
priority items and move them to the `dormant` category.
|
|
|
|
## Issue Properties
|
|
|
|
`pit` allows arbitrary properties to be attached to issues in the form of
|
|
key-value pairs. On the command line these can be provided via the `-p` or
|
|
`--properties` parameter in the form
|
|
`-p <prop1Name>:<prop1Value>;<prop2Name>:<prop2Value>[;...]`
|
|
|
|
There are a couple of properties that pit will recognize automatically:
|
|
|
|
- `context`: the context organization feature is implemented using issue
|
|
properties.
|
|
- `created`: `pit` uses this property to timestamp an issue when it is created.
|
|
- `completed`: `pit` uses this property to timestamp an issue when it is moved
|
|
to the `done` category.
|
|
- `pending`: `pit` looks to this property to provide extra information about
|
|
issues in the `pending` category. Typically I use this to note who or what is
|
|
blocking the issue and why.
|
|
|
|
Some other common properties I use are:
|
|
|
|
- `resolution`: for short notes about why an issue was moved to `done`,
|
|
especially if it the action wasn't taken or if it is not completely clear
|
|
that this issue was completed.
|
|
|
|
## Configuration Options
|
|
|
|
`pit` allows configuration via command-line options and via a configuration
|
|
file. There is some overlap between the two methods of configuring `pit`, but
|
|
it is not a complete mapping.
|
|
|
|
### Config File
|
|
|
|
`pit` looks for a JSON configuration file in the following places (in order):
|
|
|
|
1. From a file path passed on the command line via the `--config <cfgFile>` parameter,
|
|
2. `./.pitrc`, in the current working directory,
|
|
3. From a file path set in the `PITRC` environment variable.
|
|
4. `$HOME/.pitrc`, in the user's home directory.
|
|
|
|
|
|
#### Sample Config File
|
|
|
|
This example illustrates all of the possible configuration options.
|
|
|
|
```json
|
|
{
|
|
"api": {
|
|
"apiKeys": [
|
|
"50cdcb660554e2d50fd88bd40b6579717bf00643f6ff57f108baf16c8c083f77",
|
|
"e4fc1aac49fc1f2f7f4ca6b1f04d41a4ccdd58e13bb53b41da97703d47267ceb",
|
|
]
|
|
},
|
|
"cli": {
|
|
"defaultContext": "personal",
|
|
"verbose": false,
|
|
"termWidth": 120,
|
|
"triggerPtk": true
|
|
},
|
|
"contexts": {
|
|
"nla-music": "New Life Music",
|
|
"nla-youth-band": "New Life Youth Band",
|
|
"acn": "Accenture",
|
|
"hff": "Hope Family Fellowship"
|
|
},
|
|
"tasksDir": "/mnt/c/Users/Jonathan Bernard/synced/tasks"
|
|
}
|
|
```
|
|
|
|
#### Explanation of configurable options.
|
|
|
|
In general, options supplied on the CLI directly will override options supplied
|
|
in the configuration file. All options are optional unless stated otherwise.
|
|
|
|
* `api`: configuration options specific to the API service.
|
|
|
|
- `apiKeys`: a list of Bearer tokens accepted by the API for the purpose of
|
|
authenticating API requests.
|
|
|
|
* `cli`: configuration options specific to the CLI.
|
|
|
|
- `defaultContext`: if present all invokations to the CLI will
|
|
be in this context. This is like adding a `--context <defaultContext>`
|
|
parameter to every CLI invocation. Any actual `--context` parameter will
|
|
override this value.
|
|
|
|
- `verbose`: Show issue details when listing issues (same as
|
|
`--verbose` flag).
|
|
|
|
- `termWidth`: Set the expected width of the terminal (for wrapping text).
|
|
|
|
- `triggerPtk`: If set to `true`, invoke the `ptk` command to start and stop
|
|
timers when issues move to the `current` and `done` categories
|
|
respectively.
|
|
|
|
* `contexts`: `pit` allows issues to be organized into different contexts via
|
|
a `context` property on the issue. The CLI groups issues according to
|
|
context. When printing contexts the CLI will take the value from the issues'
|
|
`context` properties and capatalize it. In some cases you may wish to have a
|
|
different display value for a context. I like to use abbreviations for long
|
|
context names to reduce the need to type, `hff` for "Hope Family Fellowship",
|
|
for example. The `contexts` config option allows you to provide a map of
|
|
context values to context display names See the sample file below for an
|
|
example.
|
|
|
|
Note that this mapping does not have to have entries for all contexts, only
|
|
those you wish to provide with an alternate display form. For example, in the
|
|
configuration sample above the default context is `personal`, a value not
|
|
present in the `contexts` configuration. `personal` will be displayed as
|
|
"Personal"; it does not need an alternate display name.
|
|
|
|
* `tasksDir` **required**: a file path to the root directory for the issue
|
|
repository (same as `--tasks-dir` CLI parameter).
|