On Wed, Nov 18, 2015 at 4:49 PM, Adam Williamson <adamwill@xxxxxxxxxxxxxxxxx> wrote: > Just as a general note on this thread: if you're a packager and you > have a genuine reason why people should be careful about touching your > package, or follow some specific process when doing so, or there's > something that people might think they should change but they > shouldn't, there is already a pretty effective way of dealing with > this: > > ** PUT A COMMENT IN THE SPEC FILE ** > > this is extremely easy to do, and extremely difficult for anyone who > touches it to claim they didn't see. I know this thread is a bit old, but thought I'd add a note when I checked my backlog and saw it. A comment in the code accompanying the change itself can also be invaluable, especially for changes that should propagate upstream.I cannot count the number of patches that have *nothing* in the patch content, only in the comments preceding the patch itself. I'm personally exhausted with people who refuse to document, whose API has to be deduced from the code, and especially whose code could fit *mutliple* workflows. And worse, when the API they think they're using isn't the one they've actually written, and they get upset when you don't code to this non-published API. That's cost me a job I rather liked. > Package builds in a community distro are really just like F/OSS code: > you should assume other people are going to be looking at it and poking > it and trying to do stuff with it, and any time it's doing something > that isn't extremely obvious or diverges from the general conventions, > it makes sense to comment it. Yes, lordie, please, "the code is the documentation" is an attitude I've encountered far, far too often, and I consider it the sign of a dangerous programmer. It's afraid it's a job security thing: by refusing to document you protect your turf. -- devel mailing list devel@xxxxxxxxxxxxxxxxxxxxxxx http://lists.fedoraproject.org/admin/lists/devel@xxxxxxxxxxxxxxxxxxxxxxx
