<h1>How to submit new code to ns-3</h1>

 <h2>Introduction</h2>

 <p>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 <a href="contributing.html#bugs">How to submit a bug report</a> or 

 <a href="contributing.html#documentation">How to submit documentation</a> to ns-3.</p>

 <p>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. 

 </p>

 <p>

 In brief, we can summarize the guidelines as follows, and expand on them

 in detail below:

 <ul>

 <li>be licensed appropriately

 <li>follow the ns-3 

 <a href="http://www.nsnam.org/codingstyle.html">coding style and

 engineering guidelines </a> 

 <li>write associated documentation, tests, examples

 <li>include a short description with each submission

 <li>minimize the size of each submission

 <li>changes should be coherent!

 <li>split your code into multi-part submissions

 <li>before sending a submission: ask yourself <i>if I were a reviewer, would I understand the submission?</i>

 <li>pick a submission tool:

   <ul>

     <li>a simple patch

     <li>a patch review

     <li>a binary bundle

     <li>a hosted clone

     <li>patch emails

   </ul>

 <li>consider rewriting your development history

 </ul>

 <p>

 If you do not have the time to follow through the process to include your

 code in the main tree, please see <a href="#out-of-tree">below</a> about 

 contributing ns-3 code that is not maintained in the main tree.

 </p>

 <h2>ns-3 code reviews</h2>

 <p>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.  

 <p>ns-3 reviews are conducted on the 

 <a href="http://groups.google.com/group/ns-3-reviews"> ns-3-reviews Google 

 group</a> and on the ns-developers

 mailing list for reviews that involve code that cuts across maintainer

 boundaries or is otherwise controversial.  

 <p>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.

 <p>Some basic principles of the ns-3 reviews are to enforce the 

 <a href="codingstyle.html">coding style requirements and guidelines</a>

 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"

 <p> 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.

 <p>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. 

 <h2>Licensing, copyright, and authorship</h2>

 <p>

 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.  

 <p>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.

 <i>Do not</i> include code (even snippets) from sources that have incompatible

 licenses.

 <p>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: 

 <tt>Copyright 2009 John Doe</tt>. Do not use the phrase <tt>All rights reserved.</tt>.

 Optionally, you may also add an author line to help us track you down in case of problems in

 the code such as <tt>Author:  john_doe@example.edu</tt>. However, for

 small modifications, do not create a chain of authors by

 appending to this list in the header such as <tt>Modified by Jane Doe 02/04/09</tt>;

 we use Mercurial change history to log who is changing what file.

 <h2>Coding style</h2>

 <p>

 Whatever code you submit, make sure that you follow the ns-3 <a href="http://www.nsnam.org/codingstyle.html">coding style</a> discussed on a separate page.

 <h2>Completing your code submission</h2>

 <p>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.

 <p>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).

 <h3>Including examples</h3>

 <p>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 <tt>samples/</tt> and <tt>examples/</tt>

 directories are places for these files.

 <h3>Testing</h3>

 <p>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.  

 <p> A separate <a href="http://www.nsnam.org/docs/testing.html">ns-3 testing 

 and validation manual</a> provides documentation and suggestions for 

 how to write tests.

 <h3>Documentation</h3>

 <p>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:

 <ul>

   <li>doxygen should be added to header files for public classes and methods, 

 and should be checked for doxygen errors

   <li>incompatible API changes must be documented in <tt>CHANGES.html</tt>

   <li>new features should be described in <tt>RELEASE_NOTES</tt>

   <li>new API or changes to existing API must update the inline doxygen

     documentation in header files

   <li>consider updating or adding a new section to the tutorial in <tt>doc/tutorial/</tt>

   <li>consider updating or adding a new section to the manual in <tt>doc/manual/</tt>

   <li>update the <tt>AUTHORS</tt> file as appropriate

 </ul>

 <h2>Preparing your code for review</h2>

 <h3>Description</h3>

 <p>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 <a href="http://www.nsnam.org/bugzilla">bugzilla database</a>, 

 the subject should include first the bug number, and then, the bug title.

 For example: <tt>bug 558: qos-tag.h is gone missing from wscript</tt>

 <p>Bonus points go to submitters who provide a description of their 

 testing strategy.

 <h3>Minimize the size of each submission</h3>

 <p>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 <i>and</i>, 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.

 <h3>Coherent changes</h3>

 <p>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.

 <p>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.

 <h3>Multi-part submissions</h3>

 <p>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.

 <p>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.

 <h3>Before sending a submission</h3>

 <p>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: <i>If I were a reviewer, and I had to review that submission,

 what would I do ?</i>. 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.

 <h3>Submission tools</h3>

 <p>

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

 appropriate:

 <ul>

   <li>do not send us a modified version of each file you have changed

   <li>do not send us a .zip or .tar.gz file by email with a copy of

 every modified file

   <li>do not send us a patch against an unspecified version of ns-3

 </ul>

 <p>Others are more appropriate:

 <ol>

   <li>a simple patch

   <li>patch reviews at <a href="http://codereview.appspot.com">codereview</a>

   <li>a hosted clone

   <li>a binary bundle

   <li>patchbombs

 </ol>

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

 <ol>

 <li><b>a simple patch</b>

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

 <p>The UNIX <tt>diff</tt> 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, <tt>original.cc</tt>, and, <tt>modified.cc</tt>, you can generate a patch

 with the command <tt>diff -u original.cc modified.cc</tt>. If you wish to

 produce a patch between two directories, use the command 

 <tt>diff -uprN original modified</tt>.

 <p>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.

 <p>Patches such as this are sufficient for simple bug fixes or very simple

 small features.

 <li><b>patch reviews at <a href="http://codereview.appspot.com">codereview</a></b>

 <p>The best way to submit a larger patch for consideration is to request 

 a patch review:

 <ol>

 <li>download <a href="http://codereview.appspot.com/static/upload.py">upload.py</a>

 <li>record the changes you want to request a review for in a mercurial 

 repository: <tt>hg commit ...</tt>

 <li>within the mercurial repository, run upload.py. Make sure you specify 

 <tt>ns-3-reviews@googlegroups.com</tt> as a CC.

 <li>announce your review request on ns-developers 

 </ol>

 <p>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 <tt>hg outgoing -p http://code.nsnam.org/ns-3-dev</tt>

 <p>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 <tt>upload.py</tt> in your private 

 repository, the changesets pulled from ns-3-dev will also be published 

 on codereview, which is, of course, not desirable.

 <p>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.

 <pre>

 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 

 </pre>

 <p>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

 <pre>

 hg commit -m "merged new feature"

 upload.py --rev=$REVNO --issue=165087 --cc=ns-3-reviews@googlegroups.com

 </pre>

 <li><b>Hosted clones</b>

 <p>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 <tt>hg serve</tt> within your repository in this host and send instead

 to your co-workers a url to that repository: if I run <tt>hg serve -d -p 8080</tt> 

 on my local ns-3-dev clone, I could send the url <tt>http://diese.inria.fr:8080/</tt>

 to my co-workers to allow them to pull all my development history from there.

 <p>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 

 <a href="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">there</a>

 <p>We can also provide hosting to ns-3 developers on <a href="http://code.nsnam.org/">code.nsnam.org</a>

 should none of the above alternative work for you.

 <li><b>Binary bundles</b>

 <p>ns-3 uses <a href="http://www.selenic.com/mercurial/">mercurial</a> as its 

 version control tool: a quick introduction to using it can be found on our 

 <a href="http://www.nsnam.org/mercurial.html.">homepage</a>.

 Further extensive documentation and manuals are available from the mercurial

 <a href="http://www.selenic.com/mercurial/">homepage</a>.

 <p>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 <tt>hg bundle</tt> command and send this file over email. 

 <li><b>Patchbombs</b>

 <p>Patchbombs are a nice way to perform a request for a detailed

 review. Make sure you enable the patchbomb extension in your ~/.hgrc:

 <pre>

 [extensions]

 hgext.patchbomb = 

 </pre>

 Make sure you configure your patchbomb extension correctly: 

 <tt>man 5 hgrc</tt> and look in the [email] and [smtp] sections

 Finally:

 <pre>

 hg email -i -t ns-developers@isi.edu http://code.nsnam.org/ns-3-dev

 </pre>

 <p>Beware that generating too many emails with this tool without doing

 proper <i>history rewriting</i> to produce clean easy-to-review patches will

 be considered rude.

 </ol>

 <h3>History rewriting</h3>

 <p>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. 

 <p>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 <tt>hg log</tt> will look very verbose, and

 will most likely contain a lot of commit messages such as <i>fix bug</i>.

 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.

 <p>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:

 <ul>

   <li>pointless backup commits are deleted from the history

   <li>commits are re-organized in sub-feature commits

   <li>each commit is made buildable

   <li>etc.

 </ul>

 <ol>

 <li><b>Rewrite a new history from scratch</b>

 <p>Once you are done with a new feature, you can generate one final patch

 with the mercurial <tt>diff</tt> command and apply it to a clean repository

 as one single commit with a nice new commit message.

 <p>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.

 <li><b>Build clean history from the start</b>

 <p>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.

 <p>More information on these tools:

 <ul>

 <li><a href="http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html">Managing change with mercurial queues</a>

 <li><a href="http://hgbook.red-bean.com/read/advanced-uses-of-mercurial-queues.html">Advanced uses of mercurial queues</a>

 <li>The <a href="http://arrenbrecht.ch/mercurial/pbranch/">Pbranch</a> extension.

 </ul>

 </ol>

 <h2><a name="out-of-tree">Submitting out-of-tree code</a></h2>

 <p>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.

 <p>We ask anyone who wishes to do this to provide at least this information

 on our wiki:

 <ul>

 <li>Authors,</li>

 <li>Name and description of the extension,</li>

 <li>How it is distributed (as a patch or full tarball),</li>

 <li>Location,</li>

 <li>Status (how it is maintained)</li>

 </ul>

 <p>The contribution will be stored on our wiki 

 <a href="wiki/index.php/Contributed_Code">here</a>.  

 If you need web server space for your extension, please

 contact one of the project maintainers.