A Kerberos ticket is necessary for authenticating with Koji or DistGit when uploading source files to the lookaside cache.

I propose dropping DistGit from here, so just or when uploading source files to the lookaside cache. Because the shorter form is already clear and unambiguous, and the concept of DistGit is fuzzy enough that it is unclear if it is a system that required authentication, or rather a concept that is implemented some system that actually goes by a different name. But if you are confident that the original form is technically correct, then it is fine to retain it.

Also, I would like to add a catch-all clause here, like ...is necessary for authenticating with certain Fedora systems, such as Koji and.... Just so that in case there are more systems, or more are added later, we are better covered.

I propose not using an admonition for the addition in the Package Maintenance Guide. We cannot know beforehand what any particular reader is looking for, and highlighting one aspect with an admonition makes it visually more difficult to spot the others. Also, when there are many admonitions, it becomes difficult to find anything. I think just a normal paragraph would do fine here.

The same goes for the broken warning admonition. In my opinion, it would be better to change that into a normal sentence, and just put it before the command that needs to be warned about. It looks like the general approach for Package Maintenance Guide is to start each section with the relevant fedpkg commands, then discuss them afterwards. But the fact that this particular command is seen as destructive enough so that a warning is needed actually tells us that that approach is not suitable for this particular section.

I would even argue that no warning is actually needed. Contrary to what the section text says, nothing is erased from the lookaside cache. Only the sources file is replaced, but even that is easy to recover from Git.

My preferred way how this section should look like, to be reader-friendly and in alignment with other sections:

1. Show the commands first, no warnings or discussion. But add the parameters they expect: <source_file>....
2. Explain the general concept of lookaside cache.
3. Add details about the two commands. Some kind of warning about new-sources erasing the sources file can be given, with a note that Git can be used to recover the previous content in case it is needed (but we should not try to be a Git tutorial, Git is a skill that we can assume, and otherwise learned from other, dedicated sources).
4. Add general notes, such as the "remember to commit" note and this pull request's note about Kerberos ticket.

Rewriting it like that is of course out of scope for this pull request, unless you want to do that. However, I might follow up with a commit that implements this plan, unless somebody tells me that it is not a good idea.

And thank you for the contribution, Package Maintenance Guide really is in need of some editing, and this is a good addition!

In order to move this forward, I applied my own suggestions and pushed. See the following commits:

• 0e503ae3b10d
• 3dbcca3902aa

The policy for this repository is to grant commit access to everybody with a merged pull request, so I have added you to group package-maintainer-docs. Going forward, you can self-merge trivial fixes. Pull requests are preferred for anything substantial, so others have a way to express their views.