[oi-dev] 1220 add /usr/bin/gpg symlink

[Bayard G. Bell]

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.