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

Merge branch 'git-migration-documentation-update' into 'master'

Browse Source 
Git migration documentation update. Added CONTRIBUTING.md, modified README.md, and added a section on the manual "Working with git".

See merge request nsnam/ns-3-dev!3
This commit is contained in:
N
2018-12-18 10:47:21 +00:00
parent caa195a49b 3329e8737b
commit 9d7411b4ae
7 changed files with 647 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,290 @@
# Contributing to ns-3
*This file is heavily inspired by Atom's [CONTRIBUTING.md file](https://raw.githubusercontent.com/atom/atom/master/CONTRIBUTING.md).*
The following is a set of guidelines for contributing to ns-3, which are hosted in the [nsnam organization](https://gitlab.com/nsnam) on GitLab.com. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a merge request.
#### Table Of Contents
[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
[What should I know before I get started?](#what-should-i-know-before-i-get-started)
* [ns-3 Documentation](#ns-3-documentation)
* [ns-3 modules](#ns-3-modules)
[How Can I Contribute?](#how-can-i-contribute)
* [Reporting Bugs](#reporting-bugs)
* [Suggesting Enhancements](#suggesting-enhancements)
* [Your First Code Contribution](#your-first-code-contribution)
* [Pull Requests](#pull-requests)
[Styleguides](#styleguides)
* [Git Commit Messages](#git-commit-messages)
* [JavaScript Styleguide](#javascript-styleguide)
* [CoffeeScript Styleguide](#coffeescript-styleguide)
* [Specs Styleguide](#specs-styleguide)
* [Documentation Styleguide](#documentation-styleguide)
[Additional Notes](#additional-notes)
* [Issue and Pull Request Labels](#issue-and-pull-request-labels)
## I don't want to read this whole thing I just have a question!!!
> **Note:** Please don't file an issue to ask a question.
You'll get faster results by using the resources below.
We have an official message board where the community chimes in with helpful advice if you have questions.
* [ns-3-users, the official ns-3 message board](https://groups.google.com/forum/#!forum/ns-3-users)
* [ns-3 manual](https://www.nsnam.org/docs/manual/html/index.html)
If chat is more your speed, you can join the ns-3 Zulip channel:
* [Join the ns-3 Zulip chat](https://ns-3.zulipchat.com/)
* Even though Zulip is a chat service, sometimes it takes several hours
for community members to respond — please be patient!
* Use the `#general` channel for general questions or discussion about ns-3
* Use the `#GSoC` channel for questions about GSoC
* There are many other channels available, check the channel list
## What should I know before I get started?
### ns-3 Documentation
The ns-3 project maintains the documentation in different places, dependings on the need. The documentation that is current with the development tree is the following:
* [Tutorial](https://www.nsnam.org/docs/tutorial/html/index.html): Its purpose is to get you started, with simple examples, into the ns-3 world.
* [Manual](https://www.nsnam.org/docs/manual/html/index.html) is a descriptive documentation of the ns-3 core capabilities, as well as shared development practices.
* [Model library](https://www.nsnam.org/docs/models/html/index.html), contains a list of manuals, one for each module we officially ship.
* [Doxygen](https://www.nsnam.org/docs/doxygen/index.html), contains the programming interface of ns-3, as well as description of classes, methods, and functions that permit the interaction between different modules, as well as with the user code.
### ns-3 modules
ns-3 is an open source project — it's made up of [49 modules](https://gitlab.com/nsnam/ns-3-dev/tree/master/src). When you initially consider contributing to ns-3, you might be unsure about which of those 49 modules implements the functionality you want to change or report a bug for. This section should help you with that.
ns-3 is intentionally very modular, and it's possible that a feature you need or a technology you may want to use is not coming from the official repository, but rather from a [community maintained module](https://apps.nsnam.org/). Each community module has its own repository too, and it should contain the information on how to integrate that code with ns-3. If you are looking, instead, more information on how to work with ns-3's official modules, please take a look first to the [model documentation](https://www.nsnam.org/docs/models/html/index.html).
### Design Decisions
When we make a significant decision in how we maintain the project and what we can or cannot support, we will document it through the [ns-developers mailing list](https://mailman.isi.edu/mailman/listinfo/ns-developers). If you have a question around how we do things, please subscribe and lurk around to see how we proceed. If you have a development problem, please open a new topic and ask your question.
## How Can I Contribute?
### Reporting Bugs
This section guides you through submitting a bug report for ns-3. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:.
Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report).
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
#### Before Submitting A Bug Report (to be completed)
* **Perform a [cursory search](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.
* **Check the [release notes](RELEASE_NOTES)** for a list of known bugs.
#### How Do I Submit A (Good) Bug Report?
Bugs are tracked as [GitLab issues](https://docs.gitlab.com/ee/user/project/issues/). After you've determined [which module](#ns-3-modules) your bug is related to, if it is inside the official distribution then create an issue, label it with the name of the module, and provide as much information as possible.
Explain the problem and include additional details to help maintainers reproduce the problem:
* **Use a clear and descriptive title** for the issue to identify the problem.
* **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 exactly you called. When listing steps, **don't just say what you did, but explain how you did it**. For example, if your program includes modifications to the ns-3 core or a module, please list them (or even better, provide the diffs).
* **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 blocks](https://docs.gitlab.com/ee/user/markdown.html).
* **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.**
* **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](https://docs.gitlab.com/ee/user/markdown.html), or a file attachment.
* **If the problem is related to performance or memory**, include a CPU profile capture with your report.
Include details about your configuration and environment:
* **Which version of ns-3 are you using?**
* **What's the name and version of the OS you're using**?
* **Which [modules](#ns-3-modules) do you have installed?**
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for ns-3, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:.
Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion).
#### Before Submitting An Enhancement Suggestion
* **Check if there's already [a merge request](https://gitlab.com/nsnam/ns-3-dev/merge_requests) which provides that enhancement.**
* **Determine [which module the enhancement should be suggested in](#ns-3-modules).**
* **Perform a [cursory search](https://gitlab.com/nsnam/ns-3-dev/issues)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
#### How Do I Submit A (Good) Enhancement Suggestion?
Enhancement suggestions are tracked as [Gitlab issues](https://docs.gitlab.com/ee/user/project/issues/). After you've determined [which module](#ns-3-modules) your enhancement suggestion is related to, create an issue on that repository and provide the following information:
* **Use a clear and descriptive title** for the issue to identify the suggestion.
* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples.
* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
* **Explain why this enhancement would be useful** to most ns-3 users.
* **Specify the name and version of the OS you're using.**
### Your First Code Contribution
Unsure where to begin contributing to ns-3? You can start by looking through these `beginner` and `help-wanted` issues:
* [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two.
* [Help wanted issues][help-wanted] - issues which should be a bit more involved than `beginner` issues.
Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
#### Local development
ns-3 and all packages can be developed locally. For instructions on how to do this, see the following sections in the [ns-3 Manual](https://www.nsnam.org/docs/manual/html/index.html):
* Contributing to ns-3 with git
### Merge Requests
The process described here has several goals:
- Maintain ns-3's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible ns-3
- Enable a sustainable system for ns-3's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
1. Follow the [styleguides](#styleguides)
2. After you submit your merge request, verify that all status checks are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the merge request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
While the prerequisites above must be satisfied prior to having your merge request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
## Styleguides
### Git Commit Messages
* Use the present tense ("Add feature" not "Added feature")
* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
* Limit the first line to 72 characters or less
* Reference issues in the first line, by prepending `[#issue]`
### C++ guidelines
We maintain our code style through the webpage [Code Style](https://www.nsnam.org/develop/contributing-code/coding-style/) and as a `clang-format` configure [file](https://gitlab.com/nsnam/ns-3-dev/blob/master/.clang-format)
### Documentation Styleguide
* Use [Doxygen](http://www.doxygen.nl/) for what regards the code.
* Use [ReStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) for what regards the model (module) documentation.
## Additional Notes
### Issue and Pull Request Labels
This section lists the labels we use to help us track and manage issues and pull requests.
The labels are loosely grouped by their purpose, but it's not required that every issue have a label from every group or that an issue can't have more than one label from the same group.
Please open an issue on `infrastructure` if you have suggestions for new labels, and if you notice some labels are missing.
#### Type of Issue and Issue State
| Label name | Description |
| --- | --- |
| `enhancement` | Feature requests. |
| `bug` | Confirmed bugs or reports that are very likely to be bugs. |
| `question` | Questions more than bug reports or feature requests (e.g. how do I do X). |
| `feedback` | General feedback more than bug reports or feature requests. |
| `help-wanted` | The ns-3 team would appreciate help from the community in resolving these issues. |
| `beginner` | Less complex issues which would be good first issues to work on for users who want to contribute to ns-3. |
| `more-information-needed` | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). |
| `needs-reproduction` | Likely bugs, but haven't been reliably reproduced. |
| `blocked` | Issues blocked on other issues. |
| `duplicate` | Issues which are duplicates of other issues, i.e. they have been reported before. |
| `wontfix` | The ns-3 team has decided not to fix these issues for now, either because they're working as intended or for some other reason. |
| `invalid` | Issues which aren't valid (e.g. user errors). |
#### Topic Categories
| Label name | Description |
| --- | --- |
| `windows` | Related to ns-3 running on Windows. |
| `linux` | Related to ns-3 running on Linux. |
| `mac` | Related to ns-3 running on macOS. |
| `documentation` | Related to any type of documentation (doxygen, manual, models) |
| `git` | Related to Git functionality (e.g. problems with gitignore files or with showing the correct file status). |
| `infrastructure` | Related to gitlab infrastructure. |
| `utils` | Related to scripts and various utils for ns-3 repository or code maintenance. |
#### Pull Request Labels
| Label name | Description
| --- | --- |
| `work-in-progress` | Pull requests which are still being worked on, more changes will follow. |
| `needs-review` | Pull requests which need code review, and approval from maintainers or ns-3 core team. |
| `under-review` | Pull requests being reviewed by maintainers or ns-3 core team. |
| `requires-changes` | Pull requests which need to be updated based on review comments and then reviewed again. |
| `needs-testing` | Pull requests which need manual testing. |
### Module Labels
| Label name | Description |
| --- | --- |
| `animator` | Any issue related to this module |
| `antenna` | Any issue related to this module |
| `aodv` | Any issue related to this module |
| `applications` | Any issue related to this module |
| `bridge` | Any issue related to this module |
| `brite` | Any issue related to this module |
| `build system` | Any issue related to this module |
| `buildings` | Any issue related to this module |
| `click` | Any issue related to this module |
| `config-store` | Any issue related to this module |
| `core` | Any issue related to this module |
| `csma` | Any issue related to this module |
| `designer` | Any issue related to this module |
| `devices` | Any issue related to this module |
| `dsdv` | Any issue related to this module |
| `dsr` | Any issue related to this module |
| `emulation` | Any issue related to this module |
| `energy` | Any issue related to this module |
| `examples` | Any issue related to this module |
| `fd-net-device` | Any issue related to this module |
| `flow-monitor` | Any issue related to this module |
| `global-routing` | Any issue related to this module |
| `general` | Any issue related to this module |
| `helpers` | Any issue related to this module |
| `internet` | Any issue related to this module |
| `internet-apps` | Any issue related to this module |
| `ipv6` | Any issue related to this module |
| `lr-wpan` | Any issue related to this module |
| `lwip` | Any issue related to this module |
| `lte` | Any issue related to this module |
| `mesh` | Any issue related to this module |
| `mobility-models` | Any issue related to this module |
| `mpi` | Any issue related to this module |
| `netanim` | Any issue related to this module |
| `network` | Any issue related to this module |
| `nix-vector` | Any issue related to this module |
| `nsc-tcp` | Any issue related to this module |
| `olsr` | Any issue related to this module |
| `openflow` | Any issue related to this module |
| `point-to-point` | Any issue related to this module |
| `python bindings` | Any issue related to this module |
| `propagation` | Any issue related to this module |
| `quagga` | Any issue related to this module |
| `regression` | Any issue related to this module |
| `routing` | Any issue related to this module |
| `sixlowpan` | Any issue related to this module |
| `spectrum` | Any issue related to this module |
| `stats` | Any issue related to this module |
| `tap-bridge` | Any issue related to this module |
| `tcp` | Any issue related to this module |
| `test framework` | Any issue related to this module |
| `topology-read` | Any issue related to this module |
| `traffic-control` | Any issue related to this module |
| `uan` | Any issue related to this module |
| `virtual-net-device` | Any issue related to this module |
| `visualizer` | Any issue related to this module |
| `wave module` | Any issue related to this module |
| `wifi` | Any issue related to this module |
| `wimax` | Any issue related to this module |

91
README → README.md
View File

@@ -1,21 +1,19 @@
The Network Simulator, Version 3
--------------------------------
The Network Simulator, Version 3
================================
Table of Contents:
------------------
## Table of Contents:
1) An overview
2) Building ns-3
3) Running ns-3
4) Getting access to the ns-3 documentation
5) Working with the development version of ns-3
1) [An overview](#an-open-source-project)
2) [Building ns-3](#building-ns-3)
3) [Running ns-3](#running-ns3)
4) [Getting access to the ns-3 documentation](#getting-access-to-the-ns-3-documentation)
5) [Working with the development version of ns-3](#working-with-the-development-version-of-ns-3)
Note: Much more substantial information about ns-3 can be found at
http://www.nsnam.org
1) An Open Source project
-------------------------
## An Open Source project
ns-3 is a free open source project aiming to build a discrete-event
network simulator targeted for simulation research and education.
@@ -34,8 +32,7 @@ This README excerpts some details from a more extensive
tutorial that is maintained at:
http://www.nsnam.org/documentation/latest/
2) Building ns-3
----------------
## Building ns-3
The code for the framework and the default models provided
by ns-3 is built as a set of libraries. User simulations
@@ -49,40 +46,47 @@ included in the file doc/build.txt
However, the real quick and dirty way to get started is to
type the command
./waf configure --enable-examples
```shell
./waf configure --enable-examples
```
followed by
./waf
in the directory which contains
this README file. The files built will be copied in the
build/ directory.
```shell
./waf
```
in the directory which contains this README file. The files
built will be copied in the build/ directory.
The current codebase is expected to build and run on the
set of platforms listed in the RELEASE_NOTES file.
set of platforms listed in the [release notes](RELEASE_NOTES)
file.
Other platforms may or may not work: we welcome patches to
improve the portability of the code to these other platforms.
Other platforms may or may not work: we welcome patches to
improve the portability of the code to these other platforms.
3) Running ns-3
---------------
## Running ns-3
On recent Linux systems, once you have built ns-3 (with examples
enabled), it should be easy to run the sample programs with the
following command, such as:
./waf --run simple-global-routing
```shell
./waf --run simple-global-routing
```
That program should generate a simple-global-routing.tr text
trace file and a set of simple-global-routing-xx-xx.pcap binary
pcap trace files, which can be read by tcpdump -tt -r filename.pcap
That program should generate a `simple-global-routing.tr` text
trace file and a set of `simple-global-routing-xx-xx.pcap` binary
pcap trace files, which can be read by `tcpdump -tt -r filename.pcap`
The program source can be found in the examples/routing directory.
4) Getting access to the ns-3 documentation
-------------------------------------------
## Getting access to the ns-3 documentation
Once you have verified that your build of ns-3 works by running
the simple-point-to-point example as outlined in 3) above, it is
quite likely that you will want to get started on reading
some ns-3 documentation.
some ns-3 documentation.
All of that documentation should always be available from
the ns-3 website: http:://www.nsnam.org/documentation/.
@@ -90,7 +94,7 @@ the ns-3 website: http:://www.nsnam.org/documentation/.
This documentation includes:
- a tutorial
- a reference manual
- models in the ns-3 model library
@@ -98,20 +102,25 @@ This documentation includes:
- a wiki for user-contributed tips: http://www.nsnam.org/wiki/
- API documentation generated using doxygen: this is
a reference manual, most likely not very well suited
a reference manual, most likely not very well suited
as introductory text:
http://www.nsnam.org/doxygen/index.html
5) Working with the development version of ns-3
-----------------------------------------------
## Working with the development version of ns-3
If you want to download and use the development version
of ns-3, you need to use the tool 'mercurial'. A quick and
dirty cheat sheet is included in doc/mercurial.txt but
reading through the mercurial tutorials included on the
mercurial website is usually a good idea if you are not
If you want to download and use the development version of ns-3, you
need to use the tool `git`. A quick and dirty cheat sheet is included
in the manual, but reading through the git
tutorials found in the Internet is usually a good idea if you are not
familiar with it.
If you have successfully installed mercurial, you can get
If you have successfully installed git, you can get
a copy of the development version with the following command:
"hg clone http://code.nsnam.org/ns-3-dev"
```shell
git clone https://gitlab.com/nsnam/ns-3-dev.git
```
However, we recommend to follow the Gitlab guidelines for starters,
that includes creating a Gitlab account, forking the ns-3-dev project
under the new account's name, and then cloning the forked repository.
You can find more information in the manual [link].

1
doc/manual/Makefile
View File

@@ -16,6 +16,7 @@ SOURCES = \
source/replace.txt \
source/attributes.rst \
source/callbacks.rst \
source/working-with-git.rst \
source/documentation.rst \
source/enable-modules.rst \
source/enable-tests.rst \

2
doc/manual/source/conf.py
View File

@@ -25,7 +25,7 @@ import sys, os
# 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.pngmath']
extensions = ['sphinx.ext.imgmath']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

4
doc/manual/source/index.rst
View File

@@ -3,7 +3,7 @@
ns-3 Manual
===========
This is the *ns-3 Manual*. Primary documentation for the ns-3 project is
This is the *ns-3 Manual*. Primary documentation for the ns-3 project is
available in five forms:
* `ns-3 Doxygen <http://www.nsnam.org/doxygen/index.html>`_: Documentation of the public APIs of the simulator
@@ -17,6 +17,7 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
:maxdepth: 2
organization
working-with-git
random-variables
hash-functions
events
@@ -34,4 +35,3 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
python
tests
support

303
doc/manual/source/working-with-git.rst Normal file
View File

@@ -0,0 +1,303 @@
.. include:: replace.txt
.. highlight:: cpp
.. Section Separators:
----
****
++++
====
~~~~
.. _Working with git:
Working with git as a user
--------------------------
The ns-3 project used Mercurial in the past as its source code control system, but it has moved to Git in December 2018. Git is a VCS like Mercurial, Subversion or CVS, and it used to maintain many open-source (and closed-source) project. While git and mercurial have a lot of common properties, if you are new to git you should read first an introduction to it. The most up-to-date guide is the Git Book, at https://git-scm.com/book/en/v2/Getting-Started-Git-Basics.
The ns-3 project is officially hosted on GitLab.com at https://gitlab.com/nsnam/. For convenience and historical reasons, ns-3-dev mirrors are currently posted on Bitbucket.com and GitHub.com, and kept in sync with the official repository periodically via cron jobs. We recommend that users who have been working from one of these mirrors repoint their remotes so that they pull origin or upstream from GitLab.com (see below explanation about how to configure remotes).
This section of the manual provides common tips for both users and maintainers. Since the first part is shared, in this manual section we will start a personal repository and then explain what to do in some typical cases. ns-3 users often combine ns-3-dev with other repositories (pybindgen, netanim, apps from the app store). This manual chapter does not cover this use case; it only focuses on the single ns-3-dev repository. See other project documentation such as the ns-3 tutorial for descriptions on bundled releases distributed as source archives, or on the bake build tool for managing multiple repositories. The guidelines listed below also largely pertain to the user who is using (and cloning) bake from the GitLab.com repository.
ns-3's Git workflow in a nutshell
*********************************
Experienced git users will not necessarily need instruction on how to set up personal repositories (below). However, they should be aware of the project's workflow:
* The main repository's master branch is the main development branch.
* Releases are tagged changesets on the master branch. If a hotfix release must be made from a changeset in the past, a new hotfix support branch will be created and maintained for any such releases. Hotfix releases will be tagged from the hotfix support branch if it has diverged from master.
* Maintainers can commit obvious non-critical fixes (documentation improvements, typos etc.) directly into the master branch. Users who are not maintainers can create Merge Requests for small items such as these.
* For each new major feature, create a feature branch in your own fork. Create Merge Requests as needed to solicit review. Merge feature branches into master after review. Merged feature branches can then be deleted.
Setup of a personal repository
******************************
We will provide two ways, one anonymous (but will impede the creation of merge requests) and the other, preferred, that include forking the repository through the GitLab.com web interface.
Directly cloning ns-3-dev
+++++++++++++++++++++++++
If you go to the official ns-3-dev page, hosted at https://gitlab.com/nsnam/ns-3-dev, you can find a button that says ```Clone``. If you are not logged in, then you will see only the option of cloning the repository through HTTPS, with this command:
.. sourcecode:: bash
$ git clone https://gitlab.com/nsnam/ns-3-dev.git
If this command exits successfully, you will have a newly created `ns-3-dev` directory with all the source code.
Forking ns-3-dev on GitLab.com
++++++++++++++++++++++++++++++
Assume that you are the user *john* on GitLab.com and that you want to create a new repository that is synced with nsnam/ns-3-dev.
#. Log into GitLab.com
#. Navigate to https://gitlab.com/nsnam/ns-3-dev
#. In the top-right corner of the page, click ``Fork``.
Note that you may only do this once; if you try to fork again, Gitlab will take you to the page of the original fork. So, if you are planning to maintain two or more separate forks (for example, one for your private work, another for maintenance, etc.), you are doing a mistake. Instead, you should add these forks as a remote of your existing directory (see below for adding remotes). Usually, it is a good thing to add the maintainer's repository as remotes, because it can happen that "bleeding edge" features will appear there before landing in ns-3.
For more information on forking with Gilab, there is plenty of visual documentation (https://docs.gitlab.com/ee/gitlab-basics/fork-project.html). To work with your forked repository, you have two way: one is a clean clone while the other is meant to re-use an existing ns-3 git repository.
Clone your forked repository on your machine
============================================
Git is a distributed versioning system. This means that *nobody* will touch your personal repository, until you do something. Please note that every gitlab user has, at least, two repositories: the first is represented by the repository hosted on gitlab servers, which will be called in the following ``origin``. Then, you have your clone on your machine. This means that you could have many clones, on different machines, which points to ``origin``.
To clone the newly created fork to your system go to the homepage of your fork (that should be in the form `https://gitlab.com/your-user-name/ns-3-dev`) and click the `Clone` button. Then, go to your computer's terminal, and issue the command (please refer to https://docs.gitlab.com/ee/gitlab-basics/command-line-commands.html#clone-your-project for more documentation):
.. sourcecode:: bash
$ git clone https://gitlab.com/your-user-name/ns-3-dev
$ cd ns-3-dev-git
In this example we used the HTTPS address because in some place the git + ssh address is blocked by firewalls. If are not under this constraint, it is recommended to use the git + ssh address to avoid the username/password typing at each request.
Naming conventions
==================
Git is able to fetch and push changes to several repositories, each of them is called ``remote``. With time, you probably will have many remotes, each one with many branches. To avoid confusion, it is recommended to give meaningful names to the remotes; in the following, we will use ``origin`` to indicate the ns-3-dev repository in your personal namespace (your forked version, server-side) and ``nsnam`` to indicate the ns-3-dev repository in the nsnam namespace, server-side.
Add the official ns-3 repository as remote upstream
***************************************************
You could have already used git in the past, and therefore already having a ns-3 git repository somewhere. Or, instead, you could have it cloned for the first time in the step above. In both cases, when you fork/clone a repository, your history is no more bound to the repository itself. At this point, it is your duty to sync your fork with the original repository. The first remote repository we have encountered is ``origin``; we must add the official ns-3 repo as another remote repository:
.. sourcecode:: bash
$ git remote add nsnam https://gitlab.com/nsnam/ns-3-dev
With the command above, we added a remote repository, named upstream, which links to the official ns-3 repo. To show your remote repositories:
.. sourcecode:: bash
$ git remote show
To see to what ``origin`` is linking to:
.. sourcecode:: bash
$ git remote show origin
Many options are available; please refer to the git manual for more.
Add your forked repository as remote
************************************
If you were an users of the old github mirror, you probably have an existing git repository installed somewhere. In your case, it is not necessary to clone your fork and to port all your work in the new directory; you can add the fork as new remote.
.. sourcecode:: bash
$ git remote rename origin old-origin
$ git remote add origin https://gitlab.com/your-user-name/ns-3-dev
After these two commands, you will have a remote, named origin, that points
to your forked repository on gitlab.
Keep in sync your repository with latest ns-3-dev updates
*********************************************************
We assume, from now to the end of this document, that you will not make commits on top of the master branch. It should be kept clean from *any* personal modifications: all the works must be done in branches. Therefore, to move the current HEAD of the master branch to the latest commit in ns-3-dev, you should do:
.. sourcecode:: bash
$ git checkout master
$ git fetch nsnam
$ git pull nsnam master
If you tried a pull which resulted in a conflict and you would like to start over, you can recover with git reset (but this never happens if you do not commit over master).
Start a new branch to do some work
**********************************
Look at the available branches:
.. sourcecode:: bash
$ git branch -a
you should see something like:
.. sourcecode:: bash
* master
remotes/origin/master
remotes/nsnam/master
The branch master is your local master branch; remotes/origin/master point at the master branch on your repository located in the Gitlab server, while remotes/upstream/master points to the official master branch.
Before entering in details on how to create a new branch, we have to explain why it is recommended to do it. First of all, if you put all your work in a separate branch, you can easily see the diff between ns-3 mainline and your feature branch (with ``git diff master``). Also, you can integrate more easily the upstream advancements in your work, and when you wish, you can create a *conflict-free* merge request, that will ease the maintainer's job in reviewing your work.
To create a new branch, starting from master, the command is:
.. sourcecode:: bash
$ git checkout master
$ git checkout -b [name_of_your_new_branch]
To switch between branches, remove the -b option. You should now see:
.. sourcecode:: bash
$ git branch -a
* master
[name_of_your_new_branch]
remotes/origin/master
remotes/upstream/master
Edit and commit the modifications
*********************************
After you edit some file, you should commit the difference. As a policy, git users love small and incremental patches. So, commit early, and commit often: you could rewrite your history later.
Suppose we edited ``src/internet/model/tcp-socket-base.cc``. With git status, we can see the repostory status:
.. sourcecode:: bash
$ git status
On branch tcp-next
Your branch is up-to-date with 'mirror/tcp-next'.
Changes not staged for commit:
modified: src/internet/model/tcp-socket-base.cc
and we can see the edits with git diff:
.. sourcecode:: bash
$ git diff
nat@miyamoto ~/Work/ns-3-dev-git (tcp-next)$ git diff
diff --git i/src/internet/model/tcp-socket-base.cc w/src/internet/model/tcp-socket-base.cc
index 1bf0f69..e2298b0 100644
--- i/src/internet/model/tcp-socket-base.cc
+++ w/src/internet/model/tcp-socket-base.cc
@@ -1439,6 +1439,10 @@ TcpSocketBase::ReceivedAck (Ptr<Packet> packet, const TcpHeader& tcpHeader)
// There is a DupAck
++m_dupAckCount;
+ // I'm introducing a subtle bug!
+
+ m_tcb->m_cWnd = m_tcb->m_ssThresh;
+
if (m_tcb->m_congState == TcpSocketState::CA_OPEN)
{
// From Open we go Disorder
To create a commit, select the file you want to add to the commit with git add:
.. sourcecode:: bash
$ git add src/internet/model/tcp-socket-base.cc
and then commit the result:
.. sourcecode:: bash
$ git commit -m "My new TCP broken"
Of course, it would be better to have some rules for the commit message: they will be reported in the next subsection.
Commit message guidelines
+++++++++++++++++++++++++
The commit title should not go over the 80 char limit. It should be prefixed by the name of the module you are working on, and if it fixes a bug, it should reference it in the commit title. For instance, a good commit title would be:
tcp: My new TCP broken
Another example is:
tcp: (fixes #2322) Corrected the uint32_t wraparound during recovery
In the body message, try to explain what the problem was, and how you resolved that. If it is a new feature, try to describe it at a very high level, and highlight any modifications that changed the behaviour or the interface towards the users or other modules.
Commit log
++++++++++
You can see the history of the commits with git log. To show a particular commit, copy the sha-id and use ``git show <sha-id>``. The ID is unique, so it can be referenced in emails or in issues. The next step is useful if you plan to contribute back your changes, but also to keep your feature branch updated with the latest changes from ns-3-dev.
Rebase your branch on top of master
***********************************
Meanwhile you were busy with your branch, the upstream master could have changed. To rebase your work with the now new master, first of all sync your master branch (pulling the nsnam/master branch into your local master branch) as explained before; then
.. sourcecode:: bash
$ git checkout [name_of_your_new_branch]
$ git rebase master
The last command will rewind your work, update the HEAD of your branch to the actual master, and then re-apply all your work. If some of your work conflicts with the actual master, you will be asked to fix these conflicts if automatic merge fails.
Pushing your changes to origin
******************************
After you have done some work on a branch, if you would like to share it with others there is nothing better than pushing your work to your origin repository, on Gitlab servers.
.. sourcecode:: bash
$ git checkout [name_of_your_new_branch]
$ git push origin [name_of_your_new_branch]
The ``git push`` command can be used every time you need to push something from your computer to a remote repository, except when you propose changes to the main ns-3-dev repository: your changes must pass a review stage.
Please note that for older git version, the push command looks like:
.. sourcecode:: bash
$ git push -u origin [name_of_your_new_branch]
Submit work for review
**********************
After you push your branch to origin, you can follow the instructions here https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html to create a merge request. Please remember to add, as reviewer, at least one maintainer. To get the information on who is maintaining what, please refer to the nsnam website.
Porting patches from mercurial repositories to git
**************************************************
Placeholder section. Please improve it.
Working with git as a maintainer
--------------------------------
As a maintainer, you are a person who has write access to the main nsnam repository. You could push your own work (without passing from code review) or push someone else's work. Let's investigate the two cases.
Pushing your own work
*********************
Since you have been added to the Developer list on Gitlab (if not, please open an issue) you can use the git + ssh address when adding nsnam as remote. Once you have done that, you can do your modifications to a local branch, then update the master to point to the latest changes of the nsnam repo, and then:
.. sourcecode:: bash
$ git checkout master
$ git pull nsnam master
$ git merge [your_branch_name]
$ git push nsnam master
Please note that if you want to keep track of your branch, you can use as command ``git merge --no-ff [your_branch_name]``. It is always recommended to rebase your branch before merging, to have a clean history. That is not a requirement, though: git perfectly handles a master with parallel merged branches.
Review and merge someone else's work
************************************
Gitlab.com has a plenty of documentation on how to handle merge requests. Please take a look here: https://docs.gitlab.com/ee/user/project/merge_requests/index.html.
If you are committing a patch from someone else, and it is not coming through a Merge Request process, you can use the --author='' argument to 'git commit' to assign authorship to another email address (such as we have done in the past with the Mercurial -u option).

45
doc/mercurial.txt
View File

@@ -1,45 +0,0 @@
Introduction
------------
ns-3 uses the Mercurial software revision control system which
is a replacement for tools liks cvs or subversion. Thus, to get
access to the development versions of ns-3, you need to install
mercurial first. See http://www.selenic.com/mercurial/wiki/
Mercurial cheat sheet
---------------------
Look at our project history and source code:
-------------------------------------------
http://code.nsnam.org/ns-3-dev
clone this repository:
---------------------
hg clone http://code.nsnam.org/ns-3-dev
commit locally:
--------------
hg status
hg add <new files, if any>
hg ci -m "message"
pull development tree changes to your local repository:
------------------------------------------------------
hg ci -m "my local changes are recorded"
hg pull http://code.nsnam.org/ns-3-dev
hg update (apply the changes) OR
hg merge (if you've made local changes)
view the change log:
-------------------
hg log <file>
push upwards (developers access only):
--------------------------------------
To the main repository:
hg push ssh://code@code.nsnam.org/repos/ns-3-dev
To your private repository:
hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository