* Fetch and merge a new version

To build this package you need to get the git repository:

git clone git://git.debian.org/git/pkg-common-lisp/cl-asdf.git

Then you need to setup the following remotes:

git remote add upstream https://gitlab.common-lisp.net/asdf/asdf.git

To update the package from upstream do:

git checkout master
git fetch upstream
git merge 3.1.7    # replace with the upstream release tag

The merge should not affect any files outside the debian subdir, but
to be sure, one can check the merge result with:

git diff 3.1.7..HEAD -- . ':!debian'

* Create changelog entry

You can use git-build-package to create a changelog entry for you
which contains a list of changes of the debian branch:

gbp dch --debian-branch=master --snapshot --auto debian

Afterwards, edit debian/changelog to set the version to the correct
one (e.g. 2:3.7.1-1) and the distribution to unstable. Also copy the
upstream changes from doc/Changelog for the current release.

I create two different sections for the changes:

  Package changes:

  * ....

  New upstream release:

  * ....

* Build the new version

Try to build any 

gbp buildpackage --git-ignore-new --git-upstream-tag='3.1.7' --git-debian-branch=master

Check for errors and correct them by either changing files in debian/
or by creating patches for the source files, which you then record
with

dpkg-source --commit

During this process, it is probably a good idea to delete the files
which are generated in the upper level directory by the build process:

rm ../cl-asdf_3.1.7*

After a correct build, check your package with  lintian:

lintian --profile debian --verbose --info --display-info

Pay attention to lintian's warnings. If you decide that some of them
are spurious or cannot be worked around, you can override them in
debian/cl-asdf.lintian-overrides.

Make sure that you use a very recent version of lintian. The versions
of the different Debian releases can be found on
https://packages.debian.org/search?keywords=lintian

After all changes in debian/ have been committed and added to
changelog (which should conveniently be the last commit before the
final build), you should run gbp with '--git-tag':

gbp buildpackage --git-tag --git-upstream-tag='3.2.0' --git-debian-branch=debian

* Upload to debian-mentors

Assuming that you are not a Debian developer, you have to upload the
new version of the package to debian-mentors and find a sponsor for
the package. (cf. https://wiki.debian.org/DebianMentorsFaq)


dput mentors-http  ../cl-asdf_3.1.7-1_amd64.changes


This is my dput configuration in ~/.dput.cf:

[mentors-ftp]
fqdn = mentors.debian.net
login = anonymous
progress_indicator = 2
passive_ftp = 1
incoming = /
method = ftp
allow_unsigned_uploads = 0
# Allow uploads for UNRELEASED packages
allowed_distributions = .*

[mentors-http]
fqdn = mentors.debian.net
incoming = /upload
method = http
allow_unsigned_uploads = 0
progress_indicator = 2
# Allow uploads for UNRELEASED packages
allowed_distributions = .*


* Create a Request For Sponsorship Bug

Assuming that you are not a Debian developer and have to go through
the debian-mentors sponsorship process (cf. previous section), you
have to send such a mail to submit@bugs.debian.org, if you are not a
maintainer, put [NMU] (non-maintainer upload) in the subject line:

------ snip -------

From: John Doe <john.doe@example.com>
To: submit@bugs.debian.org
Subject: RFS: cl-asdf/3.1.7 - Another System Definition Facility

Package: sponsorship-requests
Severity: normal

Dear mentors,

I have packaged the new upstream release 3.1.7 of the Common Lisp ASDF
software:

 Package name    : cl-asdf
 Version         : 2:3.1.7-1
 Upstream Author : Robert P. Goldman <rpgoldman@sift.info>
 URL             : https://common-lisp.net/project/asdf/
 License         : Expat
 Section         : lisp

The cl-asdf source package builds this binary package:

cl-asdf    - Another System Definition Facility

The package appears to be lintian clean.

To access further information about this package, please visit the following URL:

  http://mentors.debian.net/package/cl-asdf

Alternatively, one can download the package with dget using this command:

  dget -x http://mentors.debian.net/debian/pool/main/c/cl-asdf/cl-asdf_3.1.7-1.dsc


Changes since the last upload:

cl-asdf (2:3.1.7-1) unstable; urgency=medium

  Package changes:
  * temporary fix for upstream 'make clean' deleting debian/patches

  New upstream release:

  * Fix compilation on Genera.
  * Fix UIOP:FILE-EXISTS-P for dotfiles on CCL.
  * Fix infinite loop in source registry configuration that can occur when
        there are cycles in the filesystem (typically caused by symlinks)
        on some CL implementations.
  * Miscellaneous bug fixes.
  * Documentation improvements.
  * Restore original Makefile.


Thank you


John Doe


------ snip -------

* Get push permission to the Debian git repo

If you are interested in becoming a Debian package maintainer for
cl-asdf, you should follow the asdf-devel mailing list
(asdf-devel@common-lisp.net).

In case that the current package maintainer retires and you want to
step up, I describe the steps which I had to take in 2016 to become
the Debian package maintainer. I have also a list of resources in the
next section which helped me to get a grasp of how the packaging
process works.

1) Create an account on Debian Alioth and add your public SSH key on
the page https://alioth.debian.org/account/editsshkeys.php.

2) Ask on the asdf-devel mailing list (asdf-devel@common-lisp.net)
and/or the pkg-common-lisp-devel mailing list
(pkg-common-lisp-devel@lists.alioth.debian.org) to be added to the
pkg-common-lisp team
(https://alioth.debian.org/projects/pkg-common-lisp).

3) Change the git remote address of the debian git repo in .git/config
to

[remote "origin"]
        url = git+ssh://<your-username-on-alioth-guest>@git.debian.org/git/pkg-common-lisp/cl-asdf.git

git fetch origin


4) Push the packaging and upstream changes to the repo

Assuming that you are on the branch where the debian/ subdir is maintained:

git push origin HEAD:master

git push origin upstream/master:upstream

git push origin --tags

* Useful resources

- Debian New Maintainers Guide: https://www.debian.org/doc/manuals/maint-guide/index.en.html

- Debian Mentors FAQ: https://wiki.debian.org/DebianMentorsFaq

- Debian Common Lisp Team: https://alioth.debian.org/projects/pkg-common-lisp/

- git-buildpackage Manual: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html

- Current versions of lintian: https://packages.debian.org/search?keywords=lintian

