[dist-bugs] RFC: buginfo microformat (the format in detail)

[Joey Hess]

Part 2, mostly consisting of boring details that will probably all
change later.

One thing I'm especially uncertian about in the below is the generation
of the id=gig-* field. Removing all whitespace from the buginfo *seems*
like a good idea, because whitespace damage would be the most common
problem preventing checking a signature. But, it also has the potential
to turn two different buginfos into the same string. I think that's 
  a) very unlikely to happen in real life given the current format
  b) not bad it it happens since gpg's signature includes the date anyway,
     so will still be globally unique


## the buginfo microformat

Unlike most microformats, this one is not limited to html, and can appear
in many mediums, from web pages to email to commit messages. Let's allow
the characters used to set the microformat off to vary, so that the most
natural ones for a given medium can be used.

	[[buginfo url ...]]
	{{buginfo url ...}}
	**buginfo url ...**
	<span class=buginfo>url ...</span>

All field=value pairs are optional. Fields are divided into two types,
state changing and non-state changing. With the exception of the 
"state" field, state changing fields all have names starting with "state-"
or "X-state-".

### state changing fields

Unless otherwise noted, these fields cannot be repeated multiple times
in a given buginfo.

* state={open,closed,...}

  Records if the bug is open or closed, or in some other state.

* state-blocked=url

  Records that fixing this bug is blocked by the bug at the url.
  Code dealing with this should detect and handle cycles.

  If a bug is both state=closed and blocked, the blocks can be ignored.
  
* state-unblocked=url

  Records that this bug is no longer blocked by the bug at the url.

* X-state-*=...

  Records some state, meaning is implementation dependent.

### non-state changing fields

Unless otherwise noted, these fields can be repeated multiple times
in a given buginfo.

* id=type-data

  This is a unique id for the buginfo. The "type" can be "gpg", "sha1", or
  implementation-defined.

  The data for the gpg id type is calculated by the buginfo creator
  taking everything inside the microformat delimiters, except the "id=*"
  part, stripping all whitespace, and running `gpg -a -b` on it.
  The data is the payload of the gpg signature, with whitespace
  removed.

  Excample: id=gpg-iD8DBQBIc7yG2tp5zXiKP0wRAvLZAJ95E1n5rec3bFNZ7wQt+1vQoOCtAwCgjEsbDhA0AnYg5LdDv3mpJ9F34O4==DQIt

  To check a gpg id, just put the data back inside a "BEGIN PGP SIGNATURE"
  block, and use gpg --verify against the buginfo data, munged as described above.

  A sha1 id can be generated and checked similarly.

  The id allows detection of duplicatess of a given buginfo as
  they propigate around the net, as well as to establish who generated the
  buginfo (if a gpg signature is used). It can also be used for filtering,
  or sorting.

  If this field is omittied, there's no way to refer to a buginfo,
  or detect duplicates of a buginfo. So, while this field is not
  100% required, buginfos without it may be filtered out by most
  consumers.

  This field can appear zero or one times, but not more.

* ref=type-data

  This is used for one buginfo to refer to a previous buginfo.
  Ordering buginfos by such references if the only way to tell 
  in what order state changes happened.

  A ref field should *only* be added if the intent is to change/refer to the
  previous status of a bug. If projects A and B both have a bug X, it can
  be open in A and closed in B. The closure in B should take care not to
  refer to the open bug in A, since doing so would mean it's making an
  assertian about the bug's state in A. 

  Ref cycles are not allowed. Consumers should check for them, and break them.

  This field can appear zero or one times, but not more. If multiple
  states need to be merged, it's simpler to use multiple buginfos to do it.

* merge=type-data

  This is used to refer to an additional ref whose state should be merged
  in. See below for more on merging.
  
  This field can appear zero or one times, but not more.

* ignore=type-data

  This is used to cause a ref to be ignored. See below for more on ignoring.

* unignore=type-data

  This is used to cause a ref, if previously ignored, to once again be
  taken into account.

* patch=[url|.]

  Indicates that the buginfo is associated with a patch to fix the bug.
  The value is either an url, which should be an url to use to download the
  patch, or ".", which indicates the patch is part of the document
  containing the buginfo.

  Aggregators should be usre to aggregate/archive the url containing the
  patch.

* seealso=url

  This is a way for a buginfo to add a third-party page to the bug log.

  For example, if relevant info about a bug is on a bugzilla that you
  don't have an account to, you can post a buginfo somewhere else that uses
  seealso to point to the bugzilla's url.

  Aggregators that would normally aggregate the page containing the buginfo
  can instead instead aggregate the page at the seealso url (they might
  aggregate the buginfo page too).

* license=name

  This is intended to be the license of the post that contains
  the buginfo, as well as of any copyrightable part of the buginfo itself.
  Archivers and aggregators can check the license.
  (Debian's machine parseable copyringht spec has a nice list of short
  names for licenses, such as "GPL-2+".)

* copy=url

  This records that the spcecified url is also tracking the bug.

  Once a copy url is published, buginfo consumers should associate
  together the two urls for a bug, so that any buginfos that refer to either
  would apply to both.

  Data aggregators should inform copy urls about new buginfos that they find.
  One way is by a http post with referer spoofing.

  Or, if an aggregator is archiving buginfo urls about a bug, it can
  publish these in a rss feed attached to its page (using 
  `link rel=alternate`). The copy can then poll that feed also, and
  copy it. This  is important to do, in case some sites with buginfos
  have gone down, so that information is not lost.

  Or the data can be transferred in some other, not yet specified way.

  Of course, the main point of a copy is that, if the original
  url for a bug goes down, the copy can continue working, new buginfos
  point to its url, and the bug's state continues to be tracked, and
  all archived data retained.

-- 
see shy jo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://kitenet.net/pipermail/dist-bugs/attachments/20080708/2611222a/attachment.pgp>