diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..db70750e3 --- /dev/null +++ b/CONTRIBUTING.md @@ -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
What if the status checks are failing?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.
+ +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 | diff --git a/README b/README.md similarity index 55% rename from README rename to README.md index b139b3277..f45671266 100644 --- a/README +++ b/README.md @@ -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]. diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 11ecafc7d..55469d13c 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -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 \ diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index 065e8edef..76ba63ef2 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -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'] diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 7b3609c48..44a777c44 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -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 `_: Documentation of the public APIs of the simulator @@ -17,6 +17,7 @@ This document is written in `reStructuredText 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 ``. 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). diff --git a/doc/mercurial.txt b/doc/mercurial.txt deleted file mode 100644 index fefc88f39..000000000 --- a/doc/mercurial.txt +++ /dev/null @@ -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 -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 - -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 - -