track bugs in VCS, not the other way around

[Sam Vilain]

martin f krafft wrote:
> Let's assume for a minute that we accept that VCSs are the way
> forward and start to consider how we could track bugs in the VCS,
> alongside the code.
> 
> Start to think about it this way, and stuff suddenly neatly aligns,
> at least in my world.
> 
> Suddenly you can commit a patch and mark the bug fixed atomically.
> 
> Suddenly, bug reports become commits in a branch, and keeping the
> branch empty is your goal.
> 
> Divergence from upstream is represented in topic branches, and you
> want to keep the number of those minimal to not go insane.

Martin,

I think this is an extremely sensible plan.  IME all bug trackers ever
do is fill with old stale rubbish.

I would also add, that a certain number of "best practices" be adopted;
this will assist in upstream maintainers reviewing and adopting patches,
no matter what VCS or system of development they use:

  - all patches should be clearly described by:

     - a one-line subject description of the change

     - an introduction to the patch; why it is necessary, what the code
       base did before it was introduced, and an outline of the approach
       to be taken.  For trivial changes, this might be one sentence.

     - authorship and reviewer information ("From", "Signed-off by",
       "Acked-by" lines or even "Cc" in some cases)

     - no reference should be made in the patch introcuction to things
       which become useless after the patch is applied, such as which
       version it is for.

     - optionally, a comment about this revision of the patch,
       information that will not be useful to a maintainer of the patch,
       clearly delineated from the long-term description of the patch.

  - no changes that are not a part of the description are allowed.

  - Patches that require further minor changes later for acceptance
    should be rolled together, so that the upstream has less work to
    review and you don't get "this patch fixes that patch" etc.

    The question about what to do with revised/dropped patches would
    likely be solved on a per-VCS basis

  - Ideally, no single patch should break the product's test suite.
    Individual projects may be more lax about this requirement when
    applied to patch series.

  - Where the upstream source control provides an easy way to do so -
    such as repositories hosted in repo.or.cz, github, etc - a new
    branch should be created which contains the above patches, so that
    people visiting the source control of the product can see the
    outstanding changes requested by the debian project as an explicit
    fork.

  - Patches may simply update an ERRATA file, if they are a simple
    confirmed bug report.

Note that many of these are really just a restatement of best common
practices since people started sending patches to mailing lists in the
mid-80's.  They have since been explicitly codified and rigidly enforced
in the Git community, so people will see that these are essentially the
Linux Kernel Development guidelines, just without any specification of
the exact format of the patch.  While it is tempting to standardise on
git-format-patch format, I don't think it is productive to bring that
detail in right now.

Yes, I realise that those who are frequently cross-merging will have a
hard time turning their feature branches into this form.  However, the
patches do not necessarily have to be applicable to the head version, as
long as the above requirements are met.

Sam.