On Mon, 07 Oct 2019 21:22:46 -0400, Sam Hartman wrote: > Ansgar argued that documenting the branch format is unnecessary given > all the work you need to do to contribute to a package. Several > disagreed arguing that it helped them do their work.
I have an idea where Ansgar might be coming from; maybe I'm wrong but in any case I have the following reservation or request for clarification: > Conclusiony Thing > ----------------- […] > * If you are using debian group you should document your branch format. > Update to say that. Ok, here it says that the branch format should be documented for the Debian group (which reads like "not for teams if teams have different policies / general documentation somewhere"). > General Recommendation > ====================== > > This recommendation is intended for people who are simply looking for an > approach that will work well with approaches others are using. If you > are packaging something in a large team, follow their existing > practices. […] > You should document the branch format (such as patches unapplied (gbp > pq)) that your repository uses. Best practice for documenting this is > still evolving. The best current option is to document your branch > format in debian/README.source. Alternatively if you use `dgit > push-source`, your source format is documented in maintainer tags. Does this paragraph refer to repos in the Debian group or to all repos, i.e. team-maintained ones? The reason I'm asking is that I have very bad memories of the times when Policy required to document the use of quilt in debian/README.source (although quilt was very visible in both debian/control and debian/rules at that time); and literally thousands of boilerplate debian/README.source files were added; and some years later removed after a Policy change. I'm pretty sure there are still quite a few left in the archive. So if this recommendation is targetted at repos in the Debian group only (and teams can ignore it) I'm not enthusiastic by the prospect of outdated documentation there, but well … If it's meant to apply to team-maintained repos as well I'd consider this a mistake. (Maybe a sentence like "The following paragraphs refer to the Debian group, for teams see below under 'Recommendations for Teams'." in/after the first paragraph would help to disambiguate the scope at least.) Cheers, gregor -- .''`. https://info.comodo.priv.at -- Debian Developer https://www.debian.org : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D 85FA BB3A 6801 8649 AA06 `. `' Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe `- NP: Janis Joplin: Cry Baby
signature.asc
Description: Digital Signature
