Contributing Code to TinyOS

File:Tos-jwall.jpg

Using TinyOS 1.x Projects

The contributed project for TinyOS 1.x are located in the contrib directory of the TinyOS 1.x CVS repository. To access the projects check out a copy of the "tinyos-1.x" CVS repository (instructions here).

Using TinyOS 2.x Projects

Contributed TinyOS 2 projects are organized in The TinyOS 2.x Index of Contributed Code. This index provides a short description and a contact for each project as well as a link to detailed instructions. To access the projects check out a copy of the tinyos-2.x-contrib CVS repository (instructions here).

Contributing Code

We welcome code contributions to the TinyOS source code base and have tried to make contributing as easy as possible. In order to contribute code, you must first obtain a SourceForge developer account. If you don't have an account yet, see SourceForge for details on how to get one.

Once you have obtained your SourceForge user account send an email to tinyos-contrib-caretakers@millennium.berkeley.edu indicating your intent to contribute code. TinyOS 1.x and 2.x have slightly different processes for contributing code, as described below.

It should be noted that since all contributed code is ultimately stored in a CVS repository it is highly discouraged to contribute anything not directly related to the code or documentation supporting a project under development. For example, video, audio, or sensor data gathered using the code contributed for your project should NOT be committed to the CVS repository. If you want others to have access to data of this type, you should instead provide some documentation pointing them to a location where it can be downloaded from (e.g. a webpage maintained on your local server).

Contributing Code to TinyOS 1.x

If you are contributing code to TinyOS 1.x then you only need to provide the following information in your email:

1. Your intent to contribute code to TinyOS 1.x and not TinyOS 2.x
2. A list of SourceForge developer usernames you would like to be given access for contributing code

Once you receive a confirmation email indicating that your users have been granted developer access, you should be ready to go. Simply checkout the tinyos-1.x source tree from SourceForge following the instructions found here, and create your project directory under tinyos-1.x/contrib. Make sure you follow the directions for "Developer CVS Access via SSH" and that you use tinyos-1.x as the module name when checking out the tree. If you are unfamiliar with CVS and how to use it, a short tutorial to get you started can be found here.

Once you have been granted access, you will have free reign to create and modify any directories or files located under tinyos-1.x/contrib. You should create directories of your own in order to organize your code and keep it separate from everyone elses. Some developers like to name their directories after the institution they are affiliated with (e.g. ucb, wustl, motiv, xbow). Others like to name them after the project their code is associated with (e.g. s-mac, mate, nucleus). It is entirely up to you how to organize them. If you would like write access to a particular directory restricted to a specific set of users, please send an email to tinyos-contrib-caretakers@millennium.berkeley.edu and we will accomodate your request as best we can.

Contributing Code to TinyOS 2.x

The process for contributing code to TinyOS 2.x is a little stricter than for TinyOS 1.x. A set of caretakers have been assigned to ensure that any contributed code follows a certain set of guidelines. When sending an email requesting access to contribute code for TinyOS 2.x please include the following information:

1. Your intent to contribute code to TinyOS 2.x and not TinyOS 1.x.
2. The name of a directory underneath which all of your contributed code will be contained.
3. The name and email address of someone who will act as the point of contact for maintaining that directory
4. A list of SourceForge developer usernames you would like to be given access for contributing code underneath that directory.
5. A short description of any projects you plan to develop inside of that directory. Please write one to three sentences about each project for inclusion in an index that lists all contributed code. You can always write another email later if you start working on other projects and you want them included in the index as well.

Once you receive a confirmation email indicating that your users have been granted developer access, you can checkout the tinyos-2.x-contrib source tree from SourceForge following the instructions found here. Make sure you follow the directions for "Developer CVS Access via SSH" and that you use tinyos-2.x-contrib as the module name when checking out the tree. If you are unfamiliar with CVS and how to use it to commit your code, a short tutorial to get you started can be found here.

Unlike in TinyOS 1.x where developers have free reign to commit files anywhere they please underneath tinyos-1.x/contrib, commit access is restricted under tinyos-2.x-contrib to the specific directory created for each group. Many developers like to name this directory after the institution with which their project is affiliated. For projects being developed across multiple institutions, however, it may be appropriate to specify a project name instead of an institution. If a directory name is already taken underneath which you would like to contribute code, you can either (1) directly contact the maintainer of that directory to work out a plan for contributing your code underneath it, (2) request the creation of a new directory by the contrib-caretakers. If you choose to follow (1), then it is your responsibility to have the maintainer of that directory send an email to the contrib caretakers requesting that you be given access to it. They should also provide a short description of your project for inclusion in the index. The most common reason for following this course of action is when two different groups at the same institution would like their code included under the same directory name.

While there is no restriction on how to organize your contributed code, it is highly encouraged to try and mimic the organizational structure used in the tinyos-2.x core. By mimicking this organization, it is easier for anyone wanting to use this code to navigate it and understand it. It is also easier to migrate it into the core if its status ever gets promoted. This does not mean that code from the core should be replicated in these directories, but rather that any newly contributed code should try and follow a similar structure. For example, the directory structure would look like the following for someone at UCLA developing a set of libraries and applications (a skeleton is provide in the skel directory of tinyos-2.x-contrib including a Make setup):

 tinyos-2.x-contrib
 |-- ucla
 |   |-- apps
 |   |   |-- uclaApp0
 |   |   |-- uclaApp1
 |   |-- lib
 |   |   |-- uclaLib0
 |   |   |-- uclaLib1
 

For an institution working on the development of two new platforms that contain a set of new chips and platform specific code, the directory structure might look like this.

 tinyos-2.x-contrib
 |-- institution_name
 |   |-- chips
 |   |   |-- mcuChip
 |   |   |-- chip1
 |   |   |-- chip2
 |   |-- platforms
 |   |   |-- platform0
 |   |   |   |-- .platform
 |   |   |-- platform1
 |   |   |   |-- .platform
 |   |-- support
 |   |   |-- make
 |   |   |   |-- mcuChip
 |   |   |   |   |-- mcuChip.rules
 |   |   |   |-- platform0.extra
 |   |   |   |-- platform1.extra
 

In general, the organizational structure could look like the following:

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

If you would like any or all of these directories to be created for you at the time your top level directory is created, please indicate so in your email to tinyos-contrib-caretakers@millennium.berkeley.edu.

As indicated earlier, one of the duties of the TinyOS 2.x contrib caretakers is to maintain an index of all contributed code. This index is located directly underneath the tinyos-2.x-contrib directory in a file called index.html. All contributed projects will be included in this index with the following information:

• The name of the project
• The name and email address of the developer in charge of maintaining the project
• The name of the institution working on the project
• The date the project was last updated in the index
• A short two or three sentence description of the project

The name of the project will contain a link to a local index.html file created for you underneath your top level directory. This file is used to document the projects contained in that directory. Some people will prefer to write their project documentation directly within their local.html file. Others will prefer to use this file to redirect users to another webpage maintained on a different server. It is in your best interest to make this documentation as comprehensive as possible so that other people will know how to use your code.

Depending on the status of each project, different projects will be organized into different categories.

• Stable Projects contain code that the developers of that project consider to be in a stable operating state. Developers should request to have their projects moved into this category once they are mostly completed and are only maintained by minor bug fixes and improvements.
• Experimental Projects contain code that is in a constant state of flux. Whenever a project is newly created it will be entered into the index under this category.
• Stable but Unsupported Projects contain code that was previously categorized as stable but is no longer being maintained by anyone.
• Unsupported Projects contain code that was previously categorized as experimental but is no longer being maintained by anyone.

Note that if code has existed in the repository in either the "Stable" or "Experimental" categories for more than 6 months without any new commits to it, an email will be sent to whoever is in charge of maintaining it. If there is no response after 1 week, a second email will be sent. If after another week there is still no response, the project will be demoted to either the "Unsupported" or "Stable but Unsupported" categories depending on how it had been categorized previously. In order to make sure that this doesn't happen to you, please keep the contrib caretakers up to date on the current maintainer of your project.