<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 

page <a href="bug-submission.html">How to submit a bug report</a> or 

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

<p>First, 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>follow the ns-3 coding style

<li>be licensed appropriately

<li>write associated documentation, tests, examples

<li>include a short description with each submission

<li>minimize the size of each submission

<li>changes must 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 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>Licensing and coding style</h2>

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

<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 (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 a comment to help us track you down in case of problems in

the code such as <tt>Author:  john_doe@example.edu</tt>. However, 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.

<p>You may append any contributors to the <tt>AUTHORS</tt> file as you see fit.

<h3>Coding style</h3>

<p>

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

<p>Some of the rules it describes might seem arbitrary to you and you

might disagree with these rules because the resulting code layout

looks ugly to you.  Even so, we ask you to consider carefully the 

purpose of a coding style: the purpose is to ensure that the overall

codebase is consistently indented and laid out to make it easier for a 

trained eye to deal with large amounts of code. 

<p>So, whether you disagree with our layout rules, or you are unsure

about whether a specific piece of code matches the rules, focus

on making sure that the coding style of your code matches the coding 

style of any surrounding ns-3 code.

<p>Of course, minor style errors and uncertainties can be easily 

corrected during reviews, but code submissions with a widescale 

ignorance of the ns-3 coding style will likely be bounced back until 

this step is taken.

<h3>Whitespace changes</h3>

<p>Do not ever submit code which contains whitespace/tab changes mixed

with other non-whitespace changes. Generally, it's a good idea to avoid

submitting whitespace changes at all, but, if you really must, submit

a single change consisting only of whitespace changes.

<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, and may be validation

tests of stochastic behavior.  The test code should try to cover as 

much model code as possible, and should be checked as much as possible

by regression tests.  The project is still refining the testing framework

and will add more detail to this section later, but suffice it to say

for now that new features should come with test code to match; otherwise

it risks falling into disrepair over time.  

<p>

TODO:  Add a reference (perhaps a manual chapter), with some examples and 

samples, of how to write good ns-3 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 the header files, 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> list 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 binary bundle

  <li>a hosted clone

  <li>patchbombs

</ol>

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

<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>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>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>Submitting out-of-tree code</h2>

<p>TODO:  Write about how contributors can send a tarball 

for archiving at code.nsnam.org if they do not want to go through

the process for main-tree code.  Write about src/contrib.