[ccan] CCAN issues

[Rusty Russell]

On Wednesday 19 December 2007 19:47:33 Michael Cohen wrote:
> Hi Rusty,
>    Thanks for taking the initiative...

Hi Michael,

	Thanks for responding!

> > 1) Domain name.  ccan.org would be ideal: seems to point to a generic ISP
> >    page, whois says Community Care Ambulance Network in Ohio, which seems
> >    legit at first glance.  ccan.com seems to be for sale by a squatter,
> >    perhaps we could do some deal where we buy ccan.com for the ambos and
> > get ccan.org?
>
> What about ccan.com.au? or maybe a hyphenated version (ccan-repo.org
> for example?)

    There's a certain impression made by a concise URL, and when you're trying 
to convince people to reuse code, first impressions really matter.  (I 
originally considered junkcode.org, which is great to encourage contribution, 
but can you imagine in 2 years saying to your boss "I pulled the hash 
routines from junkcode.org..."?)

    ccan-repo.org is the one I like most so far, but I'd love to find someone 
near Ohio who can chase down ccan.org...

> > 2) Namespacization.  If someone can't use (say) container_of because
> > their existing project uses that name, it'd be nice to rename it to
> > ccan_container_of.  Of course, this means any other ccan modules which
> > use this need changing too.
>
> I wonder if that is an integration issue? Clearly linking in C will
> become an issue due to name clashes. We should aim to have all ccan
> modules linked internally with strict symbol exportation controls
> (most things static etc). Things like macros and exported functions
> will need to be prefixed by something. (maybe ccan_ ).

This brings me to ccan-lint: it'd be nice to have some checker which warned 
about common stuff (like things which could be static).

> >    I thought about making the ccan_ versions canonical and providing
> > macros to map to the normal names, but it breaks the golden rule:
> >
> >         This code must not be ugly.
> >
> >    So I chose the harder road of supplying a C program to actually
> > rewrite the module and anything which depends on it.  Not quite finished
> > yet, but it has the merit of placing the burden of ugliness where it
> > belongs.
>
> This might produce un-ugly code but would make it difficult to
> integrate future versions of ccan into your project. This is because
> the version in your project would be different than the version in
> ccan and its hard to track these differences. I think it would be less
> ugly if the user ultimately drops in newer versions of ccan files
> instead of having to re-generate them.

I agree that it's a challenge, but I feel strongly about this (ie. I'm willing 
to code it).  The namespacization must be automated and sticky: if you pull  
a new version of the module, it must be automatically namespacized too.  
Obviously our testing needs to check that modules namespacize correctly.

> > 4) Licensing: so far I'm restricting it to with BSD no advertising, or
> > GPLv2+. More than that makes life too tricky for people wanting to use
> > the code.
>
> We need a consistant license for everything - unfortunately for
> testing etc we our selves will be linking to our own code so if we
> have a mix of licenses we might be breaking them ourselves.

I agree: two licenses is already one too many.  But there is existing code 
which is GPL which would be useful (talloc springs to mind), and so GPL and a 
weaker license makes sense.  (BSD no advertising can be mixed with GPL no 
problems).

> > 5) Uploading, automated testing, etc.  No idea here, plan to steal as
> > much of CPAN as possible for this.
>
> I think we need to use something bzr or darcs where people can send
> patches to the maintainer. These need to be tested before added for
> inclusion into the repo. There need to be some requirements before a
> module goes in (like tests, license etc).

The repo itself will probably be bzr (since that's the one I haven't used 
yet :), but it will need to be available through multiple means, and 
similarly submission should be possible by "upload a tarball".

We have to balance requirements with ease of contributing.  I'd prefer to 
accept anything but then grade them (automatically).  I'm hoping that Adam 
Kennedy will weigh in here...

> > 6) I have documentation-extraction code, but it doesn't do any xml-style
> > guff (the Linux kernel's system on which this is loosely based is perl
> > based, so maybe we should just steal that for the documentation, as it
> > does various different output forms).
>
> I personally dont like automated documentation generation - most of
> the time it tells you exactly what you would be able to read by just
> looking at the code and it allows people to be sloppy about writing
> documentation (hmm i can just run doxygen on this later - no need to
> document). I think reams of doxygen generated code from a thinly
> documented source tree is worse than do documentation at all.

I agree, but documentation with the code is better than external 
documentation, and some people *are* going to write documentation, so it's 
good to be standardized.  But the main purpose of the documentation is to 
read it in the code (or header), not as a separate document.

The exception is the _info.c file: this documentation is the description of 
the package as a whole, and is useful to extract for browsing the ccan repo.

> > 7) Automatic downloading, testing, checking for updates, and dependency
> >    tracking.  This would be nice, particularly handling namespacization
> > and detecting local mods.
>
> Again bzr of darcs can automatically take care of the updating,
> dependency tracking and detecting local mods.

I'm not so sure.  I don't think most people are going to grab the entire repo.  
They want the hash table routine, for example (and, by implication, anything 
else in ccan that needs).  I think there are several use cases:

1) Junkcode-style:
    grab a module, copy it into my source, never look back.
2) New project:
    grab a module, drop it under ccan/<modulename>.  May update later.
3) Large existing project:
    grab a module, drop it under ccan/<modulename>, namespacize.
    May update later.

While it'd be nice to ship helpers like "ccan-grab" and "ccan-update", I think 
that "download a tarball" is going to be the most universal method; and we 
can generate tarballs automatically containing all the dependencies.

See next mail...
Rusty.