5. Submitting externally maintained code

This chapter mainly pertains to code that will be maintained in external repositories (such as a personal or university research group repository, possibly hosted on GitHub or GitLab.com), but for which the contributor wishes to keep consistent and compatible with the ns-3 mainline.

If the contributor does not want to maintain the external code but wants to make the community aware that it is available with no ongoing support, links to the code can be posted on the ns-3 wiki contributed code page. A typical example is the graduating student who wishes to make his or her thesis-related code available but who does not plan to update it further. See Unmaintained, contributed code below.

However, much of the emphasis of this chapter is on hosting ns-3 extensions in the ns-3 App Store.

5.1. Rationale for the app store

Historically, ns-3 tried to merge all code contributions (that met the contribution guidelines) to the mainline. However, this approach has reached its limits in terms of scalability:

1. As ns-3 includes more lines of code, it takes longer to compile, while users typically only need a subset of the available ns-3 model code.
2. Merging to the mainline requires maintainer participation for code reviews (which can be time consuming for maintainers), resulting in some contributions not being merged due to lack of code reviews.

The app store federates the maintenance of ns-3 modules, and puts more control in the hands of the contributor to maintain their code. The idea is to provide a central place where users can discover ns-3 extensions and add them to their ns-3 installation. One of the drawbacks of this approach, however, is the potential for a lot of compatibility headaches, such as a user trying to use two separately developed modules, but the modules are compatible with different ns-3 mainline versions. Therefore, the app store is designed to assist in testing and clarifying which version of the external module is compatible with which mainline version of ns-3.

In brief, what it means for ns-3 users is the following. There is an empty directory in the ns-3 source code tree called contrib. This directory behaves the same way (with respect to the build system) as the src directory, but is the place in which externally developed models can be downloaded and added to ns-3.

For contributors, the app store provides a means for module developers to make releases on their own schedule and not be tied to the release schedule of the mainline, nor to be blocked by mainline code reviews or style requirements. It is still possible (and recommended) to obtain code reviews and follow style guidelines for contributed modules, as described below.

5.1.1. Example app

For example, consider a user who wants to use a model of the LoRaWAN sensor networking protocol in ns-3. This model is not available in the mainline ns-3 releases, but the user checks in the App Store. Sensor networking protocols can be found by browsing the category Sensor Networks in the left-hand menu, upon which the LoRaWAN module is displayed. This module is maintained by an external research group. Clicking on the app icon leads to a page in which more details about this module are displayed, including Release History, Installation, and Maintenance.

The installation tab suggests two primary ways to add a lorawan module to an ns-3 installation:

1. Download a source archive from the link provided on the app store and unpack it in the contrib/ directory.
2. Perform a git clone operation from within the ns-3 contrib/ directory.

There is a third way in general, which is to use the Bake build system to add or remove modules. Most modules have a bakeconf.xml file associated with them, which can be added to the contrib/ folder of Bake. This permits bake configuration operations such as:

$ ./bake.py configure -e ns-3.34 -e lorawan-0.3.0
$ ./bake.py download
$ ./bake.py build

Users will be concerned about which version of the module applies to the version of ns-3. The Release History tab describes the releases and the minimum (and, optionally, the maximum) ns-3 version that the release works with.

Finally, information about how the module will continue to be maintained, and how to submit issue reports or ask questions about it, are typically posted in the optional Maintenance or Development tabs.

5.2. App types

Two types of “apps” are hosted on the app store: 1) contributed modules, and 2) forks of ns-3. It benefits users the most when contributed code can be added as modules to the contrib directory, because this allows the modules to be used with different versions of the ns-3 mainline and to combine multiple such modules. However, some authors have chosen to create a full fork of ns-3, and to publish full ns-3 source trees. One reason for such forks is if the fork requires intrusive changes to the ns-3 mainline code, in such a manner that the patch will likely not be accepted in the mainline. For an example of a full fork in the app store, see the Public Safety Communications app page; this is a full fork because of the intrusive changes to the mainline LTE module necessary to support the public safety extensions.

Sometimes a contributed module does require a very small patch to the mainline despite being largely implemented in a modular way. In this case, the best strategy is to try to create a minimal patch to upstream to the mainline, and work with maintainers to incorporate it. Even if this is not successful or not attempted, one can maintain a small patch file as part of the module, and bake build instructions for the module can be extended to patch the mainline code as the first step in the build process. Please consult the app store maintainers if guidance on this approach is needed.

5.3. Submitting to the app store

If you are interested in adding an app to the app store, contact webmaster@nsnam.org or one of the app store maintainers. Before getting started, browse through the existing apps so that you get a feel for what type of information will be required.

The main requirements are:

1. Define a module name that will be the name of the subdirectory in the contrib folder. Use ns-3 naming conventions for directory names; i.e., all lower case, with separate words separated by dashes.
2. Ensure that your module can be successfully cloned into the contrib folder using the proposed module name, that it builds successfully, and that all examples and tests run.
3. Make at least one release on your GitHub or GitLab.com, associated with the latest ns-3 release if possible. To do this, you will need to decide on a numbering scheme, such as ‘v1.0’ or ‘0.1’, etc. Consult GitHub or GitLab.com documentation on how to make a (tagged) release.
4. Come up with a small thumbnail icon for your app. A general guideline is a transparent PNG, size 100x100 pixels.
5. Provide names and email addresses of the person(s) who should have edit privileges (accounts) on the app store.

After providing this information, a skeleton page will be set up on the app store and will be initially invisible to users who visit the front page. Contributors can then log in and work with the app store maintainer to finalize the page, and then make it active (visible) to other users when ready.

5.4. Code review for apps

Even though apps are not added to the ns-3 mainline, it is still possible to request code reviews for them (in order to improve the code). There is a special repository set up for this purpose: ns-3-contrib-reviews. The purpose of this repository is to provide a fork-able repository against which to generate Merge Requests, but no eventual merge ever takes place.

The steps to request a code review are:

1. Fork ns-3-contrib-reviews into your own namespace
2. Clone the fork to your local machine
3. Create a new feature branch on what you just checked out for your new code
4. cd to ‘contrib’ and clone your extension module there
5. remove the .git directory of that module so that git does not treat it as a submodule; e.g., if your module name is modulename:

$ rm -rf modulename/.git

6. Force an add of the module, overcoming the .gitignore file for contrib modules

$ git add -f modulename

7. Add your files:

$ git commit -m"Add modulename for review" -a

8. Push the feature branch to your remote repository

$ git push -u origin

9. Navigate to your github.com page and generate a Merge Request towards the upstream ns-3-contrib-reviews
10. Announce on ns-developers mailing list that you would like a review.

5.5. Maintaining app store modules

A recent Google Summer of Code project worked on allowing integration of the app store with continuous integration (CI) testing. This integration is ongoing, but the eventual goal is that regressions that are caused by upstream changes to ns-3 will be quickly caught, and the app owner will be asked to fix the build of their app, possibly by issuing another module release as well.

5.6. Links to related projects

Some projects choose to maintain their own version of ns-3, or maintain models outside of the main tree of the code. In this case, the way to find out about these is to look at the Related Projects page on the ns-3 wiki.

If you know of externally maintained code that the project does not know about, please email webmaster@nsnam.org to request that it be added to the list of external projects.

Going forward, we will tend to prefer to list related projects on the app store so that there is a single place to discover them.

5.7. Unmaintained, contributed code

Anyone who wants to provide access to code that has been developed to extend ns-3 but that will not be further maintained may list its availability on our website. Furthermore, we can provide, in some circumstances, storage of a compressed archive on a web server if needed. This type of code contribution will not be listed in the app store, although popular extensions might be adopted by a future contributor.

We ask anyone who wishes to do this to provide at least this information on our wiki:

• Authors,
• Name and description of the extension,
• How it is distributed (as a patch or full tarball),
• Location,
• Status (how it is maintained)

Please also make clear in your code the applicable software license. The contribution will be stored on our wiki. If you need web server space for your archive, please contact webmaster@nsnam.org.