Confusions in Contributing Our New Model to mainline ns-3. 

For a very long time, I wish to contribute my own little things to ns-3. But whenever I read the guide on contributing to ns-3, I could not able to understand that procedure at some point, and it discouraged me to proceed. So there should be some “idot’s guide on contributing to ns-3” – so that, it will be easy for people like me to contribute something to ns-3.

The reason for posting this article here is to get feedback from developers and experts so that one can easily contribute his/her code/model to ns-3 and make it available for all along with the official ns-3 distribution.

To make one to understand the problems that I faced while trying to learn the standards in contributing a new module or patch to ns-3, I hereby explain it with my examples scenario.

I  want to contribute two new mobility models for ns-3 namely, 

• CircleMobilityModel and
• SpringMobilityModel

In  fact, I already explained the way in which I developed them in the following two posts :

• Implementation of Circle Mobility Model for ns-3 and Visualizing it in 3D
• Implementation of Spring Mobility Model for ns-3 and Visualizing it in 3D along with Circle Mobility

So that, anyone can learn the way of implementing a simple mobility model by following the above procedure.

In fact, I developed these two mobility models with little effort. But making a submission to incorporate it with mainline ns-3 seems to be a nightmare to me.

But I want my Mobility Models to be merged with the mainstream ns-3 code so that anyone can use it with the default installation of ns-3.

The General section of the official ns-3 contribution guide explains the following

• Licensing our code
• Editing Copyright Section of the code
• Giving Attribution to Others
• Coding style
• Creating a patch
• Becoming a Maintainers

First Doubt

Let me start with my first doubt –  Naming my New Mobility models:

I am having a ‘silly wish’ to name the mobility models with my name like :

“CharlesCircleMobilityModel”

“CharlesSpringMobilityModel”

Will this kind of naming discourage the developers to allow this model during the review?

Another concern regarding naming is:

ndnSIM already has a mobility model called “SpringMobilityModel” for ns-3

Someone also already implemented “CircelMobilityModel” for ns-3 (sorry I could not find the link now)

So, in addition to making me happy, this way of naming will avoid confusion with some other similar implementations with the same name.

Second Doubt

I started to develop these two new mobility models by cloning the skeleton structure of “ConstantPositionMobilityModel” by Mathieu Lacage.

Only a few standard declaration lines are directly handled from ConstantPositionMobilityModel code, and mostly, 90% of lines on my new models were only rewritten by me. But, I wish to give credit to Mathieu Lacage for making me understand the simplicity of a mobility model with his code.

Will the following lines in the header section of my new model code satisfy the (1)Licensing, (2)Copyright and the (3) Attribution standards?

Third Doubt

1. 1. Of course, I can give some documentation under “doc” folder by editing the provided file (or will it autogenerate documentation by running Doxygen on my model code?)
   2. Even I will provide some examples under the “examples” folder.
   3. My simple mobility models do not need any helper functions. (should I delete this?is it allowed to submit a model without ‘helper’ code?)
   4. Even I can keep my model code under the “model” folder.
   5. Frankly saying, I am not having any idea for doing anything under ‘test’ folder. (may I delete this? is it allowed to submit a simple model without ‘test’ code?)

Mode  of Submissions

The guide on contributing to ns-3 tries to explain the following way of submitting a new model/patch to ns-3.

• Submitting as a patch
• Submitting as enhancement
• Submitting as externally maintained code
• Submitting as a new model

   

Even though I can not fully understand the exact procedures of the above four methods, I can understand that all the above methods will lead to incorporating our new ns-3 model in a future version of ns-3 after some review and a lot of time.

But the last submission method is like Directly Uploading files at GitLab, and it will get merged with the official release after some  review (and of course, only if it will satisfy  all the standards outlined in the  contribution  guide)

Fourth  Doubt

Submitting as a Merge Request or Upstreaming to ns-3-dev by Directly Uploading files at GitLab will be a suitable way to submit a simple model like the mobility models that I mentioned here?

I mean, is it allowed to directly upload my

            mobility model files (.cc and .h) under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/model and

            the corresponding examples under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/examples ?

Will it get reviewed and accepted to mainline ns-3 if it satisfies the conditions? (I mean without “test” and a separate “doc”)

I mean, what are the basic things that a model code should fulfil – so that it will be accepted?

The Last(?) Doubt

While trying to learn the way of contributing to ns-3, here and there, I saw some python based scripts and python ways of doing things. Since as per the recent announcement, the python bindings will be removed from future versions of ns-3 and there will be a ‘make’ way of compiling things.

Will these new changes affect the ways of making/submitting the contribution? the official contribution guide is not discussing future issues related to this python and ‘make’ changes and how they will affect the submission method.

Note: 

Of course, the official documents provide LOT of information regarding the submission. But its hugeness itself makes it impossible for us to contribute a ‘simple’ thing to the official version of ns-3.

I hope that the developers and experts can understand my concerns and will provide some insights in this regard.  Your simple replies not only help me to make my first contribution to ns-3.  It will help a student/scholar to really contribute something to ns-3.

The Opinions and Comments of ns3-users and Developers on this Post

Follow the Opinions and Comments of ns3-users and Developers in green text below

Mr. Tom Henderson Generously Responded with the Following Answers and Comments 

For a very long time, I wish to contribute my own little things to ns-3. But whenever I read the guide on contributing to ns-3, I could not able to understand that procedure at some point, and it discouraged me to proceed. So there should be some “idot’s guide on contributing to ns-3” – so that, it will be easy for people like me to contribute something to ns-3.

The reason for posting this here is to get feedback from developers and experts so that one can understand the ways of the submission process and can easily contribute his/her code/model to ns-3 and make it available for all along with the official ns-3 distribution. I am writing an article on “Confusions in Contributing Our New Model to mainline ns-3.” to share my experience of “trying to contribute to ns-3”.

To make one to understand the problems that I faced while trying to learn the standards in contributing a new module or patch to ns-3, I hereby explain it with my examples scenario.

I  want to contribute two new mobility models for ns-3 namely, 

• CircleMobilityModel and
• SpringMobilityModel

In  fact, I already explained the way in which I developed them in the following two posts :

• Implementation of Circle Mobility Model for ns-3 and Visualizing it in 3D
• Implementation of Spring Mobility Model for ns-3 and Visualizing it in 3D along with Circle Mobility

So that, anyone can learn the way of implementing a simple mobility model by following the above procedure.In fact, I developed these two mobility models with little effort. But making a submission to incorporate it with mainline ns-3 seems to be a nightmare to me.

But I want my Mobility Models to be merged with the mainstream ns-3 code so that anyone can use it with the default installation of ns-3.

The General section of the official ns-3 contribution guide explains the following

• Licensing our code
• Editing Copyright Section of the code
• Giving Attribution to Others
• Coding style
• Creating a patch
• Becoming a Maintainers

First Doubt

Let me start with my first doubt –  Naming my New Mobility models:

I am having a ‘silly wish’ to name the mobility models with my name like :

“CharlesCircleMobilityModel”

“CharlesSpringMobilityModel”

Will this kind of naming discourage the developers to allow this model during the review?

I would suggest that you use an ‘Author: ‘ statement just below the GPLv2 in your file rather than including your name in the class.

Another concern regarding naming is:

ndnSIM already has a mobility model called “SpringMobilityModel” for ns-3

Someone also already implemented “CircelMobilityModel” for ns-3 (sorry I could not find the link now)

Those are issues for downstream projects or users to adapt to if the ns-3 mainline makes changes– it should not affect our naming decisions.

So, in addition, to making me happy 🙂 , this way of naming will avoid confusion with some other similar implementations with the same name.

Second Doubt

I started to develop these two new mobility models by cloning the skeleton structure of “ConstantPositionMobilityModel” by Mathieu Lacage.

Only a few standard declaration lines are directly handled from ConstantPositionMobilityModel code, and most 90% of lines on my new models were only rewritten by me. But, I wish to give credit to Mathieu Lacage for making me understand the simplicity of a mobility model with his code.

Will the following lines in the header section of my new model code satisfy the (1)Licensing, (2)Copyright and the (3) Attribution standards?

/* -*- Mode:C++; c-file-style:”gnu”; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2021 Charles Pandian, ProjectGuideline.com
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation;
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* Author: Charles Pandian<[email protected]>
* Insprired from: ConstantPositionMobilityModel by Mathieu Lacage <[email protected].fr>
*/

Most likely that type of credit would be appropriate.

Third Doubt

This is the main doubt that is discouraging me to contribute something to ns-3.

 

In fact, I could not understand what a new model to satisfy the need of the automated testing described in the section “How to write tests“.

Frankly saying I can not understand what they are taking in this section (simply it is in alien language)

Is there any simple document that will explain about this testing?
Or is there any simple example of ‘testing’ that is needed for a simple ‘hello’ ns-3 model?

I can’t really respond to the criticism that it appears to be alien to you.  However, there are many tests scattered through ns-3, and I would suggest to read and understand how a few of them work, and then clone the approach (start from an existing mobility test that you can adapt) and make your modifications as needed.

I followed the procedure and run the script create-module.py for creating the directory structure for my new model “CharlesCircleMobilityModel”.  It is creating folders with some example/dummy(?) files under the contrib folder.

Here there is a small disconnect.  Above, you said that you would like to add your model to the mainline of ns-3 (i.e., into src/mobility directory).  But here, you are creating an externally-hosted module.  You will need to decide or seek feedback on which path to choose.

Of course, I can give some documentation under “doc” folder by editing the provided file (or will it autogenerate documentation by running Doxygen on my model code?)

Doxygen works on the annotations that are in every .h file.  The doc folder is instead for Sphinx-based documentation.

Even I will provide some examples under the “examples” folder.

My simple mobility models do not need any helper functions. (should I delete this?is it allowed to submit a model without ‘helper’ code?)

It is allowed to not have a helper directory.

Even I can keep my model code under the “model” folder.

Frankly saying, I am not having any idea for doing anything under ‘test’ folder. (may I delete this? is it allowed to submit a model without ‘test’ code?)

It is not allowed for the mainline.  It is also not advised for contrib modules– how will users know whether the model has been tested or continues to work as the ns-3 mainline evolves?

But, I simply want my new mobility models to live under the folder “ns-allinone-3.35/ns-3.35/src/mobility/model” of the ns-3 distribution.

But the documentation is advising me to do it using ‘create-module.py’ with several folders.

Again, if you want your model to live in src/mobility, do not use ‘create-module.py’.

If I submit the code with the above structure, will the developers of ns-3 merge it under “ns-allinone-3.35/ns-3.35/src/mobility/model” ? (and examples under “ns-allinone-3.35/ns-3.35/src/mobility/examples”, …. )

 

Kindly someone explain what I need to do for making my model live at “ns-allinone-3.35/ns-3.35/src/mobility/model” in future versions of ns-3 distributions.
Of course, it will not make much confusion if I develop a ‘big routing algorithm like’ model that will  live under ns-allinone-3.35/ns-3.35/src/

For submitting a simple add-on module like a mobility model, what are the conventions one should fulfil before submitting it for review?

Somebody, please Explain.

This section applies:  https://www.nsnam.org/docs/contributing/html/models.html#upstreaming-new-models

Mode  of Submissions

The guide on contributing to ns-3 tries to explain the following way of submitting a new model/patch to ns-3.

• Submitting as a patch
• Submitting as enhancement
• Submitting as externally maintained code
• Submitting as a new model

   

Even though I can not fully understand the exact procedures of the above four methods, I can understand that all the above methods will lead to incorporating our new ns-3 model in a future version of ns-3 after some review and a lot of time.

But the last submission method is like Directly Uploading files at GitLab, and it will get merged with the official release after some  review (and of course it will satisfy  all the standards outlined in the  contribution  guide)

Fourth  Doubt

Submitting as a Merge Request or Upstreaming to ns-3-dev by Directly Uploading files at GitLab will be a suitable way to submit a simple model like the mobility models that I mentioned here?

I mean, is it allowed to directly upload my

            mobility model files (.cc and .h) under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/model and

            the corresponding examples under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/examples ?

Will it get reviewed and accepted to mainline ns-3 if it satisfies the conditions? (I mean without “test” and a separate “doc”)

I mean, what are the basic things that a model code should fulfil – so that it will be accepted?

1) it provides somewhat broad utility to future users of ns-3 (i.e., it is not too specialized or niche).  This is a judgment call by the maintainers. 

2) it conforms to the engineering and documentation standards of ns-3

The Last(?) Doubt

While trying to learn the way of contributing to ns-3, here and there, I saw some python based scripts and ways of doing things. Since as per the recent announcement, the python bindings will be removed from ns-3 and there will be a ‘make’ way of compiling things.

We are moving away from Waf and to CMake, which is not quite ‘make’ (although it can use make as a build tool).

Will these new changes affect the ways of making/submitting the contribution? the official contribution guide is not discussing future issues related to this python and ‘make’ changes.

There really shouldn’t be much of an impact on code contribution.  The build scripts will change a bit (moving from ‘wscript’ to CMakeLists.txt).    The maintainers can help with this if needed.

Note: 

Of course, the official documents provide LOT of information regarding the submission. But its hugeness itself makes it impossible for us to contribute a ‘simple’ thing to the official version of ns-3.

I hope that the developers and experts can understand my concerns and will provide some insights in this regard.  Your simple replies not only help me to make my first contribution to ns-3.  It will help a student/scholar to really contribute something to ns-3.

Thank you for the feedback.  In general, I would suggest that you do not have to choose inaction or paralysis if you have doubts, but simply email one of the maintainers a link to your code and ask if the feature might be of possible interest and ask for some help with it.

I wrote the contribution guide and it is lengthy because there simply are a lot of issues and cases to consider; I tried to make it as clear and succinct as possible but of course would accept suggested revisions.

– Tom

My Reply to  Mr. Tom for his Answers and Comments

Mr. Tom,

Thanks for your comment and advice.
I hope that I will learn to do things according to standards while trying to submit them and while interacting with reviewers.
Your reply will be helpful for beginners like me who wish to contribute something to ns-3.

One more specific question:
I saw an interesting mobility model which is waiting for review/merging.
https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/631
That new mobility model called SRCM seems to be good and sophisticated than my simple 3D mobility models.

What may be the reason still it is not getting merged with the mainline ns-3?

Your comments on this may help me to correct my model and mistakes even before submission.

Charles Pandian,

Dec 17, 2021, 11:07 PM

Only a few maintainers are handling reviews; we get few reviews from the community.  If someone else (such as you, or other researchers) were to review this code and state that ‘this mobility model is useful and well done and should be merged’ then it may influence decisions on it.

Also, the author told us that he or she is updating the model for 3D so I suppose we are waiting for revisions also.

– Tom