2. General

This section pertains to general topics about licensing, coding style, and working with Git features, including patch submission.

2.1. Licensing

All code submitted must conform to the project licensing framework, which is GNU GPLv2 compatibility. All new source files should contain a license statement. In general, we ask that new source files be provided with a GNU GPLv2 license, but the author may select another GNU GPLv2-compatible license if necessary. GNU GPLv3 is not accepted in the ns-3 mainline. Note that the Free Software Foundation maintains a list of GPLv2-compatible licenses.

If a contribution is based upon or contains copied code that itself uses GNU GPLv2, then the author should in most cases retain the GPLv2 and optionally extend the copyright and/or the author (or ‘Modified by’) statements.

If a contribution is borrowed from another project under different licensing, the borrowed code must have a compatible license, and the license must be copied over as well as the code. The author may add the GNU GPLv2 if desired, but in such a case, should clarify which aspects of the code (i.e., the modifications) are covered by the GPLv2 and not found in the original. The Software Freedom Law Center has published guidance on handling this case.

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. Even if the code licenses are compatible, do not copy someone else’s code without attribution.

2.1.1. Documentation Licensing

Licensing for documentation or for material found on ns-3 websites is covered by the Creative Commons CC-BY-SA 4.0 license, and documentation submissions should be submitted under that license. Please ensure that any documentation submitted does not violate the terms of another copyright holder, and has correct attribution. In particular, copying of substantial portions of an academic journal paper, or copying or redrawing of figures from such a paper, likely requires explicit permission from the copyright holder.

2.3. Attribution

Besides copyright, authors also often seek to list attribution, or even credit for funding, in the headers. We request that contributors refrain from aggressively inserting statements of attribution into the code such as:

// New Hello Timer implementation contributed by John Doe, 2014

especially for small touches to files, because, over time, it clutters the code. Git logs are used to track who contributed what over time.

Likewise, if someone contributes a minor enhancement or a bug fix to an existing file, this is not typically justification to insert an Authored by or Copyright statement at the top of the file. If everyone who touched a file did this, we would end up with unwieldy lists of authors on many files. In general, we recommend to follow these guidelines:

  • if you are authoring a new file or contributing a substantial portion of code (such as 30% or more new or changed statements), you can list yourself as co-author or add a new copyright to the file header

  • if you are modifying less than the above, please refrain from adding copyright or author statements as part of your patch

  • do not put your name or your organization’s name anywhere in the main body of the code, for attribution purposes

An example of a substantial modification that led to extension of the authors section of the header can be found in src/lte/model/lte-ue-phy.h:

* Author: Giuseppe Piro  <g.piro@poliba.it>
* Author: Marco Miozzo <mmiozzo@cttc.es>
* Modified by:
*          Vignesh Babu <ns3-dev@esk.fraunhofer.de> (RLF extensions)
*/

Here, there were two original authors, and then a third added a substantial new feature (RLF extensions).

Please work with maintainers to balance the competing concerns of obtaining proper attribution and avoiding long headers.

2.4. Coding style

We ask that all contributors make their code conform to the coding standard which is outlined in Coding style.

The project maintains a Python program called check-style-clang-format.py found in the utils/ directory. This is a wrapper around the clang-format utility and can be used to quickly format new source code files proposed for the mainline. The ns-3 coding style conventions are defined in the corresponding .clang-format file.

In addition to formatting source code files with clang-format, the Python program also checks trailing whitespace in text files and converts tabs to spaces, in order to comply with the ns-3 coding style.

2.5. Creating a patch

Patches are preferably submitted as a GitLab.com Merge Request. Short patches can be attached to an issue report or sent to the mailing-lists, but a Merge Request is the best way to submit.

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.

Git can be used to create a patch of what parts differ from the last committed code; try:

$ git diff

The output of git diff can be redirected into a patch file:

$ git diff > proposal.patch

Keep in mind that git diff could include unrelated changes made locally to files in the repository (a common example is .vscode/launch.json). In order to avoid cluttering, please amend your diff file using a normal text editor before submitting it.

Likewise, if you submit a merge request using GitLab, please add only the changes to the relevant files to the branch you’re using for the merge request.

2.6. Maintainers

Maintainers are the set of people who make decisions on code and documentation changes. Maintainers are contributors who have demonstrated, over time, knowledge and good judgment as pertains to contributions to ns-3, and who have expressed willingness to maintain some code. ns-3 is like other open source projects in terms of how people gradually become maintainers as their involvement with the project deepens; maintainers are not newcomers to the project.

The list of maintainers for each module is found here: https://www.nsnam.org/developers/maintainers/

Maintainers review code (bug fixes, new models) within scope of their maintenance responsibility. A maintainer of a module should “sign off” (or approve of) changes to an ns-3 module before it is committed to the main codebase. Note that we typically do not formalize the signing off using Git’s sign off feature, but instead, maintainers will indicate their approval of the merge request using GitLab.com.

Note that some modules do not have active maintainers; these types of modules typically receive less maintenance attention than those with active maintainers (and bugs may linger unattended).

The best way to become a maintainer is to start by submitting patches that fix open bugs or otherwise improve some part of the simulator, and to join in on the technical discussions. People who submit quality patches will catch the attention of the maintainers and may be asked to become one at some future date.

People who ask to upstream a new module or model so that it is part of the main ns-3 distribution will typically be asked to maintain it going forward (or to find new maintainers for it).