Package: dgit Version: 9.13 Severity: wishlist This is a wishlist bug report on dgit(7) and dgit(1) documentation.
dgit is a very useful tool which I think all Debian actively maintained packages eventually need to migrate to. But dgit suffers fear, self-imposed uncertainty, and doubt feelings from well-intended DDs since it does many irreversible things such as uploading (source-)packages with very scant explanation of its design and functioning principles in its documents. For example, the documentation of dgit encourages to use "--overwrite" to make dgit to behave in non-default way without mentioning possible adverse effects explicitly. As I read https://bugs.debian.org/913451, it looks quite complicated due to the task dealing is complicated. ( ... still, I am not sure exactly how this impacts us). The word like "overwrite" is scary for publicly published git contents. Another scary thing is "deliberately-not-fast-forward". I think dgit(7), especially around "MODEL" needs more love. * What exactly is dgit-repo? * Is this URL printed by dgit print-dgit-repos-server-source-url? git+ssh://d...@push.dgit.debian.org/dgit/debian/repos/_dgit-repos-server.git or repo like: https://git.dgit.debian.org/dgit (for dgit) or https://salsa.debian.org/dgit-team/dgit.git (for dgit) * What is the role separation between the "package VCS site" and dgit-repo? I mean "package VCS site" such as: Vcs-Git: https://salsa.debian.org/dgit-team/dgit.git * Where do operation such as "dgit push" and "dgit push-source" send data to? * dgit-repo (?, one got from dgit clone had following refs) - vcs-git (looks like normal branch tracking Vcs-Git repo) - dgit (gitk works but "git ls-remote" doesn't work) * Vcs-Git git repo accessed by git - origin (has archive/... tags but no dgit like branch) * Debian archive (incoming) * Usage of words: "repo" and "archive", within dgit context may be documented clearly somewhere. * Why some dgit documents use "fast forward" without hyphen and some dgit documents use "fast-forward" with hyphen. (It looks like git-merge(1) consistently uses "fast-forward" with hyphen.) Are they used in the same sense as used by git-merge(1)? If so, it may be better to mention it. Please also explain --deliberately-not-fast-forward. * In --overwrite section in dgit(1) doesn't mention --deliberately-not-fast-forward. The --overwrite seems to me for the *first* time for each suite but "not the very first upload with dgit". This latter fact needs to be documented clearly. Anyway, these 2 things may scare new users. * In MODEL, in the following text, "used" is very confusing: dgit maintains a pseudo-remote called dgit, with one branch per suite. This remote cannot be used with plain git. At least, gitk can be used to identify their existence. I see git remote branch like remotes/dgit/dgit/sid in gitk for the local repository which used dgit but "git ls-remote" etc. doesn't seem to work. I don't see definition what exactly is the *pseudo-remote* in MODEL. I don't know exactly but something like: dgit pseudo-remote commit is like a git commit refs but without the actual file content in the git repository. Actual file content needs to be obtained by dgit. (or whatever it actually does, please describe.) dgit maintains a pseudo-remote called dgit, with one branch per suite. The existence of such branch ad associated tags can be seen by gitk ... but cannot be used with plain git since it is missing some normal git file content. The content of .... archive .... The mastery of pseudo-remote and its persistence over --overwrite gives me iffy feeling. The good news is dgit stops if try to do something stupid. Thanks and regards Osamu -- System Information: Debian Release: 11.0 APT prefers testing APT policy: (500, 'testing') Architecture: amd64 (x86_64) Kernel: Linux 5.10.0-7-amd64 (SMP w/12 CPU threads) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set Shell: /bin/sh linked to /usr/bin/dash Init: systemd (via /run/systemd/system) LSM: AppArmor: enabled Versions of packages dgit depends on: ii apt 2.2.4 ii ca-certificates 20210119 ii coreutils 8.32-4+b1 ii curl 7.74.0-1.3 ii devscripts 2.21.2 ii dpkg-dev 1.20.9 ii dput 1.1.0 ii git [git-core] 1:2.30.2-1 ii git-buildpackage 0.9.22 ii libdpkg-perl 1.20.9 ii libjson-perl 4.03000-1 ii liblist-moreutils-perl 0.430-2 ii liblocale-gettext-perl 1.07-4+b1 ii libtext-csv-perl 2.00-1 ii libtext-glob-perl 0.11-1 ii libtext-iconv-perl 1.7-7+b1 ii libwww-curl-perl 4.17-7+b1 ii perl [libdigest-sha-perl] 5.32.1-4 Versions of packages dgit recommends: ii distro-info-data 0.50 ii liburi-perl 5.08-1 ii openssh-client [ssh-client] 1:8.4p1-5 Versions of packages dgit suggests: ii sbuild 0.81.2 -- no debconf information
