Bug#1005190: gbp dch: add trailing dot when updating changelog
Hi, On Fri, Mar 03, 2023 at 12:16:27AM -0800, Otto Kekäläinen wrote: > Hi! > > To summarize here: > > - Good git commit message titles should NOT end with a dot. Titles I think there's consensus about that. > (and e.g. subject lines in an email) should not end with a dot based > on general English grammar rules and also software development / git > conventions as long as we have had patches and git commits. > > - By convention, many people use full sentences in changelogs (as > pointed out by e.g. Mattia in > https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=959665). In a > changelog it makes sense to have full sentences if the texts are > longer. This is also what English grammar rules say: a (bullet point) > list with just titles are not sentences and have no trailing dot, but > if the list has longer and *some* items that are sentences, then all > items in the list should end with a dot. I think the reason this is not moving forward is that people have different preferences. "English grammar rule" seems to be interpreted differently e.g. by the Imperial college for their brand: https://www.imperial.ac.uk/brand-style-guide/writing/grammar/punctuation/bullet-points/ which would only use fulls top if there's an introductory sentence (which isn't usually the case for changelogs). And there's other recommendation all around. I think a good way to move this forward is to at least have a recommendation in the developers reference (if not in policy itself) as everyone can already have the changelog configured by `gbp dch` as they see fit (via a customization-file) already. > Therefore, can we please make sure that Lintian-brush and things that > do git commits do NOT add trailing space, and that tools that write > changelogs add trailing dots when needed? Note that 'gbp dch' already figures out if a dot is needed based on the commit body for *multiline* git commit messages. So the simplest thing would be to add yet another option that (optionally) does that for one line changelog messages as well which would break down the debate to what is the right default (for which developer reference and policy are usually strong indicators). I've added a note along those lines to #959665. Cheers, -- Guido
Bug#1005190: gbp dch: add trailing dot when updating changelog
Hi! To summarize here: - Good git commit message titles should NOT end with a dot. Titles (and e.g. subject lines in an email) should not end with a dot based on general English grammar rules and also software development / git conventions as long as we have had patches and git commits. - By convention, many people use full sentences in changelogs (as pointed out by e.g. Mattia in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=959665). In a changelog it makes sense to have full sentences if the texts are longer. This is also what English grammar rules say: a (bullet point) list with just titles are not sentences and have no trailing dot, but if the list has longer and *some* items that are sentences, then all items in the list should end with a dot. Therefore, can we please make sure that Lintian-brush and things that do git commits do NOT add trailing space, and that tools that write changelogs add trailing dots when needed? I think Lintian Janitor is great and I love raising the bar on quality, but I am allergic to git commit titles and subject lines that have a trailing dot. Currently I want to support Janitor, but at the same time I don't want it to pollute my git history and suddenly have titles with trailing dot visible in e.g. $ git log --oneline af616d4bb4a Salsa-CI: Extend tests to install and run Cacti as extra validation abcdabcd Bump debhelper from old 12 to 13. a3b6f3d7f4b Increase MTR verbosity and unify skip test lists with how d/rules does it fdcc4c7493f Packages mariadb-plugin-provider-* must depend at least on MariaDB 10.11 44ae54b6dca Salsa-CI: Use pip3 with --break-system-packages for Python 3.11 compatibility 5a2361935e8 Update Brazilian translation of debconf messages (Closes: #1030908) cc86e20577c Update French translation of debconf messages (Closes: #1030581) 8f87f472749 (tag: debian/1%10.11.1-4) Update changelog for 1:10.11.1-4 release 741c3b3cdb5 Refresh patches and include references to Debian bugs they should fix 7ac10dee3b9 Add upstream patch to fix build failure on HPPA (Closes: #1006529) d0aa92192a8 Temporarily disable MTR on s390x as Debian buildd seems unstable dd25c71d47d Update existing patch with latest upstream PR#2448 version 0284207
Bug#1005190: gbp dch: add trailing dot when updating changelog
Hi! Personally I don't use trailing dots in d/changelog unless there are actual full sentences that need them. I do however wish gbp-dch had this feature, as currently when it does not have it, Lintian-brush adds trailing dot to git commit message titles. I find that ugly and I believe most git users would agree. if gbp-dch supported adding dots it would neatly solve this issue. > Jelmer Vernooij wrote: >> Guido Günther wrote: >> Introduce a /usr/share/doc/git-buildpackage/examples/debian_cl.py that >> has all the wanted options, have janitor recommend using that and later >> on make it a built in option if it's a style maintainers are happy with? > >Yeah, that seems like a reasonable approach. Let me see if I can >propose a script that does that. Thanks Guido and Jelmer for considering this! - Otto PS. This is practically identical https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=959665
Bug#1005190: gbp dch: add trailing dot when updating changelog?
On Wed, Feb 09, 2022 at 09:12:39AM +0100, Guido Günther wrote: > Hi Jelmer, > On Tue, Feb 08, 2022 at 07:01:36PM +, Jelmer Vernooij wrote: > > Package: git-buildpackage > > Version: 0.9.25 > > Severity: wishlist > > > > Hi Guido! > > > > "gbp dch" generates entries for debian/changelog based on Git commit > > messages. > > > > Best practice in Git is that the first line of a Git commit message is email > > subject-style, i.e. without a trailing dot. > > > > (see > > https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) > > > > However, the overwhelming practice in Debian (albeit not required or > > explicitly > > recommended by policy) is to use full dots at the end of each item in the > > changelog. > > > > (see > > https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog > > for the part of policy that covers the changelog) > > > > This makes it hard to stick to the convention in both systems while using > > gbp dch; > > using commit messages without a trailing dot (per Git convention) means > > having > > to add trailing dots in debian/changelog afterwards. > > > > Would you consider having "gbp dch" add trailing dots in changelog messages > > if > > they're missing? > > Can we use `--customizations=customization-file` here? We could even > ship a customization function in > /usr/share/doc/git-buildpackage/examples/ similar to > /usr/share/doc/git-buildpackage/examples/wrap_cl.py > > gbp-dch tries to stick as possible since everybody has its own > taste. I'm not totally opposed to having a more "d/changelog" like > style built in (maybe a combination of wrap_cl.py and adding a `.`) but > my feeling is that this will result in a large amount of bike shedding. > > Maybe we can about it this way: > > Introduce a /usr/share/doc/git-buildpackage/examples/debian_cl.py that > has all the wanted options, have janitor recommend using that and later > on make it a built in option if it's a style maintainers are happy with? Yeah, that seems like a reasonable approach. Let me see if I can propose a script that does that. I agree it's probably going to be gnarly to get this right for all cases. Cheers, Jelmer > > > > > (background: discussion in > > https://salsa.debian.org/jelmer/debian-janitor/-/issues/248; > > the janitor attempts to accomodate "gbp dch" users but ends up violating > > Git convention for commit messages by doing so) > > > > Jelmer > > > > -- System Information: > > Debian Release: bookworm/sid > > APT prefers unstable > > APT policy: (500, 'unstable'), (500, 'testing') > > Architecture: amd64 (x86_64) > > > > Kernel: Linux 5.15.0-3-amd64 (SMP w/2 CPU threads) > > Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8), LANGUAGE > > not set > > Shell: /bin/sh linked to /bin/dash > > Init: systemd (via /run/systemd/system) > > LSM: AppArmor: enabled > > > > Versions of packages git-buildpackage depends on: > > ii devscripts 2.22.1 > > ii git1:2.34.1-1 > > ii man-db 2.10.0-2 > > ii python33.9.8-1 > > ii python3-dateutil 2.8.1-6 > > ii python3-pkg-resources 59.6.0-1.2 > > ii sensible-utils 0.0.17 > > > > Versions of packages git-buildpackage recommends: > > ii cowbuilder0.89 > > ii pbuilder 0.231 > > ii pristine-tar 1.49 > > ii python3-requests 2.25.1+dfsg-2 > > > > Versions of packages git-buildpackage suggests: > > pn python3-notify2 > > ii sudo 1.9.9-1 > > ii unzip6.0-26 > > > > -- debconf-show failed > > -- Jelmer Vernooij PGP Key: https://www.jelmer.uk/D729A457.asc
Bug#1005190: gbp dch: add trailing dot when updating changelog?
Hi Jelmer, On Tue, Feb 08, 2022 at 07:01:36PM +, Jelmer Vernooij wrote: > Package: git-buildpackage > Version: 0.9.25 > Severity: wishlist > > Hi Guido! > > "gbp dch" generates entries for debian/changelog based on Git commit messages. > > Best practice in Git is that the first line of a Git commit message is email > subject-style, i.e. without a trailing dot. > > (see https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) > > However, the overwhelming practice in Debian (albeit not required or > explicitly > recommended by policy) is to use full dots at the end of each item in the > changelog. > > (see > https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog > for the part of policy that covers the changelog) > > This makes it hard to stick to the convention in both systems while using gbp > dch; > using commit messages without a trailing dot (per Git convention) means having > to add trailing dots in debian/changelog afterwards. > > Would you consider having "gbp dch" add trailing dots in changelog messages if > they're missing? Can we use `--customizations=customization-file` here? We could even ship a customization function in /usr/share/doc/git-buildpackage/examples/ similar to /usr/share/doc/git-buildpackage/examples/wrap_cl.py gbp-dch tries to stick as possible since everybody has its own taste. I'm not totally opposed to having a more "d/changelog" like style built in (maybe a combination of wrap_cl.py and adding a `.`) but my feeling is that this will result in a large amount of bike shedding. Maybe we can about it this way: Introduce a /usr/share/doc/git-buildpackage/examples/debian_cl.py that has all the wanted options, have janitor recommend using that and later on make it a built in option if it's a style maintainers are happy with? Cheers, -- Guido > > (background: discussion in > https://salsa.debian.org/jelmer/debian-janitor/-/issues/248; > the janitor attempts to accomodate "gbp dch" users but ends up violating > Git convention for commit messages by doing so) > > Jelmer > > -- System Information: > Debian Release: bookworm/sid > APT prefers unstable > APT policy: (500, 'unstable'), (500, 'testing') > Architecture: amd64 (x86_64) > > Kernel: Linux 5.15.0-3-amd64 (SMP w/2 CPU threads) > Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8), LANGUAGE not > set > Shell: /bin/sh linked to /bin/dash > Init: systemd (via /run/systemd/system) > LSM: AppArmor: enabled > > Versions of packages git-buildpackage depends on: > ii devscripts 2.22.1 > ii git1:2.34.1-1 > ii man-db 2.10.0-2 > ii python33.9.8-1 > ii python3-dateutil 2.8.1-6 > ii python3-pkg-resources 59.6.0-1.2 > ii sensible-utils 0.0.17 > > Versions of packages git-buildpackage recommends: > ii cowbuilder0.89 > ii pbuilder 0.231 > ii pristine-tar 1.49 > ii python3-requests 2.25.1+dfsg-2 > > Versions of packages git-buildpackage suggests: > pn python3-notify2 > ii sudo 1.9.9-1 > ii unzip6.0-26 > > -- debconf-show failed >
Bug#1005190: gbp dch: add trailing dot when updating changelog?
Package: git-buildpackage Version: 0.9.25 Severity: wishlist Hi Guido! "gbp dch" generates entries for debian/changelog based on Git commit messages. Best practice in Git is that the first line of a Git commit message is email subject-style, i.e. without a trailing dot. (see https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) However, the overwhelming practice in Debian (albeit not required or explicitly recommended by policy) is to use full dots at the end of each item in the changelog. (see https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog for the part of policy that covers the changelog) This makes it hard to stick to the convention in both systems while using gbp dch; using commit messages without a trailing dot (per Git convention) means having to add trailing dots in debian/changelog afterwards. Would you consider having "gbp dch" add trailing dots in changelog messages if they're missing? (background: discussion in https://salsa.debian.org/jelmer/debian-janitor/-/issues/248; the janitor attempts to accomodate "gbp dch" users but ends up violating Git convention for commit messages by doing so) Jelmer -- System Information: Debian Release: bookworm/sid APT prefers unstable APT policy: (500, 'unstable'), (500, 'testing') Architecture: amd64 (x86_64) Kernel: Linux 5.15.0-3-amd64 (SMP w/2 CPU threads) Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8), LANGUAGE not set Shell: /bin/sh linked to /bin/dash Init: systemd (via /run/systemd/system) LSM: AppArmor: enabled Versions of packages git-buildpackage depends on: ii devscripts 2.22.1 ii git1:2.34.1-1 ii man-db 2.10.0-2 ii python33.9.8-1 ii python3-dateutil 2.8.1-6 ii python3-pkg-resources 59.6.0-1.2 ii sensible-utils 0.0.17 Versions of packages git-buildpackage recommends: ii cowbuilder0.89 ii pbuilder 0.231 ii pristine-tar 1.49 ii python3-requests 2.25.1+dfsg-2 Versions of packages git-buildpackage suggests: pn python3-notify2 ii sudo 1.9.9-1 ii unzip6.0-26 -- debconf-show failed
