Hi!

While going over the debian-watch(5) man page noticed several things
that seem potentially problematic with the new format, or that
changing them now would make them way clearer and easier to read. In
any case thanks for the work on this, it seems like a clear
improvement over the previous formats!


* The part about ignoring dashes in field names seems weird, given
  that no other deb822-based format does that (that I'm aware of),
  so that seems rather surprising, and means we will not be able to
  use the usual deb822 parsers for this file. I think we are still
  in time to remove that?

* There was a report against dpkg to use a different name for the MUT
  "component" descriptor, I switched that to "addon", see commit
  <https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=a970502d811dbb69272506888eb3334f87e44104>,
  so it might make sense to use the same naming for the «Component» and
  «Ctype» fields, the latter could do with an expanded name instead of
  this strange contraction, to ease readability. So say «Addon-Name»
  and «Addon-Type»? Also to make it clear that the
  «Version-Constraint» is a MUT specific option, also namespace it as
  for example «Addon-Version-Constraint»?

* Rename «Repacksuffix» to «Repack-Suffix» for better clarity and
  namespacing?

* Change the «Mode» value «LWP» which is a Perl implementation detail,
  to something generic, like for example «URL»?

* If «Bare» is a git specific option, perhaps also namespace it, but
  that then could be confused with a git bare repository, so not sure
  what a better name might be. Perhaps a more descriptive name would
  be in order here.

* For «Pgp-Mode», rename «gittag» value to «git-tag» for better
  clarity?

* Do not use contractions and word merging for fields such as
  «Dversion-Mangle» and «Dirversion-Mangle» which are only away by two
  characters, or «Uversion-Mangle» or «Oversion-Mangle». I think using
  more descriptive names would be better, say «Downstream-Version-Mangle»
  (to avoid using Debian here), and «Dir-Version-Mangle»,
  «Upstream-Version-Mangle»,
  «Original-Version-Mangle»/«Orig-Tarball-Version-Mangle» (?).

* Is «hrefdecode=percent-encoding» supposed to be a field name? If
  yes, that looks like a strange name. Perhaps turn it into a field
  and value instead, say «Href-Decode: percent-encoding»?


(I'm not sure how many packages are already using several of these, but
I guess these could be switched with aliases, like it has been done
recently with similar requests, and adding deprecation warnings for the
old names, so that people can easily transition w/o immediately breaking
stuff, but given the freshness of the new format, now seems like an
appropriate time for any such change.)

Thanks,
Guillem

On that particular note, `debputy` has support for `d/watch` and can
rename the fields automatically via `debputy lint --auto-fix`  (or
`debputy reformat` with `X-Style: black`) once we agree on the new names
and `debputy` is updated, which should simplify matters for early adopters.

It already rewrites "dashless" field names into "with dashes" for cases
where it is possible, because I had a similar opinion on that matter.

Best regards,
Niels

I'm expressing my +1 to the naming improvement suggestions in this bug.

In particular the current `Dversion-Mangle` and variants place
unnecessary cognitive burden on the reader to remember what the one
letter abbreviation stand for, and to even notice the difference when
e.g. reviewing a MR with packaging done by someone else.

Hopefully somebody has time to work on this and introduce the new more
clearer naming and spelling options into uscan as accepted options so
maintainers can vote with their adoption on what their prefer.