Personal Issue Tracker

This is Jonathan Bernard's 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.

{
  "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).