On Wed, 2011-10-05 at 00:12 +0100, Alasdair Lumsden wrote: > Hi Bayard, > > On 3 Oct 2011, at 18:11, Bayard G. Bell wrote: > > > On Sat, 2011-10-01 at 20:29 -0400, Josef 'Jeff' Sipek wrote: > >> Any issues with merging this? > >> > >> http://hg.31bits.net/oi/oi-build-gnupg/rev/6e09047a6043 > >> > >> (https://www.illumos.org/issues/1220) > > > > If the bug report is agreed, I reckon there needs to be a comment > > summarising this. Anything that has to be done in addition to or as a > > modification of copying out the proto tree needs some kind of reader's > > notes, and manifests may be the de facto place to retain that > > information, either as comments or README files. > > Yes, it is probably worth annotating additions/deletions to the .p5m file so > that someone coming along and updating a package knows what the deviations > from a "gmake sample-manifest" are.
I think manifest comments are acceptable but not preferable: this may be best understand by comparing the issue raised on xcowsay. If something can be maintained out of the Makefile and is pkgmogrify'ed into the manifest, it definitely belongs in the Makefile, as people have a reasonable expectation that they can find it there (and, particularly with metadata, people are more likely to need it in the dev environment for basic tasks like browsing from a project home page to find release announcements and notes). In general, the Makefile is the logical place to start and hopefully sufficient in most cases. If the change really is just at the level of a patch or a manifest, then it's reasonable to provide comments there. > Perhaps "# Adding gpg symlink as per Illumos issue #1220" ? Just as with commit messages, I'd reckon comments should summarise the substance of the change rather than simply reference external contents like an issue tracker. _______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
