On 04/01/2015 10:00 AM, Jochen Topf wrote: > On Tue, Mar 31, 2015 at 10:15:22PM +0200, Sebastiaan Couwenberg wrote: >> http://pkg-grass.alioth.debian.org/policy/packaging.html#git-new-upstream >> >> This section documents the typical first steps for updating existing >> packaging for a new upstream release. >> >> The section still needs to be expanded of typical things to do after and >> while refreshing the patches, most importantly reviewing license & >> copyright changes, possible new dependencies, etc. >> >> I appreciate feedback what to improve in our documentation to make it >> more useful as a reference for these kinds of tasks. > > First, the docbook styling is hard to understand. H4 are the same size as > normal text and H5 are actually smaller. This makes it difficult to see the > structure of the document.
The header styling has been tweaked in the recent changes to the policy. > And the black on white with interspersed white on > black code blocks is rather jarring. But thats just styling, not so important. I quite like how the black on white terminal output stands out from the text, the strong contrast can still be improved though. > I think the document needs more complete howto code sections. I think the code > sections are much more useful than the text. All I want to do is > copy-and-paste > a few commands, maybe change the name of the repository and run it. I am going > to script this on my side anyway. If I can't script it, it is not going to > work > anyway, because when I next look at it two months later I might be able to > remember to call "update_all_my_repositories" or so, but not complex pbuilder > command lines. > > So the problem really is that there are too many options in the document. > I understand it is necessary, because there are different ways of doing > things, > but for me I only need one option. :-) At the moment I have to follow the text > and understand for each code section whether it applies in my case and I have > to run it or not. Maybe this can be done by an approach like this: > > "To update to a new version, run these commands: > ... > ... > ... > If they all work, you are done. If any of them fails, read the following > background information..." The new upstream section has been reordered to incorporate this suggestion. Have a look: http://pkg-grass.alioth.debian.org/policy/packaging.html#git-new-upstream Kind Regards, Bas -- GPG Key ID: 4096R/6750F10AE88D4AF1 Fingerprint: 8182 DE41 7056 408D 6146 50D1 6750 F10A E88D 4AF1 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: https://lists.debian.org/[email protected]
