Drop generation of debian/watch for GitHub projects and use Archive instead by ottok · Pull Request #300 · Debian/dh-make-golang

ottok · 2026-02-19T08:32:10Z

In devscripts since 2.25.19 uscan automatically discovers GitHub upstream tarballs when debian/upstream/metadata contains the Archive: GitHub and Repository fields. Since dh-make-golang already writes this file and only supports GitHub-hosted projects, the watch file is now redundant.

Removing it avoids maintenance overhead and confusion for new maintainers who might otherwise believe the file is required.

This also prevents Lintian from nagging about watch file format v4.

guilherme-puida · 2026-02-19T19:28:23Z

I think this makes uscan misbehave when upstream does not tag releases. I built this branch locally and tried dh-make-golang make -type l github.com/tscholl2/siec. Running uscan --report-status after results in:

uscan info: Scan watch files in .
uscan info: Check debian/watch and debian/changelog in .
uscan info: Found debian/upstream/metadata instead of debian/watch, trying to read it
uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61-1" (as seen in debian/changelog)
uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61" (no epoch/revision)
uscan info: ./debian/changelog sets package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61"
uscan warn: In /tmp/K8Cfn3Gdka/watch no matching files for watch source
  https://api.github.com/repos/tscholl2/siec/git/matching-refs/tags/
uscan info: Process watch file at: /tmp/K8Cfn3Gdka/watch
    package = golang-github-tscholl2-siec
    version = 0.0~git20240310.c2c6f61
    pkg_dir = .
uscan info: Parsing downloadurlmangle: s%(api.github.com/repos/[^/]+/[^/]+)/git/refs/%$1/tarball/refs/%g
uscan info: Parsing filenamemangle: s%.*/(?:[^/]+(?<=(?:\D|alpha|beta|rc))\-)?(?:[-_]?[Vv]?(\d[\-+\.:\~\da-zA-Z]*))%golang-github-tscholl2-siec-$1.tar.gz%
uscan info: Parsing pgpmode: none
uscan info: Parsing searchmode: plain
uscan info: Parsing versiontype: (?:[-_]?[Vv]?(\d[\-+\.:\~\da-zA-Z]*))
uscan info: Last orig.tar.* tarball version (from debian/changelog): 0.0~git20240310.c2c6f61
uscan info: Last orig.tar.* tarball version (dversionmangled): 0.0~git20240310.c2c6f61
uscan info: Requesting URL:
   https://api.github.com/repos/tscholl2/siec/git/matching-refs/tags/
uscan info: Scan finished

coldtobi · 2026-02-19T21:42:43Z

does this change break tracker.d.o detection of new upstream versions?

ottok · 2026-02-20T12:39:49Z

@coldtobi: This is a standard feature in uscan now and hence everything uscan does should continue to work, inluding upstream new version detection.

@guilherme-puida: Thanks for testing! Indeed the uscan v5 code path here is not working, I will test more this use case.

guilherme-puida · 2026-02-20T15:00:58Z

After some more thought, I think I disagree that the watch file is redundant. It needs to exist when:

Upstream does not tag releases (at least with the current implementation).
Upstream signs tags/commits and you want to check the signature.
You want to temporarily disable uscan with Untrackable: <reason>.
Probably other reasons I cannot think of right now...

Wouldn't it be better to still generate d/watch and use Template: Github so that changing any of the above would only require adding fields to d/watch instead of deleting Archive from d/u/metadata and creating a watchfile from scratch?

ottok · 2026-02-21T05:29:17Z

Actually the v5 template does not support checking neither signed tags nor detached signatures, see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1118381 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1118383

There are 3 options:

Not having a watch file by default, and asking people to create one only if the default upstream/metadata:Archive feature does not work for the package
Having a watch file with GitHub template, e.g.

Version: 5
Template: Github
Dist: https://github.com/homeport/dyff

Having a watch file with similar contents as now, making it easy to customize and having all security features supported, e.g.:

Version: 5
Source: https://github.com/homeport/dyff.git
Matching-Pattern: refs/tags/@ANY_VERSION@
Git-Export: all
Mode: git
Pgp-Mode: gittag

I am maybe leaning on option 3 now..

n-peugnet · 2026-02-23T15:26:13Z

IMO your option 2. looks nice, but using Owner and Project feels more common than Dist. Keeping the watch file is important for me, as I often need to tweak it a bit, so it is nice to have something to start from.

So I would simply keep the generated watch files as they are, but update them to version 5 and switch to Github templates, and maybe simplify them a bit, for example using Uversion-Mangle: auto as it works fine for most Go packages.

IIRC currently the watch file is only generated for Github upstream right?

ottok · 2026-02-23T15:35:25Z

IIRC currently the watch file is only generated for Github upstream right?

Yes, the watch file is currently generated only for projects with github.com in their identifier.

ottok · 2026-02-27T10:16:38Z

In a package where I track git HEAD I have now:

Version: 5
Source: https://github.com/pingcap/check.git
Matching-Pattern: HEAD
Mode: git

In another package I noticed the uversion-mangle has to be defined, the template alone isn't enough:

Version: 5
Template: GitHub
Dist: github.com/pingcap/tiup
Uversion-Mangle: auto
# Use Uversion-Mangle to ensure that e.g. v1.6.0-dev is converted to 1.6.0~dev
# (with tilde) is considered an earlier version than the actual v1.6.0 release

ottok · 2026-03-26T11:39:02Z

I switched the implementation to create a debian/watch file explicitly, but use v5 format. See commit for details.

Context:

When `dh-make-golang` generates source packages for new packages, it should use the new uscan v5 by default. Update the template syntax to use v5 and simplify a bit to the extent new features in v5 allows. While it would be possible to not generate any `debian/watch` file at all, as in devscripts since 2.25.19 uscan automatically discovers GitHub upstream tarballs when `debian/upstream/metadata` contains the `Archive: GitHub` and `Repository` fields, there is often cases where maintainers need to tweak the uscan settings and thus having an explicit watch file feels overall as a more uniform and handier default setup for now.

guilherme-puida · 2026-03-26T13:39:50Z

template.go

+	// If upstream release was repacked, use suffix '+ds1' to continue the Go
+	// team's historical convention despite uscan man page stating '+dfsg' as
+	// primary option.


I think this comment is a little bit misleading: +ds and +dfsg serve different purposes and I don't think +dfsg is stated as a "primary option" anywhere.

Here is the reasoning according to debian-watch(5):

+dfsg is used when some non-free files are removed
+ds is used when some files are removed for another reason (useless,...).
+repack is used when source was re-downloaded without version number change

guilherme-puida · 2026-03-26T15:00:46Z

template.go

-		fmt.Fprint(f, `" \`+"\n")
-		fmt.Fprintf(f, `  https://%s/%s/%s/tags .*/v?(\d\S*)\.tar\.gz debian`+"\n", host, owner, repo)
+		log.Printf("Setting debian/watch to fetch the GitHub release tarball")
+		fmt.Fprint(f, "Version: 5\n")


Duplicate Version: 5 here.

guilherme-puida · 2026-03-26T15:16:10Z

template.go

+		fmt.Fprint(f, "#Pgp-Mode: gittag\n")

 		// Anticipate that upstream would eventually switch to tagged releases
 		fmt.Fprint(f, "\n")


This breaks current uscan (2.26.6) AFAICT. With a d/watch file like this:

Version: 5 Mode: git Source: https://github.com/tscholl2/siec.git Matching-Pattern: HEAD # Enable verifying git tags are signed if upstream uses them: #Pgp-Mode: gittag # Use the following when upstream starts to tag releases: # #Template: GitHub #Dist: https://github.com/tscholl2/siec

This is the output of uscan --report-status

uscan info: Scan watch files in . uscan info: Check debian/watch and debian/changelog in . uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61-1" (as seen in debian/changelog) uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61" (no epoch/revision) uscan info: ./debian/changelog sets package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61" uscan info: Process watch file at: debian/watch package = golang-github-tscholl2-siec version = 0.0~git20240310.c2c6f61 pkg_dir = . uscan warn: The following paragraph isn't well formatted, skipping it: << ==EOF== # Use the following when upstream starts to tag releases: # #Template: GitHub #Dist: https://github.com/tscholl2/siec ==EOF== uscan info: Scan finished

If we remove the empty line it works fine:

uscan info: Scan watch files in . uscan info: Check debian/watch and debian/changelog in . uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61-1" (as seen in debian/changelog) uscan info: package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61" (no epoch/revision) uscan info: ./debian/changelog sets package="golang-github-tscholl2-siec" version="0.0~git20240310.c2c6f61" uscan info: Process watch file at: debian/watch package = golang-github-tscholl2-siec version = 0.0~git20240310.c2c6f61 pkg_dir = . uscan info: Parsing mode: git uscan info: Last orig.tar.* tarball version (from debian/changelog): 0.0~git20240310.c2c6f61 uscan info: Last orig.tar.* tarball version (dversionmangled): 0.0~git20240310.c2c6f61 Cloning into bare repository '../golang-github-tscholl2-siec-temporary.6087.git'... remote: Enumerating objects: 37, done. remote: Counting objects: 100% (37/37), done. remote: Compressing objects: 100% (35/35), done. remote: Total 37 (delta 5), reused 13 (delta 2), pack-reused 0 (from 0) Receiving objects: 100% (37/37), 66.94 KiB | 979.00 KiB/s, done. Resolving deltas: 100% (5/5), done. uscan info: uscan parser results: $base = https://github.com/tscholl2/siec.git $filepattern = HEAD $newfile = HEAD $mangled_newversion = 0.0~git20240310.c2c6f61 $newversion = 0.0~git20240310.c2c6f61 $lastversion = 0.0~git20240310.c2c6f61 uscan info: Upstream URL(+tag) to download is identified as https://github.com/tscholl2/siec.git HEAD uscan info: Filename (filenamemangled) for downloaded file: golang-github-tscholl2-siec-0.0~git20240310.c2c6f61.tar.xz uscan info: Newest version of golang-github-tscholl2-siec on remote site is 0.0~git20240310.c2c6f61, local version is 0.0~git20240310.c2c6f61 uscan info: => Package is up to date from: => https://github.com/tscholl2/siec.git HEAD uscan info: Removing git repo (../golang-github-tscholl2-siec-temporary.6087.git) uscan info: Scan finished

ottok self-assigned this Feb 20, 2026

ottok force-pushed the uscan-v5 branch from 5711963 to a41effa Compare March 26, 2026 11:38

ottok force-pushed the uscan-v5 branch from a41effa to c286fec Compare March 26, 2026 11:54

guilherme-puida reviewed Mar 26, 2026

View reviewed changes

Conversation

ottok commented Feb 19, 2026

Uh oh!

guilherme-puida commented Feb 19, 2026

Uh oh!

coldtobi commented Feb 19, 2026

Uh oh!

ottok commented Feb 20, 2026

Uh oh!

guilherme-puida commented Feb 20, 2026

Uh oh!

ottok commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

n-peugnet commented Feb 23, 2026

Uh oh!

ottok commented Feb 23, 2026

Uh oh!

ottok commented Feb 27, 2026

Uh oh!

ottok commented Mar 26, 2026

Uh oh!

guilherme-puida Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

n-peugnet Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

guilherme-puida Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

guilherme-puida Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ottok commented Feb 21, 2026 •

edited

Loading