[racket-dev] current packages' docs, errors, and conflicts

At a high-level, I think conflicts should be resolved by persuasion,
by long-suffering, by gentleness and meekness, and by love unfeigned.
We have had very few conflicts so far, but when they happen, I (the
package catalog maintainer) email the two package authors and let them
know what happened. Typically the newer author will volunteer that
they will change their package and it's fine. I think there will be a
rare instance where the older package is rotted in some way such that
the newer package would take precedence, but that's something we work
out with a social process.

At a low-level, I think that if a package X contains the "first
instance" of collection C then the docs for that should be named C.
But if it contains an extension of C, such as C/Y, then it should name
its docs "C/Y". For instance, if I implement the BSON protocol, I may
name it "net/bson" and I will provide "net/bson.rkt" but the docs will
be in "net/bson/manual.scrbl" with an associated "net/bson/info.rkt"
to point at that manual.

In the case of these two packages, I think that these packages may be
both inappropriately named. "c" may be better as "clang" or "lang-c"
or "lang-c-interp" and "c-utils" may be better as "syntax-c" or
something like that. Maybe we are both being to broad in these
packages which caused us to conflict.

Jay

On Mon, Aug 18, 2014 at 2:44 PM, Sam Tobin-Hochstadt
<samth at cs.indiana.edu> wrote:
> On Tue, Jul 8, 2014 at 8:14 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
>> At Tue, 08 Jul 2014 14:08:27 +0200, Jan Dvořák wrote:
>>>
>>> Can you provide some guidelines on docs naming?
>>> I am responsible for half of the conflicts. :-)
>>
>> A package "X" that provides a collection "X" of the same name should
>> probably also call its documentation "X".
>
> What should we suggest when two packages both have collections named
> "X"? This is the case for the "c" and "c-utils" packages, which both
> provide the "c" collection.
>
> Sam



-- 
Jay McCarthy
http://jeapostrophe.github.io

           "Wherefore, be not weary in well-doing,
      for ye are laying the foundation of a great work.
And out of small things proceedeth that which is great."
                          - D&C 64:33