.. include:: replace.txt
.. heading hierarchy:
   ------------- Chapter
   ************* Section (#.#)
   ============= Subsection (#.#.#)
   ############# Paragraph (no number)

.. _External:

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 |ns3| 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 |ns3|
`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 :ref:`sec-unmaintained-contributed` below.

However, much of the emphasis of this chapter is on hosting |ns3| extensions
in the |ns3| `App Store <https://apps.nsnam.org>`_.

Rationale for the app store
***************************

Historically, |ns3| 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 |ns3| includes more lines of code, it takes longer to compile, while
   users typically only need a subset of the available |ns3| 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 |ns3| 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 |ns3| extensions
and add them to their |ns3| 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 |ns3| 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 |ns3|.

In brief, what it means for |ns3| users is the following.  There is an
empty directory in the |ns3| 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 |ns3|.

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.

Example app
===========

For example, consider a user who wants to use a model of the LoRaWAN
sensor networking protocol in |ns3|.  This model is not available in
the mainline |ns3| releases, but the user checks in the
`App Store <https://apps.nsnam.org>`_.  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 |ns3| 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 |ns3| `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:

.. code-block:: text

  $ ./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 |ns3|.  The *Release History* tab describes the releases and
the minimum (and, optionally, the maximum) |ns3| 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.

App types
*********

Two types of "apps" are hosted on the app store:  1) contributed modules,
and 2) forks of |ns3|.  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 |ns3| mainline
and to combine multiple such modules.  However, some authors have chosen
to create a full fork of |ns3|, and to publish full |ns3| source trees.
One reason for such forks is if the fork requires intrusive changes to
the |ns3| 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 <https://apps.nsnam.org/app/publicsafetylte/>`_ 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.

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

Code review for apps
********************

Even though apps are not added to the |ns3| 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 <https://gitlab.com/nsnam/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`:

.. code-block:: text

  $ rm -rf modulename/.git

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

.. code-block:: text

  $ git add -f modulename

7. Add your files:

.. code-block:: text

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

8.  Push the feature branch to your remote repository

.. code-block:: text

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

Maintaining app store modules
*****************************

A recent `Google Summer of Code project <https://mishal.dev/gsoc19-report>`_
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 |ns3| 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.

Links to related projects
*************************
Some projects choose to maintain their own version of |ns3|, 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 |ns3|
`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.

.. _sec-unmaintained-contributed:

Unmaintained, contributed code
******************************

Anyone who wants to provide access to code that has been developed to
extend |ns3| 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``.

.. _wiki: https://www.nsnam.org/wiki/Contributed_Code