Contributing to ns-3

ns-3 is an open source project and seeks contributions from the broad community of users and researchers. If you are interested in contributing to this project, please review the below and decide how you would like to help.

There are many possible ways to contribute to the project:

List discussions

Development discussions occur on the ns-developers mailing list: Join | Archives. Some small discussions may also occur within the tracker (below), but lengthy discussions in the tracker are encouraged to move to the list.

Bugs, patches, feature requests, and tasks

We use a Bugzilla database for tracking bugs, patches, feature requests, and tasks. Changes to the database are logged to the ns-bugs mailing list.

There are two primary ways to log bug reports, patches, or feature requests:

  1. email the ns-developers mailing list
  2. enter the bug into the Bugzilla database yourself
We prefer the second approach; email to the mailing list runs the risk of falling through the cracks. The second approach requires you to create a Bugzilla account.

If you want to enter or report a bug, please do the following three things first:

  1. search bugzilla to see if someone has entered a similar bug.
  2. search Google to see if the bug has been previously encountered and discussed on an email thread
  3. if you are new to reporting bugs, please read the bug writing guidelines on Bugzilla

When using Bugzilla:

Bugs:   Please log the bug with the "bug" keyword in the form provided.

Patches:   Some patches are fixes for bugs and can be added to the existing bug listing. However, sometimes users may contribute a patch that is not tied to a bug (e.g., may be an extension). If you are not familiar with how to prepare patch files, please read this first. If a bug does not exist for this patch, create a new entry and use the keyword "patch". You should find the "Create a New Attachment" choice when editing the bug, allowing you to upload a patch. Alternatively, you could provide a URL to a patch in the "Description" field.

Tasks:   Tasks are items that require developer work and are logged in the Bugzilla database for tracking purposes. Please use the keyword "task" when entering a new task.

Feature requests:   If you want to ask for a developer to charitably provide a new feature, you may opt to create a feature request entry in the database. Please use the keyword "feature-request".

Help and tutorials

The project maintains a wiki for items such as FAQs, troubleshooting, related projects, design suggestions, and suggested projects. Users often turn to wikis for troubleshooting help and tips. If you figure out some non-obvious solution to a problem with ns-3, consider to enter something on the wiki to help others later.

Several people have provided helpful tutorials for ns-2 in the past, including for example:

If you start such a tutorial for ns-3, we can link it here.

Finally, if you find something wrong or incomplete with the project documentation, feel free to contribute a fix to one of the developers.

Code contributions

Many people use ns for their research and then would like to contribute their extensions to the project. Some of these extensions are incorporated into the main distribution, and some are maintained or archived as third-party contributed code. The practice of contributing code has made ns-2 very successful and we want to facilitate that as much as possible.

Licensing and Copyright

The project has decided upon GNU GPLv2 as the licensing structure. All simulation software in the ns-3 repository will be GNU GPLv2 or GNU GPLv2-compatible. We are not asking for copyright transfer but we request that all contributors attest that their modifications can be provided under a GNU GPLv2 license or compatible license.

Contributed code outside of the main distribution

Anyone who wants to provide access to code that has been developed to extend ns-3 may list its availability on our website. Furthermore, we will provide storage on a web server if needed. This type of code contribution will not be formally maintained by the project, although popular extensions might be adopted downstream.

We ask anyone who wishes to do this to provide at least this information on our wiki:

  • Authors,
  • Name and description of the extension,
  • How it is distributed (as a patch or full tarball),
  • Location,
  • Status (how it is maintained)

This link provides examples of the type of information requested. The relevant page on our wiki is here. If you need web server space for your extension, please contact one of the project maintainers.

Contributed code for the main distribution

If you would like the project to maintain an extension of yours in the main distribution, or you would like to work towards that end goal, you are welcome to propose and work on this, but please keep these things in mind along the way:

  • to avoid overlapping and conflicting contributions, please send an email to the ns-developers list stating your interest in working on a specific part of the models and trying to explain how you would like to implement it, what resources you have, etc.
  • you should be prepared to work together with the other potential contributors who want to work on the same models.
  • you should be prepared to go through code reviews with the development team prior to integration. The goal of these code reviews is to:
    • ensure adherence to the coding style of the project,
    • ensure that the structure of your code has a certain coherence with regard to the rest of the ns-3 codebase,
    • improve the quality of the code: we strongly believe in the old saying: "many eyes make all bugs shallow",
    • increase code reuse by trying to generalize certain useful pieces of your code to make them available to other models,
    • encourage unit tests, validation, and documentation. You should be prepared to try to integrate as many tests in the codebase as possible: we understand that writing tests is not necessarily fun and that not everyone is convinced that they improve the code-writing poductivity which is why we do not enforce strict rules about testing. However, we expect model authors to answer basic questions about how they plan to test, document, and validate their models.
  • you should be prepared to maintain your model once it is integrated: while we consider every bug filed against the simulator as being a bug we must deal with and while we will try to fix as many bugs as humanly possible, we also expect model authors to act as responsible maintainers and be reactive to bug reports concerning their models.

The project is maintaining a wiki page for suggested projects for interested researchers or students to undertake.

Maintaining the simulator

If you would like to maintain some part of the simulator (e.g., Windows build, tutorial, wiki, a particular protocol, etc.), please contact someone on the development team.


Generated on 08/Jul/2008 at 21:00:02. Thanks to the XORP (http://www.xorp.org) project for this stylesheet.