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