bts-link
========

******************************************************************************
This page tries to explain quickly how 'bts-link' works, and to answer most of
the usual questions people have with it.

If you need more extensive informations about it, please contact the
mailto:debian-bts-link@lists.debian.org[development mailing
list].

'bts-link' is developed using git, on `salsa.debian.org`:

- https://salsa.debian.org/bts-link-team/bts-link.git
- https://salsa.debian.org/bts-link-team/bts-link[gitweb]

******************************************************************************


Introduction
------------

'bts-link' brings the remote BTSes (_Bug Tracking Systems_) to our http://bugs.debian.org[Debian BTS (aka debbugs)],
see the
http://lists.debian.org/debian-devel-announce/2006/05/msg00001.html[announcement].


Its purpose is to allow to 'Fire and forget' bugs reports to upstreams, and
let an automatic tool *track the upstream bug status*. It was once written to
help the pkg-kde team, and was then extended so that other teams and other
BTSes than bugzilla could be supported. Currently, 'bts-link' supports:

- bitbucket;
- bugzilla (and issuezilla);
- flyspray;
- gforge (and fusionforge);
- github;
- gnats;
- googlecode;
- jira;
- launchpad;
- mantis;
- php's;
- redmine;
- roundup;
- RT;
- savane (from savannah);
- sourceforge trackers;
- trac.


How does it work ?
----------------

'bts-link' uses the +http://www.debian.org/Bugs/server-control#forwarded[forwarded]+ state of debian bugs to detect URI's of remote
BTSes it knows about. The _current_ configuration file defines which
BTSes are known, and is always available
from https://salsa.debian.org/bts-link-team/bts-link/blob/master/btslink.yaml[gitweb].

Then, based on its information, it polls the remote BTSes, gets the remote bug
_status_, and _resolution_ if the bug was closed, and acts accordingly. Depending on the remote BTS, 
it may know how to navigate to the proper active bug in case a remote bug was a duplicate of another one.


When it is executed ?
---------------------

'bts-link' is executed on a Debian project machine (sonntag.debian.org) every Monday and Thursday at 16.00 UTC.


Executions statistics
--------------------

link:stats.html[Here] there are some statistics about all the actions performed by 'bts-link'.


How you can help
----------------

There are several way you can help 'bts-link':

- forward all your packages (upstream) bugs to upstreams BTSes, and mark the Debian bugs as `forwarded`;
- alert us of any missing packages in the list of those currently checked (you can refer to the packages list in the https://salsa.debian.org/bts-link-team/bts-link/blob/master/btslink.yaml[configuration file]);
- ask to add support for any BTS not currently supported;
- provide patches when needed :)

To hack on bts-link, join the debian-bts-link@lists.debian.org[mailing-list] and the https://salsa.debian.org/bts-link-team/bts-link[Salsa project], and be part of it!

Gory Details
------------

'bts-link' uses http://wiki.debian.org/bugs.debian.org/usertags[usertags] to store its informations. The user is
debian-bts-link@lists.debian.org and it uses `status-*` and
`resolution-*` (user)tags to store those informations.

Then each time the upstream bug status changes, 'bts-link' takes the following
decisions:

- if the bug was previously opened, then closed: it tags the debian bug
  'fixed-upstream' ;
- if the bug was previously closed, then re-opened: it removes the tag
  'fixed-upstream' ;
- if the upstream resolution is also detected as a wontfix-like (it does not
  catches everyone of them though): it adds a 'wontfix' tag (and it will
  remove it also if the resolution moves from a wontfix state to another one).
- duplicates ? : to be documented
- merged-upstream ? 

******************************************************************************
'bts-link' uses the tags like that:

- 'fixed-upstream' is meant as "hey, this bug has been reported as fixed
  upstream, please checks it's true" ;
- 'fixed-upstream' + 'wontfix': this special combination means in fact
  'wontfix-upstream' but this tag does not exists.

******************************************************************************

'bts-link' will never _ever_ try to change tags in any other conditions. It
hence means that if you (as a Debian Maintainer) think that the bug isn't
fixed upstream, whatever upstream claims, you can completely remove the
'fixed-upstream' tag, 'bts-link' won't force it back, _except_ if upstream
re-opens the bug, then closes it again.

A list of all bugs having been managed by bts-link should be available at : 
http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-bts-link%40lists.debian.org
for the curious ones (attention, huge report).