Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mgoellnitz/trackdown

TrackDown - Issue Tracking with plain Markdown. If you are missing the "git clone" for your tickets from github.com, codeberg.org, or gitlab.com, then this is for you. A lightweight Ticketing System for distributed and unconnected small Teams.
https://github.com/mgoellnitz/trackdown

bitbucket gitlab issue-tracker markdown mercurial ticket wiki

Last synced: 5 days ago
JSON representation

TrackDown - Issue Tracking with plain Markdown. If you are missing the "git clone" for your tickets from github.com, codeberg.org, or gitlab.com, then this is for you. A lightweight Ticketing System for distributed and unconnected small Teams.

Awesome Lists containing this project

README

        

# TrackDown

[![Latest Release](https://img.shields.io/github/release/mgoellnitz/trackdown.svg)](https://github.com/mgoellnitz/trackdown/releases/latest)
[![License](https://img.shields.io/github/license/mgoellnitz/trackdown.svg)](https://github.com/mgoellnitz/trackdown/blob/master/LICENSE)
[![Build](https://img.shields.io/gitlab/pipeline/mgoellnitz/trackdown.svg)](https://gitlab.com/mgoellnitz/trackdown/pipelines)
[![Download](https://img.shields.io/badge/Download-Snapshot-blue)](https://gitlab.com/mgoellnitz/trackdown/-/jobs/artifacts/master/download?job=trackdown)

Issue Tracking with plain [Markdown][markdown] for [GIT][git] and
[Mercurial][hg].

In short: You are missing the `git clone` or `hg clone` respectively for your
tickets from [Codeberg][codeberg], [GitLab][gitlab], [GitHub][github], or some
other services (see below) where we already have this for code and wiki?

You need issue tracking which works for distributed and potentially disconnected
situations together with your distributed version control [GIT][git] or
[Mercurial][hg] and e.g. also your distributed wiki editing through [GIT][git]
or [Mercurial][hg] as well?

Then this here is for you!

[Support this project](https://ko-fi.com/backendzeit):
[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L5T3APO)

It is not intended for large, permanently online or connected teams and heavy
flows of tickets though, since you will be having only one file with plain
[Markdown][markdown] with your issues - and optionally other stuff - collected
in it.

The currently open issues of TrackDown itself can be found
[here](https://codeberg.org/backendzeit/trackdown/src/branch/trackdown/issues.md),
[here](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/issues.md), and
[here](https://github.com/mgoellnitz/trackdown/blob/trackdown/issues.md).

The corresponding roadmap is placed
[here](https://codeberg.org/backendzeit/trackdown/src/branch/trackdown/roadmap.md),
[here](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/roadmap.md), and
[here](https://github.com/mgoellnitz/trackdown/blob/trackdown/roadmap.md).

## Feedback

The primary home of this project for contribution and feedback lives at
[Codeberg][codeberg] with additional mirrors at [GitLab][gitlab] and
[GitHub][github].

# Design

While TrackDown does not define an issue related workflow, it has some intended
workflow elements which are supported:

The issues are defined and maintained in a single [Markdown][markdown] file
following the format given here.

The [GIT][git] post-commit hook or [Mercurial][hg] commit hook of TrackDown
reads the commit messages and modifies that issue collection if your commit
messages relate to some of the issues.

Additionally, a roadmap file is automatically maintained for your tickets.
This roadmap file groups the issue's headlines in groups according to their
version label and illustrated progress counting issues in progress and resolved
issues.

The issue collection this way is held local on your machine and not remote in
the database of a tracking system. (Which is something also [Fossil][fossil]
supports.) Like with the source code, it is pushed to remote repositories if
needed (or possible). The simple [Markdown][markdown] format and the usage of
[GIT][git] or [Mercurial][hg] as a backend support distributed, shared editing
and later merging of the issues and the related notes in the issue collection.
(This is where the parallel with [Fossil][fossil] ends).

# The Format

While sticking to only partly structured [Markdown][markdown] the following
elements should be maintainable with TrackDown:

- ID
- Title
- Status
- Commits
- Target Version
- Severity
- Affected Versions
- Description
- Comments

These fields are mapped to the following source structure

```
## ID Title (status)

*Target Version (optional)* - Currently assigned to: `me` (optional)

### severity (optional) priority (optional)

affected versions: 1.0, 1.1 (optional)

### Description (optional)

description

### Comments (optional)

comments (structured)

### Commits (auto generated)

The headline commits at level three is optional. The commit messages are
inserted just as the last part of the issue's level two text area.
```

The really fixed non-optional parts of this are

```
## ID Title (status)

(Commit messages inserted here before the next ticket)
```

## Field Values

### ID

Any combination of (English) upper- and lower-case letters and digits.

### Title

Any expressible in Markdown.

### Status

Anything expressible in Markdown. Automatically set values are "in progress" if
you start committing for a certain ID and "resolved", if you are using a prefix
of "fixes ID" or "resolves ID".

Other intended values include "new", where the issue is just files, and "closed"
when the solution is brought into production.

### Target Version

Only digits, letters and dots. No spaces allowed.

### Description

Anything expressible in Markdown.

### Affected Versions

Anything expressible in Markdown. Is expected to describe which version are
affected by the issue (if this is possible to say).

### Comments

Anything expressible in Markdown.

### Severity

Anything expressible in Markdown.

# Setup

There are two ways to set up TrackDown: Have the issues file integrated in your
source code repository, or place it in an arbitrary place of your choosing.

The first - default - way is to use it in a separate branch of your source code
repository. It is kept visible and editable through a symbolic link at the
root level of the source code repository. Of course, this file is touched
automatically via commits to your source code through the (post-)commit hook of
TrackDown.

The second way is to use the file at a different location - e.g. in the wiki of
the project instead of the source code repository, which is described later.

In both cases, the automatically maintained roadmap file resides next to the
issue collection file.

## Initialize the Repository

If you want to track the issues in a TrackDown branch of your source code
repository and not in any other location of your choosing, you need to modify the
[GIT][git] or [Mercurial][hg] repository accordingly. Your source code
repository must contain at least one commit for this to work.

To initialize your source code repository this way, call the script

```
trackdown.sh init
```

This creates the TrackDown branch for the issue tracking. For [GIT][git]
repositories, you have to manually propagate this thread to your upstream
repositories.

```
git push origin trackdown
```

TrackDown does not interfere with your remote workflow for any version control
system: Also for [Mercurial][hg] the trackdown branch will only show up in the
remote repositories if you push it.

```
hg push
```

Initialization must only be executed once for a repository including all of its
forks and clones.

If you want to use the issue collection file from a different location than the
special TrackDown branch, leave out this step.

## Repository Integration

Regardless of the location of the issue collection file, for each clone of the
repository you have to set up the TrackDown tooling to be able to use it
integrated with your source code commits.

To start using TrackDown for the respective clone, you have to issue

```
trackdown.sh use
```

when using the TrackDown branch in the source code repository or

```
trackdown.sh use
```

like in

```
trackdown.sh use ../wiki/issues.md
```

when using TrackDown with the issue collection file at a different location.
Automatic commit and push (see below) will be switched off in the latter case.

This creates (git or hg ignored) links `issues.md` and `roadmap.md` in the root
directory of your project pointing to the issue collection file and the roadmap.
Additionally, it will configure a post-commit hook for [GIT][git] or a commit
hook for [Mercurial][hg] respectively.

After this step, you can edit the issue collection file following the format
mentioned above.

# Commands in the Commit Messages

TrackDown is supposed to read the commit messages when not used as a plain
mirror and interpret the contents as potential commands for the modification of
alongside you work.

When using [GIT][git], TrackDown relies on an implementation, which is capable
of executing the script hooks, which is - as opposed to [Mercurial][hg] - not
the case for all implementations.

Right now, TrackDown understands only two commands in the commit messages.

## refs #*id*[,*id*...]

Reference the commit in the list of commits at the end of the issue text.

```
git commit -m "refs #MYID - comment" files...
```

This command changes the state to "in progress" from anything like new, nothing,
or even resolved. If the commit relates to more than one issue, the issues can
be separated by commas.

```
git commit -m "fixes #ONEID,ANOTHERID - comment" files...
```

```
(Future work: lifts the issue up to the top of the list)
```

## resolves|resolve|fixes #*id*[,*id*...]

Reference the commit in the list of commits at the end of the issue text.

```
git commit -m "fixes #MYID - comment" files...
```

This command changes the state to "resolved" from anything like new, nothing, or
in progress. If the commit relates to more than one issue, the issues can be
separated by commas.

```
git commit -m "fixes #ONEID,ANOTHERID - comment" files...
```

```
(Future work: moves the issue to the top the part of the list where the resolved issues reside)
```

# Command Line Tools

In addition to the init and integration tools, the following commands are
available:

## Roadmap

Provided that the issues in the issue collection file are marked with version
labels like suggested, the command

```
trackdown.sh roadmap
```

prints out a complete roadmap of the project sorted by "target versions" in
[Markdown][markdown] format.

The term "target version" could also be read as "release" or "sprint" or
anything which describes your development process best.

## List

The command `ls` is used to show all issues marked for a given "target version"
like in

```
trackdown.sh ls 1.1
```

where all issues intended to be completed in "target version" 1.1 are listed.

The term "target version" could also be read as "release" or "sprint" or
anything which describes your development process best.

## My Tickets

The command

```
trackdown.sh mine
```

lists all issues in the issue collection, which are marked with a

```
*Version 1.0* - Currently assigned to: `me`
```

The `me` placeholder in the case is taken - in that order - from

* the first parameter on the command line
* The `me` entry in the `.trackdown/config` file
* The local user name from the environment variable `$USER`

Optionally, you can add a path to an issue collection file as an additional parameter
like in

```
trackdown.sh mine ../wiki/issues.md
```

or

```
trackdown.sh mine UserName ../wiki/issues.md
```

## Show Issue Collection Changes Status

To show the current state of the local editing of the issue collection and
roadmap file, even if they reside in a special TrackDown branch and are only
used as symbolic links in the source code repository, a shortcut command is
available, giving a brief summary of the Mercurial or GIT state if the
issue collection and roadmap file.

```
trackdown.sh status
```

## Quick Sync of Issue Collection and Roadmap

Most times the editing changelog of the issue collection file and roadmap file
don't present too much additional information for which is already held in
the commit messages of the source code and the issue collection file itself.

In such situations, you can use the shortcut command `sync` to bring the
issue collection and roadmap file on your machine and the remote repository
in sync.

```
trackdown.sh sync
```

## Copy Milestone/Release Contents

The command `copy` is used to extract the issues related to a given milestone,
release, version, or whatever your terminology might be to a separate file
named after the given parameter. So

```
trackdown.sh copy 1.1
```

copies all notes for the issues marked with "1.1" as a version marker to a
separate file 1.1.md to obtain release notes and get the resolved issues from
the base issue collection file for your current work.

## Issues

The command

```
trackdown.sh issues
```

lists all potential issues in the issue collection. Potential means in this
case, that there may be some false positives if there are additional elements
in your issue collection file, which might be interpreted as issues.

Optionally, you can add a path to an issue collection file as a parameter, like
in

```
trackdown.sh issues ../wiki/issues.md
```

# Configuration

The source repository contains a directory named `.trackdown/`.

This directory contains a file named `config`. There are some options in this
file, which you might want to change.

Example config file for TrackDown:

```
autocommit=true
autopush=false
location=../wiki/issues.md
prefix=https://github.com/user/project/commit/
me=My Name
```

## Auto Commit all Issue Collection Changes

Automatically commits the new change to the TrackDown branch. If you didn't
change the default location where your source code repository contains the
a TrackDown branch, you will want to leave the unchanged with the default
value `true`.

In other scenarios, you may switch it to `false`.

## Auto Push all Issue Collection Commits

Automatically pushes after each cs to the upstream repository. If you
didn't change the default locations, where your source code repository actually
is the upstream repository of your issue collection, you will want to leave this
unchanged with the default value of `true`.

In other scenarios, you may switch it to false. E.g. if the issue collection is
part of your project wiki, then automatic pushing might lead to remote
operations, which is not desirable.

## Online commit summary prefix

With some GIT backends, it is possible to obtain a summary with changes and
commit message online for every commit. To use this facility, place a prefix
in the config file, where the hash of a commit can be appended, to obtain a
valid link for that very commit.

If TrackDown discovers common GIT services, it tries to automatically discover
the correct prefix for URLs pointing to single commits.

## Username for assignments

To be able to assign tickets to users, and thus to know who you are, the user
name as used in the issue collection file can be added here. This makes it
possible e.g. to list issues assigned to the current user.

Tickets won't be automatically be assigned when adding commits for an issue.
Just the progress flag will be set.

# Installation

When building TrackDown locally, preliminary DEB and RPM packages will be
created. But when downloading one of the releases or a snapshot, copy the files
from bin/ to a place on your $PATH for now. For some functions - especially in
the area of issue tracker mirror - [jq][jq] needs to be installed.

Of course, this way the remaining Windows users are locked out.

A symbolic link `td` to the `trackdown.sh` script is recommended for easier
use.

## Compatibility

TrackDown is tested to work with Debian 11 and newer. It is expected to work
on similar Linux systems and MacOS systems. Also [NetBeans][netbeans] internal
GIT implementation should work.

There are no plans to support Windows systems directly.

## Prerequisites

TrackDown relies on a [GIT][git] or [Mercurial][hg] installation available on
the path when used with distributed version control as the backend. The
mirror feature in turn heavily relies on the installation of [jq][jq] available
through your path.

# Related Projects

I only came across related projects which have certain limitations or are
unmaintained. In each case, the limitations have an extent that kept me from
using these systems except for very small or test projects.

## Fossil SCM

What I liked about fossil is, that it brings the three core elements of development

- Source Code
- Documentation or Notes (Wiki)
- Issues

local to my machine for distributed development or disconnected situations.

You don't have to maintain backups since the remote instances are your backups
of the source code, wiki, and ticketing state.

It does not have a wiki capable of shared editing with later merging, like the
[GIT][git] based wikis of [GitLab][gitlab], [GitHub][github],
[Forgejo][forgejo], or [Bitbucket][bitbucket].

Also, it is not possible to the contents of the wiki outside the
[Fossil][fossil] context e.g. for a documentation website, since you cannot
export the wikis raw data. (Yes, [Fossil][fossil] provides means to use the
wiki directly as a documentation site system, which is similar but not exactly
the same.)

The drawback is, that it does all these things by creating a nearly closed shop
system not open to re-use of these elements and not open to external tooling
outside the [Fossil][fossil] scripting facility.

Additionally, I have to keep the [Fossil][fossil] internal web server running
for each repository I am using, to be able to read the notes and issues for a
project.

Also, there is only poor IDE support for [Fossil][fossil] right now, with the
exception of support for [Idea](https://plugins.jetbrains.com/plugin/7479)
and my own small [plug-in for NetBeans](http://chiselapp.com/user/backendzeit/repository/netbeans-fossil-plugin/index)
mirrored [here](https://github.com/mgoellnitz/netbeans-fossil-plugin).

## Forgejo (Gitea and Gogs)

Originally coming from the root of [Gitea][gitea] and [Gogs][gogs],
[Forgejo][forgejo] has been forked and extended. Intended for on premises use
as a [GIT][git] based solution for Code, Wiki and CI together with an issue
tracking section, it is also available in the form of the public online
incarnation [Codeberg](codeberg).

Of course [Forgejo][forgejo] can be used as a TrackDown storage backend or
mirroring source.

We also expect the related [Gitea][gitea] and [Gogs][gogs] system to be still
fully usable in the same way.

## GitHub

[GitHub][github] is the obvious solution used in so many [GIT][git] powered
projects together with a [GIT][git] based wiki (as opposed to
[Bitbucket][bitbucket] and [GitLab][gitlab] the Wiki is a flat folder - be
warned) and many other useful details.

The only thing I'm missing is the distributed offline work for ticketing.

So in this case it is possible to leave out the ticketing of [GitHub][github]
and use TrackDown with [GitHub][github] as the [GIT][git] based
storage backend. And this is exactly what TrackDown was designed for.

As an alternative, you can at least mirror the issues from [GitHub][github] to
have your notes with you and at least know the issue IDs for offline code
commits. Or you can use the mirroring steps for migration purposes.

## GitLab

[GitLab][gitlab] not only is a good online solution but also is a piece of
on premises software (like Bitbucket for the renamed git-Part - not hg.). It's
wiki is also [GIT][git] based wiki, and it comes with a wealth of other
integrations and useful tools and details.

The only thing I'm missing is the distributed offline work for ticketing.

So in this case it is possible to leave out the ticketing of [GitLab][gitlab]
and use TrackDown with [GitLab][gitlab] as the [GIT][git] based
storage backend. And this is exactly what TrackDown was designed for.

As an alternative, you can at least mirror the issues from [GitLab][gitlab] to
have the notes with you and now the issue IDs for offline code commits.

## Bitbucket

[Bitbucket.org][bitbucket] is a decent tool for open source or small projects.
It has decent VCS solutions, a wiki which can be used distributed through
[GIT][git]. In the past they were a brilliant backend for TrackDown with both
VCS solutions, since they also provided support for [Mercurial][hg], which was
abandoned in mid 2020.

The only thing I'm missing is the distributed offline work for ticketing.

So in this case it is possible to leave out the ticketing of [Bitbucket][bitbucket]
and use TrackDown with [Bitbucket][bitbucket] as the [GIT][git] based storage
backend. And this is exactly what TrackDown was designed for. For migration
purposes, or if the limited issue tracking within bitbucket.org is sufficient, the
mirroring feature might come in handy.

Atlassian themselves recommends using Jira.

## Trac

A few years ago, a colleague stated that he is running a local VM for each
project, he is involved with, to take notes, track issues, and maintain source
code.

Of course, this does not imply shared use of the Trac service or disconnected use.

Also, while Trac is a brilliant tool, this leaves me with the necessity to
maintain the locally running instances and take backups of them, in addition to
the project VCS and source code repositories. This is not the case for the
[GIT][git] based solutions in this list, which have a remote repository as a
backup wiki and source code.

## Other VCS Services

A small list of tested backends for TrackDown which don't support any kind of
issue tracking but Code and Wiki with the VCS:

* [Helix Team Hub][hth]
* [Visual Studio Services][vss]

## MDWiki

Unlike [Blogdown](https://github.com/gernest/blogdown) where you again start
a server - but this time on localhost, [MDWiki][mdwiki] just runs in your
browser to view Markdown files nicely formatted locally.

```
file:///home/me/somewhere/thats/green/repo/wiki.html#!issues.md
file:///home/me/somewhere/thats/green/repo/wiki.html#!roadmap.md
```

The output of TrackDown looks pretty usable in this setup and gives a good
overview of the issues as the roadmap.

When you also use GitLab, GitHub, or Bitbucket Wikis, [MDWiki][mdwiki] has
a different understanding, how links should be interpreted. To get a fully
compatible local and remote viewing setup for these cases, a patched
version of [MDWiki][mdwiki] [exists on GitHub](https://github.com/mgoellnitz/mdwiki/).

## Unmaintained related Projects

These seem to address similar issues, but are not under active development

- [GitIssius][gitissius]
- [Distributed Issue Tracker](https://github.com/keredson/distributed-issue-tracker)
- [Bugs Everywhere][be]

# Migration and Offline Mirroring

To facilitate the use of TrackDown, the option of migrating an existing base
of tickets is helpful, of course. The choice, which systems are taken as a
data source for such a migration is driven by personal needs.

## GitHub Offline Mirror

For disconnected situations which TrackDown is supposed to support, it is
possible to connect a workspace to its [GitHub][github] issue tracker and
mirror tickets for offline use.

The mirror - of course - is not intended for changing the issues in the issue
collection file. State changes will most likely be triggered on [GitHub][github]
by your commit messages or manually, after which a call of the mirroring script
can be helpful.

Instead of `trackdown.sh use` issue `trackdown.sh github` to set up the mirror
connection.

```
trackdown.sh github
```

Afterwards, anytime you can connect to the [GitHub][github] system, collect the
current mirror state to your local issue collection file and the roadmap.

```
trackdown.sh mirror
```

Additionally - since you now are on your command line and perhaps don't want
to switch windows every second - there is a `remote` command to issue commands
on the remote mirroring source system.

You have to provide the issue-id and the id of the user, which is also always
exported to the issue collection file to facilitate this.

The commands available are

* `assign` to assign issues to users

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

* `comment` to comment issues

```
trackdown.sh remote comment 68 "Just a comment"
Adding comment "Just a comment" to issue 68
```

## GitLab Offline Mirror

For disconnected situations which TrackDown is supposed to support, it is
possible to connect a workspace to its [GitLab][gitlab] issue tracker and
mirror tickets for offline use.

The mirror - of course - is not intended for changing the issues in the issue
collection file. State changes will most likely be triggered on [GitLab][gitlab]
by your commit messages or manually, after which a call of the mirroring script
can be helpful.

Instead of `trackdown.sh use` issue `trackdown.sh gitlab` to set up the mirror
connection.

```
trackdown.sh gitlab [https://]
```

If you omit the URL prefix, `https://gitlab.com` is used. The project name must
be given without any group or user addition.

Afterwards, anytime you can connect to the [GitLab][gitlab] system, collect the
current mirror state to your local issue collection file and the roadmap.

```
trackdown.sh mirror
```

Additionally, since you now are on your command line and perhaps don't want
to switch windows every second, there is a `remote` command to issue commands
on the remote mirroring source system.

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

You have to provide the issue-id and the id of the user, which is also always
exported to the issue collection file to facilitate this.

The commands available are

* `assign` to assign issues to users

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

* `comment` to comment issues

```
trackdown.sh remote comment 68 "Just a comment"
Adding comment "Just a comment" to issue 68
```

* `assign` to assign issues to users

* `milestone` to put issues into milestones

## Gitea Offline Mirror

For disconnected situations which TrackDown is supposed to support, it is
possible to connect a workspace to its [Gitea][gitea] issue tracker and mirror
tickets for offline use.

Setup parameters default to values from the [Git][git] repository your current
local directory points to.

The mirror - of course - is not intended for changing the issues in the issue
collection file. State changes will most likely be triggered on the [Gitea][gitea]
instance in use by your commit messages or manually, after which a call of the
mirroring script can be helpful.

Instead of `trackdown.sh use` issue `trackdown.sh gitea` to set up the mirror
connection.

```
trackdown.sh gitea [https://]
```

If you omit the URL prefix and no values can be derived from your current
working directory, `https://codeberg.org` is used.

Afterwards, anytime you can connect to the [Gitea][gitea] system, collect the
current mirror state to your local issue collection file and the roadmap.

```
trackdown.sh mirror
```

Additionally - since you now are on your command line and perhaps don't want
to switch windows every second - there is a `remote` command to issue commands
on the remote mirroring source system.

You have to provide the issue id and the id of the user, which is also always
exported to the issue collection file to facilitate this.

The commands available are

* `assign` to assign issues to users

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

* `comment` to comment issues

```
trackdown.sh remote comment 68 "Just a comment"
Adding comment "Just a comment" to issue 68
```

It is expected that this also works for [Gogs](gogs) backends as well.

## Bitbucket.org Offline Mirror

For disconnected situations which TrackDown is supposed to support, it is
possible to connect a workspace to its [Bitbucket.org][bitbucket] issue
tracker and mirror tickets for offline use.

Some of my stalled projects reside there, and I already did an export of the
issue tracker contents, which is what [Bitbucket.org][bitbucket] supports.

Offline mirror capabilities are now added to this tool for smother migration
away from the proprietary issue tracker.

The mirror again is not intended for changing the issues in the issue
collection file. State changes will most likely be triggered on
[Bitbucket.org][bitbucket] by your commit messages or manually, after which a
call of the mirroring script can be helpful.

Instead of `trackdown.sh use` issue `trackdown.sh github` to set up the mirror
connection.

```
trackdown.sh bitbucket
```

Afterwards, anytime you can connect to the [Bitbucket.org][bitbucket] system,
collect the current mirror state to your local issue collection file and the
roadmap.

```
trackdown.sh mirror
```

In the case of [Bitbucket.org][bitbucket], the mirror script has to ask for
you password on [Bitbucket.org][bitbucket], if you leave out the app password.
App passwords can be generated in the personal [Bitbucket.org][bitbucket]
settings.

Additionally - since you now are on your command line and perhaps don't want
to switch windows every second - there is a `remote` command to issue commands
on the remote mirroring source system.

The commands available are

* `assign` to assign issues to users

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

* `comment` to comment issues

```
trackdown.sh remote comment 68 "Just a comment"
Adding comment "Just a comment" to issue 68
```

## Redmine

For historical reasons, my [Tangram](https://github.com/mgoellnitz/tangram)
project used [Redmine][redmine] some time ago and customers also used
[Redmine][redmine]. So there are two scenarios where some interfacing would be
helpful.

In addition, the roadmap outline of TrackDown is very much inspired by the
[Redmine][redmine] roadmap page.

### Offline mirror

Since I'm - sad enough - not in the position to tell my enterprise scale
customers which ticketing systems to use, there is still the need to have
the issue descriptions, ticket ID, target versions, affected versions and
even the roadmap available offline.

For an offline mirror without the capability to change the status of tickets,
the following setup workflow is used instead of the steps given above:

Instead of `trackdown.sh use` issue `trackdown.sh redmine` to set up the mirror
connection.

```
trackdown.sh redmine [,...] https:///
```

Afterwards, anytime you can connect to the [Redmine][redmine] system, collect the
current mirror state to your local issue collection file and the roadmap.

```
trackdown.sh mirror
```

Additionally, since you now are on your command line and perhaps don't want
to switch windows every second, there is a `remote` command to issue commands
on the remote mirroring source system.

```
trackdown.sh remote comment XYZ "Hi there."
Adding comment "Hi there." to XYZ
```

```
trackdown.sh remote assign 68 XYZ
Assigning 68 to user XYZ
```

You have to provide the id of the user - not its name, which is also always
exported to the issue collection file to facility this.

### Migration

When you think the information mirrored right now is sufficient to cut the ties,
you can set up the created issue collection and roadmap as the repository and do
a `trackdown.sh use`.

The full migration is not covered by a command yet, and setting up the mirrored
data in the special TrackDown branch or any other location of your choosing must
be accomplished manually. The needed steps include:

*Latest Mirror*

Get the latest mirrored data.

```
trackdown.sh mirror
```

*Remove Mirror Configuration*

```
rm -rf .trackdown
```

*Initialize TrackDown*

Special Branch Flavour:

```
trackdown.sh init
trackdown.sh use
mv old-issues.md .git/trackdown/issues.md # or .hg
roadmap.md .git/trackdown/roadmap.md # or .hg
```

Custom location - e.g. wiki

```
mv old-issues.md ../wiki/issues.md
roadmap.md ../wiki/roadmap.md
trackdown.sh use ../wiki/issues.md
(cd wiki; git add issues.md roadmap.md) # or hg
```

*Clean Up*

Since the mirroring collects as much data as possible, it might be a good idea
to separate already closed releases or milestones from the currently relevant
issues in the issue collection. Use the copy command to do so:

```
trackdown.sh copy Milestone1
```

And now use the remaining issues as the new collection and add the separated
issues as a changes/changelog part to your documentation.

```
mv ../wiki/Milestone1-issues.md ../wiki/issues.md
(cd ../wiki ; git add Milestone1.md) # or hg
```

Of course, this cannot only be done for mirror issue collections and is e.g.
used for TrackDown itself, like for release 1.0 in
[this](https://github.com/mgoellnitz/trackdown/blob/trackdown/1.0.md) and
[this](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/1.0.md) file.

[markdown]: https://daringfireball.net/projects/markdown/
[mdwiki]: http://mdwiki.info
[jq]: https://stedolan.github.io/jq/
[jgit]: https://eclipse.org/jgit/
[trac]: http://trac.edgewall.org/
[fossil]: http://fossil-scm.org/index.html/doc/trunk/www/index.wiki
[redmine]: http://www.redmine.org/
[be]: http://www.bugseverywhere.org/
[gitissius]: https://github.com/glogiotatidis/gitissius
[git]: http://git-scm.com/
[hg]: https://www.mercurial-scm.org/
[bitbucket]: https://bitbucket.org/
[gitlab]: https://gitlab.com/
[github]: https://github.com/
[forgejo]: https://forgejo.org/
[gogs]: https://gogs.io/
[gitea]: https://gitea.io/
[codeberg]: https://codeberg.org/
[hth]: https://www.perforce.com/products/helix-teamhub
[vss]: https://www.visualstudio.com/team-services/