How to submit new code to ns-3

Introduction

This document summarizes the steps to take to prepare code for submission to ns-3 as a new feature, such as a new feature of an existing simulation model, or a new model altogether. If you are interested in submitting a bugfix to an existing ns-3 feature, or new documentation, see the companion sections How to submit a bug report or How to submit documentation to ns-3.

We actively encourage submission of new features to ns-3. Independent submissions are essential for open source projects, and you will also be credited as an author of future versions of ns-3. However, please keep in mind that there is already a large burden on the ns-3 maintainers to manage the flow of incoming contributions and maintain new and existing code. The goal of this document is thus to outline how you can help to minimize this burden and thus minimize the average time-to-merge of your code. Making sure that each code submission fulfills as many items as possible in the following checklist is the best way to ensure quick merging of your code.

In brief, we can summarize the guidelines as follows, and expand on them in detail below:

If you do not have the time to follow through the process to include your code in the main tree, please see below about contributing ns-3 code that is not maintained in the main tree.

ns-3 code reviews

Code submissions are expected to go through a review process where one or more maintainers comment on the code. Contributors may be asked to revise their code or rewrite portions during this process. New features are also typically only merged during the beginning of a new release cycle, to avoid destabilizing code before release.

ns-3 reviews are conducted on the ns-3-reviews Google group and on the ns-developers mailing list for reviews that involve code that cuts across maintainer boundaries or is otherwise controversial.

The basic purpose of the code reviews is to ensure the long-term maintenance and overall system integrity of ns-3. Going through detailed code reviews is a departure in practice from ns-2, where many contributed modules were integrated without style or consistency requirements. For ns-3, we feel that code reviews are essential to maintaining a high quality simulation tool and reducing the potential for simulation errors.

Some basic principles of the ns-3 reviews are to enforce the coding style requirements and guidelines and to review for consistency in overall system design and performance. A bad outcome (to be avoided) is when the contributor is asked to refactor code that is otherwise stylistically compliant late in the design/review process. Sometimes the contributor may feel annoyed at somewhat arbitrary application of rules. In such a situation, it is best to discuss points in question on the public mailing lists. For aspects of the contribution that are self contained and don't affect the rest of the simulator, when one of the (non-mandatory) coding style or engineering guidelines is perceived to be not followed, maintainers/reviewers should offer suggestions such as "here is the ns-3 way to do that" or "here is how I recommend you should change it" but leave it up to the contributor how he or she wants to deal with the comment. Contributors should respond somehow to review suggestions not followed, even if it is a response like "gee, that is simply too much work to do for the benefit"

Maintainers should be free to ask contributors to rewrite proposed modifications to existing classes in the codebase, such as base classes. Because this is a bad outcome for the contributor, the maintainer should try to avoid this, but if deemed necessary, offer technical rationale why and be willing to debate this on the list (sometimes the maintainer is wrong). If the maintainer is ultimately not convinced, the contributor should follow the maintainer's guidelines. Again, to avoid surprises, contributors are encouraged to contact maintainers early in the process if they are planning to modify existing ns-3 code or APIs.

One final important issue that we touched on briefly above is system integrity. What we have seen in the past from ns-2 is that people contribute models that have been tested within a specific configuration range (e.g. running on a WiFi network only), but may not do something sane with respect to other possible configurations. If we do not look at these overall system issues and require that, at the very least, contributed models do something reasonable when they are configured outside their range of applicability (even if the behavior is just a hard assert), invariably there will be user mail in the future to the effect of "I tried to use model X with configuration Y and got a surprising outcome." That is if we are lucky; the interaction may be error prone but not reveal any warning signs to the user. So, maintainers and reviewers may require contributors to deal with these (current and potential) system issues.

Licensing, copyright, and authorship

All code submitted must conform to the project licensing framework, which is GNU GPLv2 compatibility. All new source files must contain a license statement. All modified source files must either conform to the license of the original file or (in rare cases) may add a license to the original license.

Note that it is incumbent upon the submitter to make sure that the licensing attribution is correct and that the code is suitable for ns-3 inclusion. Do not include code (even snippets) from sources that have incompatible licenses.

If you are writing a new file or making large modifications (e.g. more than 20 or 30 lines) to an existing file, include a copyright statement in the header, such as: Copyright 2009 John Doe. Do not use the phrase All rights reserved.. Optionally, you may also add an author line to help us track you down in case of problems in the code such as Author: john_doe@example.edu. However, for small modifications, do not create a chain of authors by appending to this list in the header such as Modified by Jane Doe 02/04/09; we use Mercurial change history to log who is changing what file.

Coding style

Whatever code you submit, make sure that you follow the ns-3 coding style discussed on a separate page.

Completing your code submission

Often we have observed that contributors will provide nice new classes implementing a new model, but will fail to include supporting test code, example scripts, and documentation. Therefore, we ask people submitting the code (who are in the best position to do this type of work) to provide documentation, test code, and example scripts.

Note that you may want to go through multiple phases of code reviews, and all of this supporting material may not be needed at the first stage (e.g. when you want some feedback on public API header declarations only, before delving into implementation). However, when it times come to merge your code, you should be prepared to provide these things, as fits your contribution (maintainers will provide some guidance here).

Including examples

For many submissions, it will be important to include at least one example that exercises the new code, so the reviewer understands how it is intended to be used. For final submission, please consider to add as many examples as you can that will help new users of your code. The samples/ and examples/ directories are places for these files.

Testing

Every new code should include automated tests. These should, where appropriate, be unit tests of model correctness, validation tests of stochastic behavior, and overall system tests if the model's interaction with other components must be tested. The test code should try to cover as much model code as possible, and should be checked as much as possible by regression tests.

A separate ns-3 testing and validation manual provides documentation and suggestions for how to write tests.

Documentation

If you add a new features, or make changes to existing features, you need to update existing or write new documentation and example code. Consider the following checklist:

Preparing your code for review

Description

For each code submission, include a description of what your code is doing, and why. Ideally, you should be able to provide a summary description in a 5-line paragraph with a 1-line (15 word) subject. If you fix a bug filed in our bugzilla database, the subject should include first the bug number, and then, the bug title. For example: bug 558: qos-tag.h is gone missing from wscript

Bonus points go to submitters who provide a description of their testing strategy.

Minimize the size of each submission

Each submission should be as small as possible. Ideally, each submission should deal with one issue only. If your description of your submission includes words such as and, it is a big red warning sign that you should think about splitting your submission in two separate smaller submissions, if the changes are not intertwined.

Coherent changes

Each submission should be a coherent whole: if you need to edit ten files to get a feature to work, then, the submission should contain all the changes for these ten files. Of course, if you can split the feature in sub-features, then, you should do it to decrease the size of the submission as per the previous item.

For example, if you have made changes to optimized a module and to fix a bug in another module, make sure you separate these two sets of changes in two separate submissions.

Multi-part submissions

If you are working on a large new feature or a large refactoring, and because you will attempt to minimize the size of your submissions, you will have to split your large work in multiple separate submissions.

Ideally, these submissions will be started by a detailed explanation of the overall plan such that code reviewers can review each submission separately but within a large context. This kind of work typically is split in multiple dependent steps where each step depends on the previous one. If this is the case, make it very clear in your initial explanation. If you can, minimize dependencies between each step such that reviewers can merge each step separately without having to consider the impact of merging one submission on other submissions.

Before sending a submission

When you send a submission for review and merging in ns-3, before you hit the 'Send' button of your email client, ask yourself one last time: If I were a reviewer, and I had to review that submission, what would I do ?. Specifically, make sure that you have provided enough context to allow someone else to understand what you did and why. Keep in mind that your reviewer does not have access to a readable dump of your brain: he has access only to your code, and your emails.

Submission tools

There are many ways to submit a piece of code. Some of them are not appropriate:

Others are more appropriate:

  1. a simple patch
  2. patch reviews at codereview
  3. a hosted clone
  4. a binary bundle
  5. patchbombs

Most submissions to ns-3 use the first three techniques.

  1. a simple patch

    Patches can be attached to a bug report or sent to our developer mailing-lists.

    The UNIX diff tool is the most common way of producing a patch: a patch is a text-based representation of the difference between two text files or two directories with text files in them. If you have two files, original.cc, and, modified.cc, you can generate a patch with the command diff -u original.cc modified.cc. If you wish to produce a patch between two directories, use the command diff -uprN original modified.

    Make sure you specify to the reviewer where the original files came from and make sure that the resulting patch file does not contain unexpected content by performing a final inspection of the patch file yourself.

    Patches such as this are sufficient for simple bug fixes or very simple small features.

  2. patch reviews at codereview

    The best way to submit a larger patch for consideration is to request a patch review:

    1. download upload.py
    2. record the changes you want to request a review for in a mercurial repository: hg commit ...
    3. within the mercurial repository, run upload.py. Make sure you specify ns-3-reviews@googlegroups.com as a CC.
    4. announce your review request on ns-developers

    When you send a tree without a detailed summary of your changes, it would help if you could send a list of the changesets you want to merge. To generate it, first merge with ns-3-dev and then, from your modified directory, run hg outgoing -p http://code.nsnam.org/ns-3-dev

    If you already pulled changes from ns-3-dev into your private repository after you started doing your private modifications, there is an issue to be considered. upload.py does not let you specify a range of revisions, nor a set of changesets. So if you just run upload.py in your private repository, the changesets pulled from ns-3-dev will also be published on codereview, which is, of course, not desirable.

    A possible workaround is to pull your changes into a temporary repository which is an up-to-date clone of ns-3-dev. The following code should do the trick. This code assumes that your private repository is in path DEV_BRANCH_WITH_NEW_FEATURE, and that it is in sync with ns-3-dev.

    hg clone http://code.nsnam.org/ns-3-dev ns-3-tmp
    cd ns-3-tmp
    export REVNO=`hg tip -q | sed 's/:.*$//'`
    hg pull DEV_BRANCH_WITH_NEW_FEATURE
    hg merge
    hg commit -m "merged new feature"
    upload.py --rev=$REVNO --cc=ns-3-reviews@googlegroups.com 
    

    To update a previous issue with a new patchset, use the -i (--issue) option to avoid the tool creating a new issue. For instance, if the issue to which you want to add a new patchset is numbered 165087, you would do

    hg commit -m "merged new feature"
    upload.py --rev=$REVNO --issue=165087 --cc=ns-3-reviews@googlegroups.com
    
  3. Hosted clones

    If your bundles grow large in size, it can become tricky to send them over email: hosting a clone of your mercurial repository is a simple way to work around this. If you have a host with a static ip address and/or a hostname, you can run hg serve within your repository in this host and send instead to your co-workers a url to that repository: if I run hg serve -d -p 8080 on my local ns-3-dev clone, I could send the url http://diese.inria.fr:8080/ to my co-workers to allow them to pull all my development history from there.

    If you don't have a static ip address or hostname, or are located behind a NAT or a firewall, you have to use a third-party hosting provider for your code. A small list of hosting providers is available there

    We can also provide hosting to ns-3 developers on code.nsnam.org should none of the above alternative work for you.

  4. Binary bundles

    ns-3 uses mercurial as its version control tool: a quick introduction to using it can be found on our homepage. Further extensive documentation and manuals are available from the mercurial homepage.

    If you get used to use mercurial to record your daily/hourly work using mercurial in a local clone of the ns-3 main repository, and if you want to share that work with other people to get initial feedback about your work, your implementation approach, and start a high-level discussion about it, you can easily package all your local work history as a single binary bundle file with the hg bundle command and send this file over email.

  5. Patchbombs

    Patchbombs are a nice way to perform a request for a detailed review. Make sure you enable the patchbomb extension in your ~/.hgrc:

    [extensions]
    hgext.patchbomb = 
    
    Make sure you configure your patchbomb extension correctly: man 5 hgrc and look in the [email] and [smtp] sections Finally:
    hg email -i -t ns-developers@isi.edu http://code.nsnam.org/ns-3-dev
    

    Beware that generating too many emails with this tool without doing proper history rewriting to produce clean easy-to-review patches will be considered rude.

History rewriting

The idea behind history rewriting is to request a code submitter to re-arrange their repository history prior to merging in the main ns-3 repository.

For example, let's say that during development of a new feature, you decide to use your mercurial repository as a fancy version-enabled backup system: you do a lot of work, and regularly commit it to save it. When you are done implementing and testing that new feature, the resulting repository history as shown with hg log will look very verbose, and will most likely contain a lot of commit messages such as fix bug. Clearly, none of these commits are very helpful and there is little point in keeping them around: they make it painful to use the annotate, and bisect commands, and will make review of the final mercurial tree harder than it need to be.

A simple way to work around these problems is to ask each contributor to re-structure their commit history before submitting their tree for review:

  1. Rewrite a new history from scratch

    Once you are done with a new feature, you can generate one final patch with the mercurial diff command and apply it to a clean repository as one single commit with a nice new commit message.

    A variant on the above is to split the final commit in multiple smaller commits, each of which addresses one aspect of the final feature and make sure that each commit is still buildable.

  2. Build clean history from the start

    Instead of using mercurial as a powerful backup system and trying to go back later, some users prefer to use tools such as 'mq' or 'pbranch' to split their work from the start in a set of separate entities and still record somewhere their day-to-day development history.

    More information on these tools:

Submitting out-of-tree code

Anyone who wants to provide access to code that has been developed to extend ns-3, but who chooses not to go through the above review process, 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:

The contribution will be stored on our wiki here. If you need web server space for your extension, please contact one of the project maintainers.