[Tinyos Core WG] Instructions for contributing code

[Kevin Klues]

We argued about this organizational structure for a while, constantly
flip flopping back and forth between having code organized at the top
level by institution name, by project name, underneath a replicated
tinyos-2.x "core" dierectory strucutre (i.e. if you have a library to
contribute you put it under lib, if you have an app you put it under
apps), or not really "organized at all" (i.e. letting the community
decide how it should be organized).

Letting the community decide is the approach tinyos-1.x has taken, and
it has led to the mess that we see right now in the tinyos-1.x/contrib
directory.  It is almost impossible to find anything that is in there
since there is no central place to look for it, and there is no index
listing what code does exists, or how to use it.

I was originally for the idea of replicating something similar to the
tinyos-2.x core directory structure and letting people contribute code
however they wanted underneath that.  This would mean that we as
caretakers create the following top level directory structure.

|-- apps
|-- chips
|-- libs
|-- platforms
|-- sensorboards
|-- support
|   |-- make
|   |-- sdk
|-- system
|-- tools

We then give free reign to users to do whatever they want underneath
that.  The major drawback of this solution is that there is no
protection between users that know what they are doing and follow this
directory structure correctly, and those that do not.  I can imagine a
situation where some user checks out this tree, starts working on
their own stuff, but overwrites some file in someone elses stuff to
try and make theirs work correctly and then does a blind checkin of
all modified files.  I can actually see this happe3ning quite often
and causing a major frustration between all parties involved.

It is mostly for this reason that we settled on the idea of organizing
the code by institution name/project name at the top level.
Additionally we decided that it was also a way for these institutions
to immediately announce "hey look, OSU or Harvard is contributing code
to intyos".  It would then be the duty of the index file (which by the
way is a webpage) to logically organize any contributed code.  Instead
of sifting through the directories to find what you want, you would
know to look instead in the index.html file at the top level
tinyos-2.x-contrib directory.

Another advantage of this solution is that it gives each institution
the chance to simply play around with their code however they want
underneath their own directories.  They only get references to their
code included in the index when they are ready for it to be, and can
essentially do whatever they want before that.  If they were forced to
put their stuff inside of a top level directory structure containing
an apps, libs, etc. directory then I think they would feel too
pressured to have their code nice and working than instead of trying
things out and putting anything experimental in there.

Maybe institution name is too rigid of a top level structure as seems
to be the consensus, but I definitely don't think its a good idea to
force users into contributing code inside of a rigid top level
framework either.  Like prabal says, who would manage the institution
namespace?  What if there are two completely different projects coming
out of the same institution that don't really have anything to do with
one another whatsoever?  Why should they have to share a namespace?

Maybe the best compromise is to do something of a mixture between what
Joe suggests and how it has been proposed so far.

How does this sound:
1) We as caretakers create the top level directories for people and
restrict write access to them based on the requests of someone
designated as the maintainer of that directory.
2) There is no restriction on how to name top level directories (or
how to organize code underneath it for that matter).  If the first
person from UCLA comes along and thinks that ucla should be the name
of their folder, then they get to take it.  If someone else from UCLA
comes along and doesn't want to work within the same namespace as the
others already within the ucla folder, they can have a folder created
for them with a different name and can work underneath that.
3) We can suggest that each directory follows a structure similar to
what the core does, but ultimately it can be organized in any way
desired.
4) The index file is where to go to look for projects.  Remove the
notion of an unsupported project and only have stable and experimental
ones.  It is up to the contributors to let the caretakers know that
they would like their code included in the index (in either one of the
two categories), and the only restriction for getting in is that they
have some documentation somewhere that the index can point to that
tells users how to use their code.  If the contributors say that they
want their code to be categorised as stable when it really isn't then
that's their loss because users will get frustrated with trying to use
it.

Kevin


On 12/1/06, Joe Polastre <joe at polastre.com> wrote:
> rathole--;
>
> Point of contrib is that people can (in my opinion) "CONTRIBUTE CODE EASILY"
>
> Institution Name Space is a bad idea because a working group (ie,
> something like Apache Labs) should have the ability to commit.  If you
> want the ability to index by type (ie routing protocol), create a
> webpage.  That's what they're for, NOT for creating directory
> structures.
>
> Let it be a free for all with the only requirement being that a
> description has to be provided in the top level directory.  Clearly
> TinyOS is completely lacking contributions, so any barriers you place
> are going to compound the code stifling that already exists.
>
> Best,
> -Joe
>
> On 12/1/06, Prabal Dutta <prabal at cs.berkeley.edu> wrote:
> > On 11/30/06, henri dubois-ferriere <henridf at gmail.com> wrote:
> > > On 01/12/06, Philip Levis <pal at cs.stanford.edu> wrote:
> > > > On Nov 30, 2006, at 12:11 AM, henri dubois-ferriere wrote:
> > > >
> > > > >
> > > > > - Top-level organisation: Why organise things by institution name?
> > > > > That's in my view one of the drawbacks of the 1.x organization. It
> > > > > doesn't seem like a relevant top-level structure (do I typically
> > > > > search for "any code from UCX" or  for "a routing protocol"?), and it
> > > > > also doesn't seem compatible with the hope (I assume that its shared
> > > > > by others) that one day a sizeable amount of contributions come from
> > > > > individuals working on their own account (like for most other
> > > > > successful open source projects).
> > > >
> > > > The directory structure is mostly for management and to keep related
> > > > things close. The index is intended to be the way to find things,
> >
> > By management, do you mean a convention for managing the directory
> > namespace?  Since there's no connection between directory structure
> > and namespace, I don't see the benefit of this organization from a
> > management perspective.  Who within, say "UCB", will help "manage" the
> > UCB namespace?  Will the caretakers do it?  Will the first one who has
> > write access?
> >
> > I also question whether this would actually "keep related things
> > close."  The only relation that is kept close is that the authors all
> > labor under the same organizational umbrella or are co-located
> > geographically.
> >
> > > > e.g., "a routing protocol." Levels of indirection considered helpful.
> > > >
> > >
> > > I understand that such a directory structure certainly isnt to make
> > > searching and browsing easier.
> >
> > I would argue that the proposed structure neither makes management
> > easier nor keeps related things close in a dimension that is relevant
> > to the codebase.  But, something organized around functionality, like
> > Henri suggests, does make searching and browsing easier and more
> > intuitive.
> >
> > > Can you cite any successful (read: that is not written and used in
> > > majority by residents of academia) open source project where things
> > > are organised out based on where the author of some module happens to
> > > work as opposed to what kind of functionality the module actually
> > > offers? I can't.
> >
> > Value judgement: I think related code being close together is more
> > useful than unrelated code created under the aegis of a single
> > organzation.
> >
> > - Prabal
> >
> > > > Phil
> > > >
> > > _______________________________________________
> > > Tinyos-2.0wg mailing list
> > > Tinyos-2.0wg at Mail.Millennium.Berkeley.EDU
> > > https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/tinyos-2.0wg
> > >
> > _______________________________________________
> > Tinyos-2.0wg mailing list
> > Tinyos-2.0wg at Mail.Millennium.Berkeley.EDU
> > https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/tinyos-2.0wg
> >
> _______________________________________________
> Tinyos-2.0wg mailing list
> Tinyos-2.0wg at Mail.Millennium.Berkeley.EDU
> https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/tinyos-2.0wg
>