[Tinyos Core WG] Instructions for contributing code

Sat Dec 2 01:42:01 PST 2006

I think your 4-point proposal below sounds pretty good. Thanks for
addressing all the concerns.

Henri

On 01/12/06, Kevin Klues <klueska at gmail.com> wrote:
> 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
> >
> _______________________________________________
> 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
>