F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

documentation: Add contributing guide

Browse Source
This commit is contained in:
Tom Henderson
2019-05-14 09:28:45 -07:00
parent 70adab8d72
commit e3590d611a
18 changed files with 2111 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/codingstd.txt
View File

@@ -1,2 +1,4 @@
The project coding style document is maintained at:
http://www.nsnam.org/developers/contributing-code/coding-style/
The project coding style document is maintained as part of the contribution
guide (https://www.nsnam.org/docs/contributing/html/index.html). The raw
source file for the coding style chapter is in a subdirectory:
contributing/source/coding-style.rst

165
doc/contributing/Makefile Normal file
View File

@@ -0,0 +1,165 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# Additional variables for figures, not sphinx default:
DIA = dia
EPSTOPDF = epstopdf
FIGURES = source/figures
IMAGES_EPS = \
IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
IMAGES = $(IMAGES_EPS) $(IMAGES_PNG) $(IMAGES_PDF)
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
.NOTPARALLEL:
%.eps : %.dia
@echo dia $(notdir $<)
@$(DIA) -t eps $< -e $@ >/dev/null
%.png : %.dia
@echo dia $(notdir $<)
@$(DIA) -t png $< -e $@ >/dev/null
%.png : %.eps
@echo convert $(notdir $<)
@$(CONVERT) $< $@ >/dev/null
%.pdf : %.eps
@echo epstopdf $(notdir $<)
@$(EPSTOPDF) $< -o=$@ >/dev/null
@if test x$($@_width) != x; then $(RESCALE) $($@_width) $@ ; fi
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)
frag: pickle
@if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle > navigation.xml && popd
cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
html: $(IMAGES)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml: $(IMAGES)
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml: $(IMAGES)
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle: $(IMAGES)
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json: $(IMAGES)
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp: $(IMAGES)
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp: $(IMAGES)
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
devhelp: $(IMAGES)
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
@echo "# devhelp"
epub: $(IMAGES)
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex: $(IMAGES)
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf: $(IMAGES)
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text: $(IMAGES)
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man: $(IMAGES)
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes: $(IMAGES)
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck: $(IMAGEs)
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest: $(IMAGES)
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

18
doc/contributing/figures/README Normal file
View File

@@ -0,0 +1,18 @@
Please write image files in a vector graphics format, when possible, and
generate the .png and .pdf versions on the fly (see ../Makefile).
The currently supported tool is dia. xfig could be added similarly
if someone wants to add it. The main requirement for adding another format
is that the tool to edit it is freely available and that a cron script can
autogenerate the pdf and png from the figure source. Tgif (.obj) files
were once used but the file conversions require a valid X display to
be running, and are therefore to be avoided since our code server
does not run such a server. Tgif pdf conversions were also cumbersome.
Store the .dia versions in git, but not the .png or .pdfs.
If the figure is not available in a vector graphics format, store both
a .png and a .pdf version in this directory.
If you add a source (.dia) file here, remember to add it to
the list of figure sources in the Makefile in the directory above

42
doc/contributing/pickle-to-xml.py Executable file
View File

@@ -0,0 +1,42 @@
#!/usr/bin/python
# output xml format:
# <pages>
# <page url="xx"><prev url="yyy">zzz</prev><next url="hhh">lll</next><fragment>file.frag</fragment></page>
# ...
# </pages>
import pickle
import os
import codecs
def dump_pickles(out, dirname, filename, path):
f = open(os.path.join(dirname, filename), 'r')
data = pickle.load(f)
fragment_file = codecs.open(data['current_page_name'] + '.frag', mode='w', encoding='utf-8')
fragment_file.write(data['body'])
fragment_file.close()
out.write(' <page url="%s">\n' % path)
out.write(' <fragment>%s.frag</fragment>\n' % data['current_page_name'])
if data['prev'] is not None:
out.write(' <prev url="%s">%s</prev>\n' %
(os.path.normpath(os.path.join(path, data['prev']['link'])),
data['prev']['title']))
if data['next'] is not None:
out.write(' <next url="%s">%s</next>\n' %
(os.path.normpath(os.path.join(path, data['next']['link'])),
data['next']['title']))
out.write(' </page>\n')
f.close()
if data['next'] is not None:
next_path = os.path.normpath(os.path.join(path, data['next']['link']))
next_filename = os.path.basename(next_path) + '.fpickle'
dump_pickles(out, dirname, next_filename, next_path)
return
import sys
sys.stdout.write('<pages>\n')
dump_pickles(sys.stdout, os.path.dirname(sys.argv[1]), os.path.basename(sys.argv[1]), '/')
sys.stdout.write('</pages>')

0
doc/contributing/source/_static/.hidden Normal file
View File

423
doc/contributing/source/coding-style.rst Normal file
View File

@@ -0,0 +1,423 @@
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _Coding style:
Coding style
------------
When writing code to be contributed to the |ns3| open source project, we
ask that you follow the coding standards, guidelines, and recommendations
found below.
A lot of the syntactical rules described can be easily enforced with the
help of the ``utils/check-style.py`` script which relies on a working version
of `uncrustify <http://uncrustify.sourceforge.net/>`_ so, do not hesitate
to run this script over your code prior to submission.
Code layout
***********
The code layout follows the
`GNU coding standard <https://www.gnu.org/prep/standards/>`_ layout for C and
extends it to C++. Do not use tabs for indentation. Indentation spacing is
2 spaces (the default emacs C++ mode) as outlined below:
::
Foo (void)
{
if (test)
{
// do stuff here
}
else
{
// do other stuff here
}
for (int i = 0; i < 100; i++)
{
// do loop
}
while (test)
{
// do while
}
do
{
// do stuff
} while ();
}
Each statement should be put on a separate line to increase readability, and
multi-statement blocks following conditional or looping statements are always
delimited by braces (single-statement blocks may be placed on the same line
of an ``if ()`` statement). Each variable declaration is on a separate line.
Variables should be declared at the point in the code where they are needed,
and should be assigned an initial value at the time of declaration. Except
when used in a switch statement, the open and close braces ``{`` and ``}``
are always on a separate line. Do not use the C++ ``goto`` statement.
The layout of variables declared in a class may either be aligned with
the variable names or unaligned, as long as the file is internally consistent
and no tab characters are included. Examples:
::
int varOne;
double varTwo; // OK (unaligned)
int varOne;
double varTwo; // also OK (aligned)
Naming
******
Name encoding
=============
Function, method, and type names should follow the
`CamelCase <https://en.wikipedia.org/wiki/CamelCase>`_ convention: words are
joined without spaces and are capitalized. For example, "my computer" is
transformed into ``MyComputer``. Do not use all capital letters such as
``MAC`` or ``PHY``, but choose instead ``Mac`` or ``Phy``. Do not use all
capital letters, even for acronyms such as ``EDCA``; use ``Edca`` instead.
This applies also to two-letter acronyms, such as ``IP`` (which becomes
``Ip``). The goal of the CamelCase convention is to ensure that the words
which make up a name can be separated by the eye: the initial Caps
fills that role. Use PascalCasing (CamelCase with first letter capitalized)
for function, property, event, and class names.
Variable names should follow a slight variation on the base CamelCase
convention: camelBack. For example, the variable ``user name`` would be named
``userName``. This variation on the basic naming pattern is used to allow a
reader to distinguish a variable name from its type. For example,
``UserName userName`` would be used to declare a variable named
``userName`` of type ``UserName``.
Global variables should be prefixed with a ``g_`` and member variables
(including static member variables) should be prefixed with a ``m_``. The goal
of that prefix is to give a reader a sense of where a variable of a given
name is declared to allow the reader to locate the variable declaration and
infer the variable type from that declaration. Defined types will start
with an upper case letter, consist of upper and lower case letters, and may
optionally end with a ``_t``. Defined constants (such as static const class
members, or enum constants) will be all uppercase letters or numeric digits,
with an underscore character separating words. Otherwise, the underscore
character should not be used in a variable name. For example, you could
declare in your class header ``my-class.h``:
::
typedef int NewTypeOfInt_t;
const uint8_t PORT_NUMBER = 17;
class MyClass
{
void MyMethod (int aVar);
int m_aVar;
static int m_anotherVar;
};
and implement in your class file ``my-class.cc``:
::
int MyClass::m_anotherVar = 10;
static int g_aStaticVar = 100;
int g_aGlobalVar = 1000;
void
MyClass::MyMethod (int aVar)
{
m_aVar = aVar;
}
As an exception to the above, the members of structures do not need to be
prefixed with an ``m_``.
Finally, do not use
`Hungarian notation <https://en.wikipedia.org/wiki/Hungarian_notation>`_, and
do not prefix enums, classes, or delegates with any letter.
Choosing names
==============
Variable, function, method, and type names should be based on the English
language, American spelling. Furthermore, always try to choose descriptive
names for them. Types are often english names such as: Packet, Buffer, Mac,
or Phy. Functions and methods are often named based on verbs and adjectives:
GetX, DoDispose, ClearArray, etc.
A long descriptive name which requires a lot of typing is always better than
a short name which is hard to decipher. Do not use abbreviations in names
unless the abbreviation is really unambiguous and obvious to everyone (e.g.,
use "size" over "sz"). Do not use short inappropriate names such as foo,
bar, or baz. The name of an item should always match its purpose. As such,
names such as "tmp" to identify a temporary variable, or such as "i" to
identify a loop index are ok.
If you use predicates (that is, functions, variables or methods which return
a single boolean value), prefix the name with "is" or "has".
File layout and code organization
*********************************
A class named ``MyClass`` should be declared in a header named ``my-class.h``
and implemented in a source file named ``my-class.cc``. The goal of this
naming pattern is to allow a reader to quickly navigate through the |ns3|
codebase to locate the source file relevant to a specific type.
Each ``my-class.h`` header should start with the following comments: the
first line ensures that developers who use the emacs editor will be able to
indent your code correctly. The following lines ensure that your code
is licensed under the GPL, that the copyright holders are properly
identified (typically, you or your employer), and that the actual author
of the code is identified. The latter is purely informational and we use it
to try to track the most appropriate person to review a patch or fix a bug.
Please do not add the "All Rights Reserved" phrase after the copyright
statement.
::
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) YEAR COPYRIGHTHOLDER
*
* 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: MyName <myemail@example.com>
*/
Below these C-style comments, always include the following which defines a
set of header guards (``MY_CLASS_H``) used to avoid multiple header includes,
which ensures that your code is included in the |ns3| namespace and which
provides a set of Doxygen comments for the public part of your class API.
Detailed information on the set of tags available for doxygen documentation
is described in the `Doxygen website <https://www.doxygen.nl/index.html>`_.
::
#ifndef MY_CLASS_H
#define MY_CLASS_H
namespace n3 {
/**
* \brief short one-line description of the purpose of your class
*
* A longer description of the purpose of your class after a blank
* empty line.
*/
class MyClass
{
public:
MyClass ();
/**
* \param firstParam a short description of the purpose of this parameter
* \returns a short description of what is returned from this function.
*
* A detailed description of the purpose of the method.
*/
int DoSomething (int firstParam);
private:
void MyPrivateMethod (void);
int m_myPrivateMemberVariable;
};
} // namespace ns3
#endif /* MY_CLASS_H */
The ``my-class.cc`` file is structured similarly:
::
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) YEAR COPYRIGHTHOLDER
*
* 3-paragraph GPL blurb
*
* Author: MyName <myemail@foo.com>
*/
#include "my-class.h"
namespace ns3 {
MyClass::MyClass ()
{}
...
} // namespace ns3
Language features
*****************
As of ns-3.25, ns-3 had avoided C++-11 (and C++-14) features until compiler
support was mature. Starting with ns-3.26, we will permit the use of
`C++-11 features <https://gcc.gnu.org/gcc-4.8/cxx0x_status.html>`_ supported
by our minimum compiler supported (gcc-4.8, clang-3.3). Starting with ns-3.27,
we require at least gcc-4.9 instead of gcc-4.8.
If a developer would like to propose to raise this bar to include more
features than this, please email the developers list. We will move this
language support forward as our minimally supported compiler moves forward.
Comments
********
The project uses `Doxygen <https://www.doxygen.nl/index.html>`_ to document
the interfaces, and uses comments for improving the clarity of the code
internally. All public methods should have Doxygen comments. Doxygen comments
should use the C comment style. For non-public methods, the ``@internal`` tag
should be used. Please use the ``@see`` tag for cross-referencing. All
parameters and return values should be documented.
As for comments within the code, comments should be used to describe intention
or algorithmic overview where is it not immediately obvious from reading the
code alone. There are no minimum comment requirements and small routines
probably need no commenting at all, but it is hoped that many larger
routines will have commenting to aid future maintainers. Please write
complete English sentences and capitalize the first word unless a lower-case
identifier begins the sentence. Two spaces after each sentence helps to make
emacs sentence commands work.
Short one-line comments and long comments can use the C++ comment style;
that is, ``//``, but longer comments may use C-style comments:
::
/*
* A longer comment,
* with multiple lines.
*/
Variable declaration should have a short, one or two line comment describing
the purpose of the variable, unless it is a local variable whose use is
obvious from the context. The short comment should be on the same line as the
variable declaration, unless it is too long, in which case it should be on
the preceding lines.
Every function should be preceded by a detailed (Doxygen) comment block
describing what the function does, what the formal parameters are, and what
the return value is (if any). Either Doxygen style ``\`` or ``@``
is permitted. Every class declaration should be preceded by a (Doxygen) comment block describing what the class is to be used for.
Casts
*****
Where casts are necessary, use the Google C++ guidance: "Use C++-style casts
like ``static_cast<float>(double_value)``, or brace initialization for
conversion of arithmetic types like ``int64 y = int64{1} << 42``."
Try to avoid (and remove current instances of) casting of ``uint8_t``
type to larger integers in our logging output by overriding these types
within the logging system itself. Also, the unary ``+`` operator can be used
to print the numeric value of any variable, such as:
::
uint8_t flags = 5;
std::cout << "Flags numeric value: " << +flags << std::endl;
Avoid unnecessary casts if minor changes to variable declarations can solve
the issue.
Miscellaneous items
*******************
- The following emacs mode line should be the first line in a file:
::
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
- ``NS_LOG_COMPONENT_DEFINE("log-component-name");`` statements should be
placed within namespace ns3 (for module code) and after the
``using namespace ns3;``. In examples.
``NS_OBJECT_ENSURE_REGISTERED()`` should also be placed within namespace ns3.
- Const reference syntax:
::
void MySub (const T&); // Method 1 (prefer this syntax)
void MySub (T const&); // Method 2 (avoid this syntax)
- Use a space between the function name and the parentheses, e.g.:
::
void MySub(const T&); // avoid this
void MySub (const T&); // use this instead
This spacing rule applies both to function declarations and invocations.
- Do not include inline implementations in header files; put all
implementation in a .cc file (unless implementation in the header file
brings demonstrable and significant performance improvement).
- Do not use ``nil`` or ``NULL`` constants; use ``0`` (improves portability)
- Consider whether you want the default copy constructor and assignment
operator in your class, and if not, make them private such as follows:
::
private:
ClassName (const Classname&);
ClassName& operator= (const ClassName&)
- Avoid returning a reference to an internal or local member of an object:
::
a_type& foo (void); // should be avoided, return a pointer or an object.
const a_type& foo (void); // same as above
This guidance does not apply to the use of references to implement operators.
- Expose class members through access functions, rather than direct access
to a public object. The access functions are typically named Get" and
"Set". For example, a member m_delayTime might have accessor functions
``GetDelayTime ()`` and ``SetDelayTime ()``.
- For standard headers, use the C++ style of inclusion, such as
::
#include <cheader>
instead of
::
#include <header.h>
- Do not bring the C++ standard library namespace into |ns3| source files by
using the "using" directive; i.e. avoid ``using namespace std;``.
- When including |ns3| headers in other |ns3| files, use `<>` when you expect
the header to be found in build/ (or to be installed) and use `""` when
you know the header is in the same directory as the implementation.
- inside .h files, always use
::
#include <ns3/header.h>
- inside .cc files, use
::
#include "header.h"
if file is in same directory, otherwise use
::
#include <ns3/header.h>
- When writing library code, try to avoid the use of unused function
parameters; use the ``NS_UNUSED ()`` macro to explicitly note that a
parameter is intentionally ignored. However, when writing client code
(tests and examples), ``NS_UNUSED()`` is not required and may be avoided
especially if the author feels that it clutters the code (example: hooking
a trace source to gather program output, but not using all of the parameters
that the trace source provides).

216
doc/contributing/source/conf.py Normal file
View File

@@ -0,0 +1,216 @@
# -*- coding: utf-8 -*-
#
# ns-3 documentation build configuration file, created by
# sphinx-quickstart on Tue Dec 14 09:00:39 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.imgmath']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'ns-3'
copyright = u'2015, ns-3 project'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'ns-3-dev'
# The full version, including alpha/beta/rc tags.
release = 'ns-3-dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'ns3_html_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ['../..']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = 'Contributing'
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%b %d, %Y %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'ns-3doc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'ns-3-contributing.tex', u'Contributing to ns-3',
u'ns-3 project', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
latex_logo = '../../ns3_html_theme/static/ns-3.png'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Additional stuff for the LaTeX preamble.
latex_preamble = '\usepackage{amssymb}'
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'ns-3-contributing', u'Contributing to ns-3',
[u'ns-3 project'], 1)
]

302
doc/contributing/source/enhancements.rst Normal file
View File

@@ -0,0 +1,302 @@
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _Enhancements:
Submitting enhancements
-----------------------
This chapter covers how to submit fixes and small patches for the existing
mainline code and its documentation.
Enhancements (new models) can be proposed for the mainline, and
maintainers will make a decision on whether to include it as mainline
or recommend that it be supported in the ns-3 App Store. Documentation
on hosting code in the ns-3 App Store is provided in the next
chapter (:ref:`External`). This chapter provides guidance on submitting
code for inclusion in the mainline (and much of it applies also as
best practice for app store code).
GitLab.com trackers
*******************
|ns3| uses two trackers to keep track of known issues or submitted code.
Maintainers prefer to list everything on the tracker so that issues do not
slip through the cracks. Users are encouraged to use these to report
or comment on issues or merge requests; this requires users to obtain
a GitLab.com account.
If a user wants to report an issue with |ns3|, please first search
the `issue tracker <https://gitlab.com/nsnam/ns-3-dev/-/issues>`_ for
something that may be similar, and if nothing is found, please report
the new issue.
If a user wants to submit proposed new code for |ns3|, please
submit on the `merge request tracker <https://gitlab.com/nsnam/ns-3-dev/-/merge_requests>`_.
More details for each are provided below. Similarly, users who want to
report issues on other related repositories under the `nsnam` project
(such as the `Bake build system <https://gitlab.com/nsnam/bake>`_)
should follow similar steps there.
Reporting issues
****************
Issues can be reported against the code or the documentation, if you believe
that something is incorrect or could be improved. The key to reporting
an issue with the code is to try to provide as much information as possible
to allow a maintainer to quickly reproduce the problem. After you've
determined which module your bug is related to, if it is inside the
official distribution (mainline), then create an issue, label it with the
name of the module, and provide as much information as possible.
First, perform a cursory search on the
`open issue list <https://gitlab.com/nsnam/ns-3-dev/-/issues>`_ to see if
the problem has already been reported. If it has and the issue is still
open, add a comment to the existing issue instead of opening a new one.
If you are reporting an issue against an older version of |ns3|, please
scan the most recent
`Release Notes <https://gitlab.com/nsnam/ns-3-dev/-/blob/master/RELEASE_NOTES>`_ to see if it has been fixed since that release.
If you then decide to list an issue, include details of your environment:
1. Which version of ns-3 are you using?
2. What's the name and version of the OS you're using?
3. Which modules do you have installed?
4. Have you modified ns-3-dev in any way?
Here are some additional guidelines:
1. Use a clear and descriptive title for the issue to identify the problem.
2. Describe the exact steps which reproduce the problem in as many details
as possible. For example, start by explaining how you coded your script;
e.g. which functions were called in what order, or else provide an example
program. If your program includes modifications to the ns-3 core or a
module, please list them (or even better, provide the diffs).
3. Provide specific examples to demonstrate the steps. Include links to
files or projects, or copy/pasteable snippets, which you use in those
examples. If you're providing snippets in the issue, use Markdown code
block formatting.
4. Describe the behavior you observed after following the steps and point out
what exactly is the problem with that behavior. Explain which behavior you
expected to see instead and why.
5. If you're reporting that ns-3 crashed, include a crash report with a
stack trace from the operating system. On macOS, the crash report will
be available in Console.app under
`"Diagnostic and usage information" > "User diagnostic reports"`. Include
the crash report in the issue in a code block, or a file attachment.
6. If the problem is related to performance or memory, include a CPU
profile capture with your report.
Some issues have suggested resolutions that are trivial and do not
require submitting a merge request. For more complicated resolutions,
if you have a patch to propose, either attach it to the issue, or submit a
merge request (described next).
Submitting merge requests
*************************
To submit code proposed for |ns3| as one or more commits, use a merge
request. The following steps are recommended to smooth the process.
If you are new to public Git repositories, you may want to read
`this overview of merge requests <https://docs.gitlab.com/ee/user/project/merge_requests/getting_started.html>`_. If you are familiar with GitHub
pull requests, the GitLab.com merge requests are very similar.
In brief, you will want to fork ns-3-dev into your own namespace (i.e.,
fork the repository into your personal GitLab.com account, via the user
interface on GitLab.com), clone your fork of ns-3-dev to your local machine,
create a new feature branch that is based on the
current tip of ns-3-dev, push that new feature branch up to your fork,
and then from the GitLab.com user interface, generate a Merge Request back
to the |ns3| mainline. You will want to monitor and respond to any
comments from reviewers, and try to resolve threads.
Remember the documentation
==========================
If you add or change API to the simulator, please include `Doxygen <https://www.doxygen.nl>`_ changes as appropriate. Please scan the module documentation
(written in `Restructured Text <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ in the `docs` directory) to check if an update is needed to align with the patch proposal.
Commit message format
=====================
Commit messages should be written as follows. For examples, please look
at the output of `git log` command.
1. The author string should be formatted such as "John Doe <john.doe@example.com>". It is a good idea to run
`git config <https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration>`_ on your machine, or hand-edit the `.gitconfig` file in your home directory,
to ensure that your name and email are how you want them to be displayed.
.. raw:: latex
\newpage
2. The first line of the commit message should be limited to 72 columns if possible. This is not a hard requirement but a preference. If you prefer to add
more detail, you can add subsequent message lines below the first one, separated by a blank line. Example:
.. code-block:: text
commit e6ca9be6fb5a0592a44967f7885545dce3a6da1a
Author: Rediet <getachew.redieteab@orange.com>
Date: Wed May 19 16:34:01 2021 +0200
lte: Assign default values
Fixes crashing optimized/release builds with 'may be used uninitialized' error
3. The first line of the commit message should include the relevant module name or names, separated by a colon. Example:
.. code-block:: text
commit 15ab50c03132a5f7686045014c6bedf10ac7d421
Author: Stefano Avallone <stavallo@unina.it>
Date: Wed Jan 27 14:58:54 2021 +0100
wifi,wave,mesh: Rescan python bindings
4. If the commit fixes an issue in the issue tracker, list it in parentheses
after the colon (by saying 'fixes #NNN' where NNN is the issue number).
This reference alerts future readers to an issue where
more may be discussed about the commit. Example:
.. code-block:: text
commit 10ef08140ab2a9f2b550f24d1e881e76ea0873ff
Author: Tom Henderson <tomh@tomh.org>
Date: Fri May 21 11:11:33 2021 -0700
network: (fixes #404) Use Queue::Dispose() for SimpleNetDevice::DoDispose()
5. If the commit is from a merge request, that may also be added in a similar
way the same by saying 'merges !NNN'. The exclamation point differentiates
merge requests from issues (which use the number sign '#') on GitLab.com.
Example:
.. code-block:: text
commit d4258b2b32d6254b878eca9200271fa3f4ee7174
Author: Tom Henderson <tomh@tomh.org>
Date: Sat Mar 27 09:56:55 2021 -0700
build: (merges !584) Exit configuration if path whitespace detected
Here is an example making use of both:
.. code-block:: text
commit a97574779b575af70d975f9e2ca899e2405cf497
Author: Federico Guerra <federico@guerra-tlc.com>
Date: Tue Jan 14 21:14:37 2020 +0100
uan: (fixes #129, merges !162) EndTx moved to PhyListener
6. Use the present tense ("Add feature", not "Added feature") and the imperative mood ("Move cursor to ...", not "Moves cursor to...").
No extraneous white space
=========================
Do not make whitespace changes to unrelated parts of the code (unrelated
to your merge request). This can often happen if the `check-style.py`
program is used on existing files. Use the automated style correction
program `check-style.py` only on your *new* source code files.
Squashing your history
======================
In the course of developing and responding to review comments, you may
add more commits, so what started out as a single commit might grow into
several. Please consider to squash any such revisions if they do not
need to be preserved as separate commits in the mainline Git history.
If you squash commits, you must force-push your branch back to your fork.
Do not worry about this; GitLab.com will update the Merge Request
automatically. This `tutorial <https://docs.gitlab.com/ee/topics/git/git_rebase.html>`_ may be helpful to learn about Git rebase, force-push, and merge
conflicts.
Note that GitLab can squash the commits while merging. However, it is often
preferred to keep multiple commit messages, especially when the merge request
contains multiple parts or multiple authors.
It is a good practice to NOT squash commits while the merge request is being
reviewed and updated (this helps the reviewers), and perform a selective
squash before the merge.
Rebasing on ns-3-dev
====================
It is also helpful to maintainers to keep your feature branch up to date
so that the commits are appended to the tip of the mainline code. This
is not strictly required; maintainers may do such a rebase upon merging
your finalized Merge Request. This may help catch possible merge conflicts
before the time to merge arrives.
Note that sometimes it is not possible to rebase a merge request through
GitLab's web interface. Hence, it is a good practice to keep your merge
request in line with the mainline (i.e., rebase it periodically and push
the updated branch).
Resolving discussion threads
============================
Any time someone opens a new comment thread on a Merge Request, a counter
of 'Unresolved threads' is incremented (near the top of the Merge Request).
If you are able to successfully resolve the comment thread (either by
changing your code, or convincing the reviewer that no change is needed),
then please mark the thread as resolved. Maintainers will look at the
count of unresolved threads and make decisions based on this count as to
whether the Merge Request is ready. Maintainers prefer that all threads
are resolved successfully before moving forward with a merge.
Adding a label
==============
You can use labels to indicate whether the Merge Request is a bug, pertains
to a specific module or modules, is documentation related, etc. This is
not required; if you do not add a label, a maintainer probably will.
Other metadata
==============
It is not necessary to set other metadata on the Merge Request such as
milestone, reviewers, etc.
Feature requests
****************
Feature requests are tracked as `GitLab.com issues <https://gitlab.com/nsnam/ns-3-dev/-/issues>`_. If you want to suggest an enhancement, create an issue and provide the following information:
1. Use a clear and descriptive title for the issue to identify the suggestion.
2. Provide a step-by-step description of the suggested enhancement in as many details as possible.
3. Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples.
4. Describe the current behavior and explain which behavior you expected to see instead and why.
5. Explain why this enhancement would be useful to most ns-3 users.
The |ns3| project does not have professional developers available to respond
to feature requests, so your best bet is to try to implement it yourself and
work with maintainers to improve it, but the project does like to hear back
from users about what would be a useful improvement, and you may find
like-minded collaborators in the community willing to work on it with you.
Use the `enhancement` Label on your feature request.

264
doc/contributing/source/external.rst Normal file
View File

@@ -0,0 +1,264 @@
.. 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 chaper 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 <https://www.nsnam.org/wiki/Related_Projects>`_.
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 <https://www.nsnam.org/wiki/Contributed_Code>`_. If you need web server
space for your archive, please contact ``webmaster@nsnam.org``.

1
doc/contributing/source/figures Symbolic link
View File

@@ -0,0 +1 @@
../figures

273
doc/contributing/source/general.rst Normal file
View File

@@ -0,0 +1,273 @@
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _General:
General
-------
This section pertains to general topics about licensing, coding style,
and working with Git features, including patch submission.
Licensing
*********
All code submitted must conform to the project licensing framework, which
is `GNU GPLv2 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>`_
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 |ns3| mainline.
Note that the Free Software Foundation maintains
`a list <https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses>`_ 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 <http://www.softwarefreedom.org/resources/2007/gpl-non-gpl-collaboration.html>`_ 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 |ns3|
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.
Documentation Licensing
=======================
Licensing for documentation or for material found on |ns3| websites
is covered by the `Creative Commons CC-BY-SA 4.0 <https://creativecommons.org/licenses/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.
Copyright
*********
Copyright is a statement of ownership of code, while licensing describes
the terms by which the owners of the code permit the reuse of the code.
The |ns3| project does not maintain copyright of contributed code.
Copyright remains with the author(s) or their employer. Because multiple
people or organizations work on the |ns3| code over time, one can think
of the project and even individual files as a "mixed copyright" work.
Copyright can be stated when originating files in |ns3| or when making
"substantial" changes to such files; the definition of substantial is
open to interpretation. Copyright need not be claimed explicitly by adding
a copyright statement; according to copyright laws in many countries,
copyright rights are automatic upon publishing a work. Copyright should
not be explicitly listed for *all* changes to a file; for instance, patches
to fix small things or make small adjustments or improvements are not
considered to be subjected to copyright protection.
Use of copyright statements in open source projects, as a means of
author attribution, can be controversial, because having a long list
of copyright statements on every file impairs readability. Also,
since copyright is automatic, there is little formal legal requirement
to add a copyright statement. The |ns3| project has decided to follow
the guidance provided by the Software Freedom Law Center in this regard:
https://softwarefreedom.org/resources/2012/ManagingCopyrightInformation.html
Copyright on new files
======================
When originating a new file, the originating author should place his or her
copyright statement at the top in the header, preceding the copy of the
license. An important exception to this is if the new file is copied from
somewhere else and modified to make the new file; please do not delete
the previous copyrights from the copyright file! See below for this case.
An example placement of a copyright statement can be found in the file
``src/network/model/packet.h``::
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2005,2006 INRIA
*
* 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;
Copyright on existing files
===========================
When providing a substantial feature (maintainers and contributors should
mutually agree on this point) as a patch to an existing file, the
contributor may add a copyright statement that clarifies the new portion
of code that is covered by the new copyright. An example is the program
``src/lte/model/lte-ue-phy.h``::
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2010 TELEMATICS LAB, DEE - Politecnico di Bari
* Copyright (c) 2018 Fraunhofer ESK : RLF extensions
*
* 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;
Here, Fraunhofer ESK added extensions to support radio link failure (RLF),
and the copyright statement clarifies the extension (separated from the
organization by a colon).
Copyright on external code copied from elsewhere
================================================
If a contributor borrows code from somewhere else (such as a snippet of
code to implement an algorithm, or whole files altogether), it is important
to keep the original copyright (and license statement) in the new file.
Contributors who fail to do this may be accused of plagiarism.
Some existing examples of code copied from elsewhere are:
* ``src/network/utils/error-model.h``
* ``src/core/model/valgrind.h``
* ``src/core/model/math.h``
If in doubt about how to handle a specific case, ask a maintainer.
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.
Coding style
************
We ask that all contributors make their code conform to the
coding standard which is outlined in :ref:`Coding style`.
The project maintains a Python program called ``check-style.py`` found in
the ``utils/`` directory. This is a wrapper around the ``uncrustify``
utility with configuration set to the conventions used by |ns3|, and
can be used to quickly format new source code files proposed for the
mainline.
Creating a patch
****************
Patches are preferably submitted as a GitLab.com
`Merge Request <https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html>`_.
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.
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 |ns3|, and who
have expressed willingness to maintain some code. |ns3| 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 |ns3| 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 |ns3| distribution will typically be asked to maintain it going forward
(or to find new maintainers for it).

25
doc/contributing/source/index.rst Normal file
View File

@@ -0,0 +1,25 @@
.. only:: html or latex
Contributing to ns-3
====================
This is the guide to *Contributing to ns-3*. Primary documentation for the ns-3 project is available in several forms:
* `ns-3 Doxygen <http://www.nsnam.org/doxygen/index.html>`_: Documentation of the public APIs of the simulator
* Tutorial for the `latest release <http://www.nsnam.org/documentation/latest/>`_ and `development tree <http://www.nsnam.org/ns-3-dev/documentation/>`_
* Contributing to ns-3 (this document)
* Manual, and Model Library for the `latest release <http://www.nsnam.org/documentation/latest/>`_ and `development tree <http://www.nsnam.org/ns-3-dev/documentation/>`_
* `ns-3 wiki <http://www.nsnam.org/wiki/Main_Page>`_
This document is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ for `Sphinx <http://sphinx.pocoo.org/>`_ and is maintained in the
``doc/contributing`` directory of ns-3's source code.
.. toctree::
:maxdepth: 2
introduction
general
enhancements
models
external
coding-style

81
doc/contributing/source/introduction.rst Normal file
View File

@@ -0,0 +1,81 @@
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _Introduction:
Introduction
------------
This document is a guide for those who wish to contribute code to |ns3|
or its related projects in some way.
Changes to |ns3| software are made by
or reviewed by *maintainers*. |ns3| has a small core team of maintainers,
and also some specialized maintainers who maintain a portion of the software.
The source code branch that is centrally maintained is sometimes
called the *mainline*, a term used further herein.
End users are encouraged to report issues and bugs, or to propose
software or documentation modifications, to be reviewed by and handled by
maintainers. End users can also help by reviewing code
proposals made by others. Some end users who contribute high quality
patches or code reviews over time may ask or be invited to become
a maintainer of software within their areas of expertise. Finally, some
end users wish to disseminate their |ns3| work to the community, through
the addition of new features or modules to |ns3|.
A question often asked by newcomers is "How can I contribute to |ns3|?"
or "How do I get started?".
This document summarizes the various ways and processes used to contribute
to |ns3|. Contribution by users is essential for a project maintained
largely by volunteers. However, one of the most scarce resources on
an open source project is the available time of maintainers, so we ask
contributors to please become familiar with conventions and processes
used by |ns3| so as to smooth the contribution process.
The very first step is to become familiar with |ns3| by reading the tutorial,
running some example programs, and then reading some of the code and
documentation to get a feel for things. From that point, there are a
number of options to contribute:
* Contributing a small documentation correction
* Reporting or discussing a bug in the software
* Fixing an already reported bug by submitting a patch
* Reviewing code contributed by others
* Submitting new code for inclusion in the mainline
* Alerting users to code that is maintained or archived elsewhere
* Submitting a module or fork for publishing in the ns-3 app store
* Becoming a maintainer of part of the simulator
|ns3| is mainly a C++ project, and this contribution guide focuses on
how to contribute |ns3| code specifically, but the overall open source
project maintains various related codebases written in several other
languages, so if you are interested in contributing outside of |ns3|
C++ code, there are several possibilities:
* |ns3| provides Python bindings to most of its API, and maintains an
automated API scanning process that relies on other tools. We can use
maintenance help in the C++/Python bindings support.
* Another Python project is the `bake build tool <https://gitlab.com/nsnam/bake/-/issues>`_, which has a number of open issues.
* See also our Python-based `PyViz visualizer <https://www.nsnam.org/wiki/PyViz>`_; extensions and documentation would be welcome.
* The `NetAnim <https://gitlab.com/nsnam/netanim>`_ animator is written in `Qt <https://www.qt.io/>`_ and has lacked a maintainer for several years.
* If you are interested in Linux kernel hacking, or use of applications in |ns3| such as open source routing daemons, we maintain the
`Direct Code Execution project <https://www.nsnam.org/docs/dce/manual/html/index.html>`_.
* If you are familiar with `Django <https://www.djangoproject.com/>`_, we have work to do on `our app store infrastructure <https://gitlab.com/nsnam/ns-3-AppStore>`_.
* Our `website <https://gitlab.com/nsnam/nsnam-web>`_ is written in `Jekyll <https://jekyllrb.com/>`_ and is in need of more work.
The remainder of this document is organized as follows.
* Chapter 2 covers general issues surrounding code and documentation
contributions, including license and copyright;
* Chapter 3 describes approaches for contributing small enhancements to
the |ns3| mainline, such as a documentation or bug fix;
* Chapter 4 outlines the approach for proposing new models for the mainline;
* Chapter 5 describes how to contribute code that will be stored outside
of the |ns3| mainline, with emphasis on the |ns3| *AppStore*; and
* Chapter 6 provides the coding style guidelines that are mandatory for the
|ns3| mainline and strongly suggested for contributed modules.

271
doc/contributing/source/models.rst Normal file
View File

@@ -0,0 +1,271 @@
.. include:: replace.txt
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _Models:
Submitting new models
---------------------
We actively encourage submission of new features to |ns3|.
Independent submissions are essential for open source projects, and if
accepted into the mainline, you will also be credited as an author of
future versions of |ns3|. However,
please keep in mind that there is already a large burden on the |ns3|
maintainers to manage the flow of incoming contributions and maintain new
and existing code. The goal of this chapter is to outline the options for
new models in |ns3|, and how you can help to minimize the burden on maintainers
and thus minimize the average time-to-merge of your code.
Options for new models
**********************
|ns3| is organized into modules, each of which is compiled and linked into
a separate library. Users can selectively enable and disable the inclusion
of modules (via the `--enable-modules` argument to Waf configure, or via
the selective inclusion of contributed modules).
When proposing new models to |ns3|, please keep in mind that not all models
will be accepted into the mainline. However, we aim to provide at least
one or more options for any code contribution.
Because of the long-term maintenance burden, |ns3| is no longer accepting
all new proposals into the mainline. Features that are of general
interest are more likely to be approved for the mainline, but features that
are more specialized may be recommended for the `ns-3 App Store <https://apps.nsnam.org>`_. Some modules that have been in the mainline for a long time, but
fall out of use (or lose their maintainers) may also be moved out of the
mainline into the App Store in the future.
The options for publishing new models are:
1. Propose a Merge Request for the |ns3| mainline and follow the guidelines below.
2. Organize your code as a "contributed module" or modules and maintain them in
your own public Git repository. A page on the App Store can be made to
advertise this to users, and other tooling can be used to ensure that the
module stays compatible with the mainline.
3. Organize your code as a "public fork" that evolves separately from the
|ns3| mainline. This option is sometimes chosen for models that require
significant intrusive changes to the |ns3| mainline to support. Some
recent examples include the Public Safety models and the millimeter-wave
extensions to |ns3|. This has the benefit of being self-contained, but
the drawback of losing compatibility with the mainline over time. A page
on the App Store can be made for these forks as well. For maintenance
reasons and improved user experience, we prefer to upstream mainline
changes so that public forks can be avoided.
4. Archive your code somewhere, or publish in a Git repository, and link to
it from the |ns3| `Contributed Code <https://www.nsnam.org/wiki/Contributed_Code>`_
wiki page. This option requires the least amount of work from the
contributor, but visibility of the code to new |ns3| users will likely be
reduced. To follow this route, obtain a wiki account from the webmaster,
and make edits as appropriate to link your code.
The remainder of the chapter concerns option 1 (upstreaming to ns-3-dev); the
other options are described in the next chapter (:ref:`External`).
Upstreaming new models
**********************
The term "upstreaming" refers to the process whereby new code is
contributed back to an upstream source (the main open source project)
whereby that project takes responsibility for further enhancement and
maintenance.
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.
In brief, we can summarize the guidelines as follows:
1. Be licensed appropriately (see :ref:`General`)
2. Understand how and why |ns3| conducts code reviews before merging
3. Follow the ns-3 coding style (:ref:`Coding style`) and software
engineering and consistency feedback that maintainers may provide
4. Write associated documentation, tests, and example programs
If you do not have the time to follow through the process to include your
code in the main tree, please see the next chapter (:ref:`External`)
about contributing ns-3 code that is not maintained in the main tree.
The process can take a long time when submissions are large or when
contributors skip some of these steps. Therefore, best results are found
when the following guidelines are followed:
* Ask for review of small chunks of code, rather than large patches. Split
large submissions into several more manageable pieces.
* Make sure that the code follows the guidelines (coding style,
documentation, tests, examples) or you may be asked to fix these
things before maintainers look at it again.
Code reviews
************
Code submissions to ns-3-dev are expected to go through a review process
where one or more maintainers comment on the code. The basic purpose of the
code reviews is to ensure the long-term maintenance and overall system
integrity of ns-3. Contributors may be asked
to revise their code or rewrite portions during this process. New features are
also typically only merged during the early stages of a new release cycle,
to avoid destabilizing code before release.
|ns3| code reviews are conducted using GitLab.com merge requests, possibly
supported by discussion on the ns-developers mailing list for reviews that
involve code that cuts across maintainer boundaries or is otherwise
controversial. Many examples of ongoing reviews can be browsed on
our `GitLab.com site <https://gitlab.com/nsnam/ns-3-dev/-/merge_requests>`_.
Submission structure
********************
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
short paragraph at the top of the Merge Request. If you want to flag
to maintainers that your submission is known to be incomplete (e.g., you
are looking for early feedback), preface the title of the Merge Request
with ``Draft:``.
Coherent and multi-part submissions
===================================
Large code submissions should be split into smaller submissions where possible.
The likelihood of getting maintainers to review your submission is inversely
proportional to its size, because large code reviews require a large block
of time for a maintainer. For instance, if you are submitting two
routing protocol models and each protocol model can stand on its own,
submit two Merge Requests rather than a single one containing both models.
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 paragraph.
For example, if you have made changes to optimize one module, and in the
course of doing so, you fixed a bug in another module, make sure you separate
these two sets of changes in two separate submissions.
When splitting a large submission into seprate submissions, (ideally) these
submissions should be prefaced (in the Merge Request description) by a
detailed explanation of the overall plan
such that code reviewers can review each submission separately but within a
larger context. This kind of submission 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.
History rewriting
=================
It is good practice to rebase your feature branch onto the tip of the
(evolving) ns-3-dev, so that the commits appear on top of a recent commit
of ns-3-dev. For instance, you may have started with an initial Merge
Request, and it has been some time to gather feedback from maintainers,
and now you want to update your Merge Request with that feedback. A
rebase onto the current ns-3-dev ``master`` branch is good practice
for any Merge Request update.
In addition, in the course of your development, and in responding to
reviewer comments, the git commit log will accumulate lots of small
commits that are not helpful to future maintainers: they make it more painful
to use the annotate and bisect commands. For this reason, it is good
practice to "squash" and "rebase" commits into coherent groups. For example,
assume that the commit history, after you have responded to a reviewer's
comment, looks like this:
::
commit 4938c01400fb961c37716c3f415f47ba2b04ab5f (HEAD -> master, origin/master, origin/HEAD)
Author: Some Contributor <some.contributor@example.com>
Date: Mon Jun 15 11:19:49 2020 -0700
Fix typo in Doxygen based on code review comment
commit 915cf65cb8f464d9398ddd8bea9af167ced64663
Author: Some Contributor <some.contributor@example.com>
Date: Thu Jun 11 16:44:46 2020 -0400
Add documentation, tests, and examples for clever protocol
commit a1d51db126fb3d1c7c76427473f02ee792fdfd53
Author: Some Contributor <some.contributor@example.com>
Date: Thu Jun 11 16:35:48 2020 -0400
Add new models for clever protocol
In the above case, it will be helpful to squash the top commit about the
typo into the first commit where the Doxygen was first written, leaving
you again with two commits. `Git interactive rebase <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`_ is a good tool for this;
ask a maintainer for help in doing this if you need some help to learn
this process.
Documentation, tests, and examples
**********************************
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.
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
starting the 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).
Including examples
==================
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.
Tests
=====
All new models should include automated tests. These should, where
appropriate, be unit tests of model correctness, validation tests of
stochastic behavior, and overall system tests if the model's interaction with
other components must be tested. 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 ns-3 manual provides documentation and suggestions for
`how to write tests <https://www.nsnam.org/docs//manual/html/how-to-write-tests.html>`_.
Documentation
=============
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:
* Doxygen should be added to header files for all public classes and methods, and should be checked for Doxygen errors
* new features should be described in the ``RELEASE_NOTES``
* public API changes (if any) must be documented in ``CHANGES.html``
* new API or changes to existing API must update the inline doxygen documentation in header files
* consider updating or adding a new section to the manual (``doc/manual``) or
model library (``doc/models``) as appropriate
* update the ``AUTHORS`` file for any new authors
Module dependencies
===================
Since |ns3| is a modular system, each module has (typically) dependencies on
other modules. These must be kept to the minimum necessary, and circular
dependencies must be avoided (they will generate errors).
As an example, the ``lr-wpan`` module depends on ``core``, ``network``,
``mobility``, ``spectrum``, and ``propagation``. Tests for your new module
must not add any other dependency (that was not needed for the model or
helper code itself), but examples can use other modules because their module
dependencies are handled independently. As an example, the ``lr-wpan`` examples
also use the ``stats`` module.
This rule might pose limitations to the authoring of tests. In such a case,
ask a maintainer for suggestions, or check existing tests to find solutions.
Sometimes tests that involve adding additional dependencies are placed into
the ``src/test`` subdirectory.

5
doc/contributing/source/replace.txt Normal file
View File

@@ -0,0 +1,5 @@
.. |ns3| replace:: *ns-3*
.. |ns2| replace:: *ns-2*
.. |check| replace:: :math:`\checkmark`

13
doc/ns3_html_theme/layout.html
View File

@@ -72,15 +72,18 @@
<div id="mDocs"
onmouseover="mcancelclosetime()"
onmouseout="mclosetime()">
<a id="ns3_wiki"
href="http://www.nsnam.org/wiki"
>Wiki</a><br/>
<a id="ns3_man"
href="/docs/manual/html/index.html"
>Manual</a><br/>
<a id="ns3_mod"
href="/docs/models/html/index.html"
>Models</a><br/>
<a id="ns3_con"
href="/docs/contributing/html/index.html"
>Contributing</a><br/>
<a id="ns3_wiki"
href="http://www.nsnam.org/wiki"
>Wiki</a><br/>
</li>
<li><span
onmouseover="mopen('mDev')"
@@ -93,7 +96,9 @@
href="/docs/doxygen/html/index.html"
>API</a><br/>
<a id="ns3_bugs"
href="http://www.nsnam.org/bugzilla/">Bugs</a>
href="https://gitlab.com/nsnam/ns-3-dev/-/issues">Bugs</a>
<a id="ns3_merge"
href="https://gitlab.com/nsnam/ns-3-dev/-/merge_requests">Merge Requests</a>
</li>
</ul>
</div>

13
doc/ns3_html_theme/ns3_doxy_header.html
View File

@@ -68,15 +68,18 @@ $extrastylesheet
<div id="mDocs"
onmouseover="mcancelclosetime()"
onmouseout="mclosetime()">
<a id="ns3_wiki"
href="http://www.nsnam.org/wiki"
>Wiki</a><br/>
<a id="ns3_man"
href="/docs/manual/html/index.html"
>Manual</a><br/>
<a id="ns3_mod"
href="/docs/models/html/index.html"
>Models</a><br/>
<a id="ns3_con"
href="/docs/contributing/html/index.html"
>Contributing</a><br/>
<a id="ns3_wiki"
href="http://www.nsnam.org/wiki"
>Wiki</a><br/>
</li>
<li><span
onmouseover="mopen('mDev')"
@@ -89,7 +92,9 @@ $extrastylesheet
href="/docs/doxygen/index.html"
>API</a><br/>
<a id="ns3_bugs"
href="http://www.nsnam.org/bugzilla/">Bugs</a>
href="https://gitlab.com/nsnam/ns-3-dev/-/issues">Bugs</a><br/>
<a id="ns3_merge"
href="https://gitlab.com/nsnam/ns-3-dev/-/merge_requests">Merge Requests</a>
</li>
</ul>
</div>

3
doc/ns3_html_theme/static/ns3_links.js
View File

@@ -3,6 +3,7 @@ var ns3_site = "https://www.nsnam.org/";
var ns3_home = ns3_site + "";
var ns3_wiki = ns3_site + "wiki";
var ns3_bugs = "https://gitlab.com/nsnam/ns-3-dev/-/issues";
var ns3_merge = "https://gitlab.com/nsnam/ns-3-dev/-/merge_requests";
// Links that depend on version:
// Defined in ns3_version.js:
@@ -42,12 +43,14 @@ if (typeof ns3_builder != 'undefined') {
var ns3_man = ns3_rel + "manual/" + ns3_index;
var ns3_mod = ns3_rel + "models/" + ns3_index;
var ns3_tut = ns3_rel + "tutorial/" + ns3_index;
var ns3_con = ns3_rel + "contributing/" + ns3_index;
function ns3_write_links() {
document.getElementById("ns3_home1").href = ns3_home;
document.getElementById("ns3_home2").href = ns3_home;
document.getElementById("ns3_wiki" ).href = ns3_wiki;
document.getElementById("ns3_bugs" ).href = ns3_bugs;
document.getElementById("ns3_merge" ).href = ns3_merge;
document.getElementById("ns3_api" ).href = ns3_api;
document.getElementById("ns3_man" ).href = ns3_man;