===========================================
Debian source package for ‘python-coverage’
===========================================

:Author: Ben Finney <bignose@debian.org>
:Updated: 2021-12-26


Pristine upstream source contains non-DFSG-free files
=====================================================

The pristine upstream source contains obfuscated files, that are thereby not
appropriate for use as source files. This violates DFSG §2.

The ‘debian/repack’ program removes those files to create the Debian upstream
source tarball.

The ‘debian/watch’ configuration specifies that ‘uscan --download’ will re-pack
the pristine upstream tarball.


Package maintenance in VCS
==========================

The source for the Debian packaging is managed in the ‘main’ branch of the
Git repository.


Work on a release in VCS
------------------------

* Get the correct upstream source, using UScan::

      $ uscan --download

* In the ‘main’ branch, create a new Debian changelog entry.

  Because the release is not complete, many aspects have not been decided and
  should not be recorded in the VCS:

  * The target destination (in the header) is “UNRELEASED”.

  * The person and timestamp of the release is undecided, so should be empty:
    the signature line should have no content, just the “ --” leader.

* While working on the package, temporarily finalise the signature line for
  testing the build.

  This ephemeral state should not be part of the VCS history, though, so do not
  commit that finalised changelog entry; revert it to the above state to
  continue development.


Build the source package from VCS
---------------------------------

* Ensure the ‘main’ branch contains all the changes that are intended for the
  release to Debian.

* Until the work is ready for release, do not commit a finalised Debian
  changelog entry. The changelog entry should be in the state described in
  “Work on a release in VCS”, above.

  This correctly leaves the decision of which destination for the upload, who
  uploads and when, to the point in time where that decision is made: the time
  of finalising the release.

* Rebase a working branch, e.g. ‘wip/release/4.2+dfsg.1-1’, from the HEAD of
  ‘main’.

* In this branch, finalise the ‘debian/changelog’:

  * Declare a release name, e.g. “* The “Ananta Bijoy Das” release.”

  * Set the target distribution, e.g. “unstable”.

  * Set the signature line containing the correct person and timestamp,
    e.g. “Ben Finney <bignose@debian.org>  Tue, 09 Aug 2016 06:05:28 +1000”.

  * Commit the finalised changelog with a commit message of the form
    “Finalise release “4.2+dfsg.1-1”.”

* Test the source package:

  * Export the source package::

        $ gbp buildpackage -S

  * Test the source package by building it in a Sbuild or Pbuilder
    environment, with all Lintian checks enabled.

* Only when the package builds satisfactorily from the source package:

  * Switch to the ‘main’ branch.

  * Pull the work-in-progress branch ‘wip/release/4.2+dfsg.1-1’ to ‘main’.

  * Create and sign a tag for the release, ‘release/4.2+dfsg.1-1’ with
    the commit message “Debian release “4.2+dfsg.1-1.”::

        $ git tag --sign \
            --message "Debian release “4.2+dfsg.1-1”." \
            "release/4.2+dfsg.1-1"

* Upload the successfully-built source package to Debian.

* Prepare the ‘main’ branch for ongoing work:

  * Delete the work-in-progress branch ‘wip/release/4.2+dfsg.1-1’.

  * Optionally: Create a new work-in-progress for an upcoming release,
    as described in “Work on a release in VCS”, above.


Omitted components
==================

Components that have been omitted from Debian because they do not
constitute the source form of the work:

    Files:
        tests/qunit/*.min.js
    Comments:
        These files are auto-generated from a source form that is not included
        in the work.


..
    Copyright © 2013–2022 Ben Finney <bignose@debian.org>
    This is free software: you may copy, modify, and/or distribute this work
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; version 3 of that license or any later version.
    No warranty expressed or implied.


..
    Local variables:
    coding: utf-8
    mode: rst
    mode: text
    End:
    vim: fileencoding=utf-8 filetype=rst :
