From faa2bb23dd93fd17ee72437750c02d23d008e38f Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Thu, 13 Dec 2018 18:21:03 +0100 Subject: [PATCH 1/9] doc: Move README to README.md (With formatting update) The markdown syntax is more web-friendly for the platform we are currently using as code repository. --- README => README.md | 70 ++++++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 32 deletions(-) rename README => README.md (69%) diff --git a/README b/README.md similarity index 69% rename from README rename to README.md index b139b3277..d817200f8 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,35 +46,42 @@ 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. -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 @@ -102,16 +106,18 @@ This documentation includes: 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 +of ns-3, you need to use the tool `mercurial`. A quick and +dirty cheat sheet is included in +[doc/mercurial.txt](doc/mercurial.txt) but reading through the mercurial tutorials included on the mercurial website is usually a good idea if you are not familiar with it. If you have successfully installed mercurial, you can get a copy of the development version with the following command: -"hg clone http://code.nsnam.org/ns-3-dev" +```shell +hg clone http://code.nsnam.org/ns-3-dev +``` From a25e09ca099f1e1d37799bf89eed2b758990b240 Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Fri, 14 Dec 2018 12:31:45 +0100 Subject: [PATCH 2/9] doc: added CONTRIBUTING.md, references to git --- CONTRIBUTING.md | 256 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 19 ++-- doc/mercurial.txt | 45 -------- 3 files changed, 267 insertions(+), 53 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 doc/mercurial.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..f2e557367 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,256 @@ +# Contributing to ns-3 + +[comment]: # (This file is heavily inspired by Atom's CONTRIBUTING.md file: https://raw.githubusercontent.com/atom/atom/master/CONTRIBUTING.md) + +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: + +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) + * [Atom and Packages](#atom-and-packages) + * [Atom Design Decisions](#design-decisions) + +[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://link) + * Even though Zulip is a chat service, sometimes it takes several hours + for community members to respond — please be patient! + * Use the `#ns3` channel for general questions or discussion about ns-3 + * Use the `#electron` channel for questions about Electron + * Use the `#packages` channel for questions or discussion about writing or contributing to Atom packages (both core and community) + * Use the `#ui` channel for questions and discussion about Atom UI and themes + * 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). Fill out [the required template](ISSUE_TEMPLATE.md), the information it asks for helps us resolve issues faster. + +> **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) + +* **Check the [debugging guide](https://flight-manual.atom.io/hacking-atom/sections/debugging/).** You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem [in the latest version of Atom](https://flight-manual.atom.io/hacking-atom/sections/debugging/#update-to-the-latest-version), if the problem happens when you run Atom in [safe mode](https://flight-manual.atom.io/hacking-atom/sections/debugging/#check-if-the-problem-shows-up-in-safe-mode), and if you can get the desired behavior by changing [Atom's or packages' config settings](https://flight-manual.atom.io/hacking-atom/sections/debugging/#check-atom-and-package-settings). +* **Check the [FAQs on the forum](https://discuss.atom.io/c/faq)** for a list of common questions and problems. +* **Determine [which repository the problem should be reported in](#atom-and-packages)**. +* **Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aatom)** 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. + +#### 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 the following information by filling in [the template](doc/ISSUE_TEMPLATE.md). + +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](https://flight-manual.atom.io/hacking-atom/sections/debugging/#diagnose-runtime-performance) 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). Fill in [the template](doc/ISSUE_TEMPLATE.md), including the steps that you imagine you would take if the feature you're requesting existed. + +#### 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 Atom? 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 all instructions in [the template](doc/MERGE_REQUEST_TEMPLATE.md) +2. Follow the [styleguides](#styleguides) +3. 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 | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | +| --- | --- | --- | --- | +| `enhancement` | [search][search-atom-repo-label-enhancement] | [search][search-atom-org-label-enhancement] | Feature requests. | +| `bug` | [search][search-atom-repo-label-bug] | [search][search-atom-org-label-bug] | Confirmed bugs or reports that are very likely to be bugs. | +| `question` | [search][search-atom-repo-label-question] | [search][search-atom-org-label-question] | Questions more than bug reports or feature requests (e.g. how do I do X). | +| `feedback` | [search][search-atom-repo-label-feedback] | [search][search-atom-org-label-feedback] | General feedback more than bug reports or feature requests. | +| `help-wanted` | [search][search-atom-repo-label-help-wanted] | [search][search-atom-org-label-help-wanted] | The Atom core team would appreciate help from the community in resolving these issues. | +| `beginner` | [search][search-atom-repo-label-beginner] | [search][search-atom-org-label-beginner] | Less complex issues which would be good first issues to work on for users who want to contribute to Atom. | +| `more-information-needed` | [search][search-atom-repo-label-more-information-needed] | [search][search-atom-org-label-more-information-needed] | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). | +| `needs-reproduction` | [search][search-atom-repo-label-needs-reproduction] | [search][search-atom-org-label-needs-reproduction] | Likely bugs, but haven't been reliably reproduced. | +| `blocked` | [search][search-atom-repo-label-blocked] | [search][search-atom-org-label-blocked] | Issues blocked on other issues. | +| `duplicate` | [search][search-atom-repo-label-duplicate] | [search][search-atom-org-label-duplicate] | Issues which are duplicates of other issues, i.e. they have been reported before. | +| `wontfix` | [search][search-atom-repo-label-wontfix] | [search][search-atom-org-label-wontfix] | The Atom core team has decided not to fix these issues for now, either because they're working as intended or for some other reason. | +| `invalid` | [search][search-atom-repo-label-invalid] | [search][search-atom-org-label-invalid] | Issues which aren't valid (e.g. user errors). | +| `package-idea` | [search][search-atom-repo-label-package-idea] | [search][search-atom-org-label-package-idea] | Feature request which might be good candidates for new packages, instead of extending Atom or core Atom packages. | +| `wrong-repo` | [search][search-atom-repo-label-wrong-repo] | [search][search-atom-org-label-wrong-repo] | Issues reported on the wrong repository (e.g. a bug related to the [Settings View package](https://github.com/atom/settings-view) was reported on [Atom core](https://github.com/atom/atom)). | + +#### Topic Categories + +| Label name | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | +| --- | --- | --- | --- | +| `windows` | [search][search-atom-repo-label-windows] | [search][search-atom-org-label-windows] | Related to Atom running on Windows. | +| `linux` | [search][search-atom-repo-label-linux] | [search][search-atom-org-label-linux] | Related to Atom running on Linux. | +| `mac` | [search][search-atom-repo-label-mac] | [search][search-atom-org-label-mac] | Related to Atom running on macOS. | +| `documentation` | [search][search-atom-repo-label-documentation] | [search][search-atom-org-label-documentation] | Related to any type of documentation (e.g. [API documentation](https://atom.io/docs/api/latest/) and the [flight manual](https://flight-manual.atom.io/)). | +| `performance` | [search][search-atom-repo-label-performance] | [search][search-atom-org-label-performance] | Related to performance. | +| `security` | [search][search-atom-repo-label-security] | [search][search-atom-org-label-security] | Related to security. | +| `ui` | [search][search-atom-repo-label-ui] | [search][search-atom-org-label-ui] | Related to visual design. | +| `api` | [search][search-atom-repo-label-api] | [search][search-atom-org-label-api] | Related to Atom's public APIs. | +| `uncaught-exception` | [search][search-atom-repo-label-uncaught-exception] | [search][search-atom-org-label-uncaught-exception] | Issues about uncaught exceptions, normally created from the [Notifications package](https://github.com/atom/notifications). | +| `crash` | [search][search-atom-repo-label-crash] | [search][search-atom-org-label-crash] | Reports of Atom completely crashing. | +| `auto-indent` | [search][search-atom-repo-label-auto-indent] | [search][search-atom-org-label-auto-indent] | Related to auto-indenting text. | +| `encoding` | [search][search-atom-repo-label-encoding] | [search][search-atom-org-label-encoding] | Related to character encoding. | +| `network` | [search][search-atom-repo-label-network] | [search][search-atom-org-label-network] | Related to network problems or working with remote files (e.g. on network drives). | +| `git` | [search][search-atom-repo-label-git] | [search][search-atom-org-label-git] | Related to Git functionality (e.g. problems with gitignore files or with showing the correct file status). | + +#### `atom/atom` Topic Categories + +| Label name | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | +| --- | --- | --- | --- | +| `editor-rendering` | [search][search-atom-repo-label-editor-rendering] | [search][search-atom-org-label-editor-rendering] | Related to language-independent aspects of rendering text (e.g. scrolling, soft wrap, and font rendering). | +| `build-error` | [search][search-atom-repo-label-build-error] | [search][search-atom-org-label-build-error] | Related to problems with building Atom from source. | +| `error-from-pathwatcher` | [search][search-atom-repo-label-error-from-pathwatcher] | [search][search-atom-org-label-error-from-pathwatcher] | Related to errors thrown by the [pathwatcher library](https://github.com/atom/node-pathwatcher). | +| `error-from-save` | [search][search-atom-repo-label-error-from-save] | [search][search-atom-org-label-error-from-save] | Related to errors thrown when saving files. | +| `error-from-open` | [search][search-atom-repo-label-error-from-open] | [search][search-atom-org-label-error-from-open] | Related to errors thrown when opening files. | +| `installer` | [search][search-atom-repo-label-installer] | [search][search-atom-org-label-installer] | Related to the Atom installers for different OSes. | +| `auto-updater` | [search][search-atom-repo-label-auto-updater] | [search][search-atom-org-label-auto-updater] | Related to the auto-updater for different OSes. | +| `deprecation-help` | [search][search-atom-repo-label-deprecation-help] | [search][search-atom-org-label-deprecation-help] | Issues for helping package authors remove usage of deprecated APIs in packages. | +| `electron` | [search][search-atom-repo-label-electron] | [search][search-atom-org-label-electron] | Issues that require changes to [Electron](https://electron.atom.io) to fix or implement. | + +#### Pull Request Labels + +| Label name | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description +| --- | --- | --- | --- | +| `work-in-progress` | [search][search-atom-repo-label-work-in-progress] | [search][search-atom-org-label-work-in-progress] | Pull requests which are still being worked on, more changes will follow. | +| `needs-review` | [search][search-atom-repo-label-needs-review] | [search][search-atom-org-label-needs-review] | Pull requests which need code review, and approval from maintainers or Atom core team. | +| `under-review` | [search][search-atom-repo-label-under-review] | [search][search-atom-org-label-under-review] | Pull requests being reviewed by maintainers or Atom core team. | +| `requires-changes` | [search][search-atom-repo-label-requires-changes] | [search][search-atom-org-label-requires-changes] | Pull requests which need to be updated based on review comments and then reviewed again. | +| `needs-testing` | [search][search-atom-repo-label-needs-testing] | [search][search-atom-org-label-needs-testing] | Pull requests which need manual testing. | diff --git a/README.md b/README.md index d817200f8..5dfa7cec5 100644 --- a/README.md +++ b/README.md @@ -108,16 +108,19 @@ This documentation includes: ## 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](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 [doc/mercurial.txt](doc/git.txt) 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: ```shell -hg clone http://code.nsnam.org/ns-3-dev +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/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 - - From 52fb6a6e5493160c3832ec0a514ed85dd80590ec Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Fri, 14 Dec 2018 12:35:13 +0100 Subject: [PATCH 3/9] doc: [WIP] Section on the manual for git --- doc/manual/Makefile | 1 + doc/manual/source/conf.py | 2 +- doc/manual/source/contributing-with-git.rst | 344 ++++++++++++++++++++ doc/manual/source/index.rst | 1 + 4 files changed, 347 insertions(+), 1 deletion(-) create mode 100644 doc/manual/source/contributing-with-git.rst diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 11ecafc7d..1f0b5df99 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -16,6 +16,7 @@ SOURCES = \ source/replace.txt \ source/attributes.rst \ source/callbacks.rst \ + source/contributing-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/contributing-with-git.rst b/doc/manual/source/contributing-with-git.rst new file mode 100644 index 000000000..f8649d7ad --- /dev/null +++ b/doc/manual/source/contributing-with-git.rst @@ -0,0 +1,344 @@ +.. include:: replace.txt +.. highlight:: cpp + +.. Section Separators: + ---- + **** + ++++ + ==== + ~~~~ + +.. _Contributing with git: + +Contributing with git +--------------------- + +The ns-3 project used Mercurial in the past as its source code control system, but is 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](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book). + +Ns-3 project is officially hosted on GitLab.com at [this address](https://gitlab.com/nsnam/ns-3-dev). + +This section of the manual provides common tips for both users and maintainers. Since the first part is common, we will start a personal repository setup and a first example of contribution. + +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. + +Anonumously cloning ns-3-dev +++++++++++++++++++++++++++++ + +If you go to the [official ns-3-dev page](https://gitlab.com/nsnam/ns-3-dev) you can find a button that says `Clone`. If you are not logged in, then you will find 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 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. + +For more information on forking with Gilab, there is plenty of visual [documentation](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html). + +Clone your repository on your machine +===================================== + +Clone the newly created fork to your system going 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](https://docs.gitlab.com/ee/gitlab-basics/command-line-commands.html#clone-your-project): + +.. sourcecode:: bash + + $ git clone https://gitlab.com/your-user-name/ns-3-dev + $ cd ns-3-dev-git + +Add the remote to an existing ns-3-dev installation +=================================================== + +If you already used git in the past, you probably have + + +== Typical workflow == + +Git is a distributed versioning system. This means that '''nobody''' will touch your personal repo, until you do something. Please note that every github user has, at least, two repositories: the first is represented by the repository hosted on github 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 refers to ''origin''. + +=== Add the official ns-3 repository as remote upstream === + +When you fork 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. +Git is able to fetch and push changes to several repositories, each of them is called '''remote'''. The first remote repository we have encountered is ''origin''; we must add the official ns-3 repo as another remote repository. + + git remote add upstream https://github.com/nsnam/ns-3-dev-git + +With the command above, we added a remote repository, named upstream, which links to the official ns-3 repo. To show your remote repositories: + + git remote show + +To see to what ''origin'' is linking to: + + git remote show origin + +You can also delete remotes: + + git remote remove [name] + +Many options are available; please refer to the git manual for more. + +=== Sync your repo === + +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. Move the current HEAD to the master branch: + + git checkout master + +and fetch the changes from ''upstream'': + + git fetch upstream + +we can now merge the official changes into our master: + + git pull upstream master + +If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with git reset (but this never happens if you do not commit over master). + +=== Start a new branch === + +Now look at the available branches: + + git branch -a + +you should see: + + * master + remotes/origin/master + remotes/upstream/master + +The branch master is your local master branch; remotes/origin/master point at the master branch on your repository located in the Github server, while remotes/upstream/master points to the official master branch. + +To create a new branch, which hopefully will contains new feature or bug correction, the command is + + git checkout -b [name_of_your_new_branch] + +To switch between branches, remove the -b option. You should now see: + + 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: + + + 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: + + +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, 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: + + git add src/internet/model/tcp-socket-base.cc + +and then commit the result: + + git commit -m "My new TCP broken" + +You can see the history of the commits with git log. To show a particular commit, copy the sha id and use git show . +Do this until you feature or bug is corrected; now, it is time to make a review request. + +=== Rebase your branch on 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 as explained before; then + + git checkout [name_of_your_new_branch] + git rebase master + +this 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. + +=== Creating a patch against master === + +If you are in a branch and want to diff it against master, you can type: + + git diff master + +and redirect to a patch: + + git diff master > patch-against-master.patch + +To preserve all your commits, it is preferable to create many patches, one for each commit: + + git format-patch master + +and then you could submit them for a review. + +=== Rewrite your history === + +Let's suppose that, after a first round of review, you are asked to fix something. After you commited the fix of your (previously bad) commit, the log should be something like: + + +nat@miyamoto ~/Work/ns-3-dev-git (tcp-next)$ git log +Sun Jan 17 14:43:36 2016 +0100 9cfa78e (HEAD -> tcp-next) Fix for the previous [Tony Spinner] +Sun Jan 17 14:43:16 2016 +0100 77ad6e1 first version of TCP broken [Tony Spinner] +Mon Jan 11 14:44:13 2016 -0800 e2fc90a (origin/master, upstream/master, master) update some stale tutorial info [Someone] +Mon Jan 11 21:11:54 2016 +0100 1df9c0d Bug 2257 - Ipv[4,6]InterfaceContainer::Add are not consistent [Someone] + + +If you plan to resubmit a review, you would like to merge the commits (original and its fix). You can easily do this with git rebase -i (--interactive). + + git rebase -i master + +and an editor should pop up, with your commits, and various possibilities: + + +pick 77ad6e1 first version of TCP broken +pick 9cfa78e Fix for the previous + +# Rebase e2fc90a..9cfa78e onto e2fc90a (10 command(s)) +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup = like "squash", but discard this commit's log message +# x, exec = run command (the rest of the line) using shell +# d, drop = remove commit +# +# These lines can be re-ordered; they are executed from top to bottom. +# +# If you remove a line here THAT COMMIT WILL BE LOST. +# +# However, if you remove everything, the rebase will be aborted. +# +# Note that empty commits are commented out + + +What we want is to "fixup" the fix commit into the previous. So, changing "pick" to "fixup" (or simply f) and saving and quitting the editor is sufficient. The edited content: + + +pick 77ad6e1 first version of TCP broken +f 9cfa78e Fix for the previous + + +The resulting history: + + +nat@miyamoto ~/Work/ns-3-dev-git (tcp-next)$ git log +Sun Jan 17 14:43:16 2016 +0100 847e9a8 (HEAD -> tcp-next) first version of TCP broken [Tony Spinner] +Mon Jan 11 14:44:13 2016 -0800 e2fc90a (origin/master, upstream/master, master) update some stale tutorial info [Someone] +Mon Jan 11 21:11:54 2016 +0100 1df9c0d Bug 2257 - Ipv[4,6]InterfaceContainer::Add are not consistent [Someone] + + +Please remember that rewriting already published history is '''bad''', especially if someone other has synced your commits into their repository, but is necessary if you want to make clear commits. As a general rule, your personal development history can be rewritten as you wish; the history of your published features should be kept as they are. + +== Collaborating: an example of exchange between a maintainer and a contributor == +In the following we will explain a typical git workflow in the case of an exchange between a maintainer (M) and a contributor (C). It's clear that M is the only one that can push over the official ns-3-dev repo; but sometime, commits from C should be reviewed and tested out-of-the-tree. Now, we will follow two paths, corresponding to the actions of C and the actions of M. + +=== How a contributor could made commits to be reviewed by a maintainer === + +The first step for C is to set up a fork of the official ns-3-dev-git repository (see before). Then, if the M has it own repository, with some branches dedicated to future work that can be included next in the ns-3-dev repository, C should add its remote and fetch the index: + + git remote add [name] [url] + git fetch [name] + +For instance, let's assume we are working on TCP. Nat usually has his own "next-to-be-pushed" work in the branch "tcp-next" of his repo on github. Therefore, C should start its work from this branch. + + git remote add nat https://github.com/kronat/ns-3-dev-git + git fetch + git checkout -b [feature_name] nat/tcp-next + +Please note that this is an example; the repo name, address, and the branch name could be different. At this point, the (local) branch of C called [feature_name] is tracking nat/tcp-next, and so it has all the same commits. C can start to work, using the normal workflow. + +When the set of commit is ready, C can push the branch to its own repository. Just do: + + git push + +NO ! This will likely results in an error, since C does not have the permission into writing the M repo. C should create a new branch in his own repository: + + git push -u origin [feature_name] + +That command will change the upstream reference, setting it to your origin (which is likely your github repo), and pushing all the work into the remote "origin". For a visual representation of what is happening: + + +[commit 169] <----- C/tcp-next +.... ( work of C on tcp-next ) +[commit 160] <----- nat/tcp-next +.... (previous work on TCP) +[commit 123] <---- ns-3-dev-git +... (official ns-3 history) + + +Well, at this point C could notify M: "Please, see my work at github.com/C/ns-3-dev-git in the branch [feature_name]!" and maybe asking for a merge. And it's time to change the perspective, passing to M. + +=== A maintainer with a lot of contributor === + +M has been notified of the work of C. The first thing he has to do is to adding the C repository to his (long) list of remotes: + + git remote add [C_name] [C_repo] + git fetch [C_name] + +Then, he could quickly view the work done by the contributor: + + git checkout -b [local_C_name] [C_name]/[C_branch] + +If M thinks the work is well-done and ok, he could directly merge it into his branch: + + git checkout tcp-next + git checkout merge [local_C_name] + +At this point, after some time, if the works is ok M should push the changes to the ns-3-dev mercurial repo. This is really tedious, and should be done carefully.. And it will be explained later in this HOWTO. But, as it often happens, M could made comments, and then wait another patchset. + + git checkout master + git branch -D [local_C_name] + +=== A quick flash-back to C === + +Often the maintainer will made changes to that branch, because works of other contributor could have been merged, or whatever. So, C should be ready to _REBASE_ his own branch. Please note that a maintainer is *forced* to merge the contributor's work, because otherwise will broke the history of many. But each single contributor should *rebase* his work on the maintainer branch (or the master if the maintainer has no one). So, please go back and re-read carefully the section for rebasing the work. + +=== Pushing things to ns-3-dev mercurial repository === + +Of course this applies only for maintainers. When you have a local branch (e.g. tcp-next) that is ready to be merged in ns-3-dev, please do the following: +# Pull the ns-3-dev-git master into your master branch +# Rebase your local tcp-next branch to your local master branch +# Create a series of patch that applies on top of master: + git format-patch master +# Copy these patches in ns-3-dev mercurial repo +# Apply and commit one-by-one all these patches, paying attention to the right owner of the commit. + +One last thing: for binary patches this doesn't work: you need to update by hand all the files. We still need to figure a way to export correctly binary patches from git to mercurial. + +== Cheat sheet == +=== Removing all local changes not tracked in the index (Dangerous) === + + git clean -df + git checkout -- . diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 7b3609c48..37a2726da 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -17,6 +17,7 @@ This document is written in `reStructuredText Date: Sun, 16 Dec 2018 11:20:00 +0100 Subject: [PATCH 4/9] doc: finished manual --- doc/manual/source/contributing-with-git.rst | 369 ++++++++------------ 1 file changed, 144 insertions(+), 225 deletions(-) diff --git a/doc/manual/source/contributing-with-git.rst b/doc/manual/source/contributing-with-git.rst index f8649d7ad..1bef849cf 100644 --- a/doc/manual/source/contributing-with-git.rst +++ b/doc/manual/source/contributing-with-git.rst @@ -8,26 +8,26 @@ ==== ~~~~ -.. _Contributing with git: +.. _Working with git: -Contributing with git ---------------------- +Working with git as a user +-------------------------- -The ns-3 project used Mercurial in the past as its source code control system, but is 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](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book). +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](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book). -Ns-3 project is officially hosted on GitLab.com at [this address](https://gitlab.com/nsnam/ns-3-dev). +The ns-3 project is officially hosted on GitLab.com at https://gitlab.com/nsnam/. -This section of the manual provides common tips for both users and maintainers. Since the first part is common, we will start a personal repository setup and a first example of contribution. +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. 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. -Anonumously cloning ns-3-dev -++++++++++++++++++++++++++++ +Directly cloning ns-3-dev ++++++++++++++++++++++++++ -If you go to the [official ns-3-dev page](https://gitlab.com/nsnam/ns-3-dev) you can find a button that says `Clone`. If you are not logged in, then you will find only the option of cloning the repository through HTTPS, with this command: +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 @@ -38,307 +38,226 @@ If this command exits successfully, you will have a newly created `ns-3-dev` dir Forking ns-3-dev on GitLab.com ++++++++++++++++++++++++++++++ -Assume that you are user 'john' on GitLab.com, and that you want to create a new repository that is synced with nsnam/ns-3-dev. +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'''. +#. 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. -For more information on forking with Gilab, there is plenty of visual [documentation](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html). +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 repository on your machine -===================================== +Clone your forked repository on your machine +============================================ -Clone the newly created fork to your system going 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](https://docs.gitlab.com/ee/gitlab-basics/command-line-commands.html#clone-your-project): +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 -Add the remote to an existing ns-3-dev installation -=================================================== +In this example we used the HTTPS address, but if you have a permissive setup, it is recommended to use the git + ssh address to avoid the username/password typing at each request. -If you already used git in the past, you probably have +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. -== Typical workflow == +Add the official ns-3 repository as remote upstream +*************************************************** -Git is a distributed versioning system. This means that '''nobody''' will touch your personal repo, until you do something. Please note that every github user has, at least, two repositories: the first is represented by the repository hosted on github 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 refers to ''origin''. +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: -=== Add the official ns-3 repository as remote upstream === +.. sourcecode:: bash -When you fork 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. -Git is able to fetch and push changes to several repositories, each of them is called '''remote'''. The first remote repository we have encountered is ''origin''; we must add the official ns-3 repo as another remote repository. - - git remote add upstream https://github.com/nsnam/ns-3-dev-git + $ 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: - git remote show +.. sourcecode:: bash -To see to what ''origin'' is linking to: + $ git remote show - git remote show origin +To see to what ``origin`` is linking to: -You can also delete remotes: +.. sourcecode:: bash - git remote remove [name] + $ git remote show origin Many options are available; please refer to the git manual for more. -=== Sync your repo === +Add your forked repository as remote +************************************ -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. Move the current HEAD to the master branch: +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. - git checkout master +.. sourcecode:: bash -and fetch the changes from ''upstream'': + $ git remote rename origin old-origin + $ git remote add origin https://gitlab.com/your-user-name/ns-3-dev - git fetch upstream +After these two commands, you will have a remote, named origin, that points +to your forked repository on gitlab. -we can now merge the official changes into our master: +Keep in sync your repository with latest ns-3-dev updates +********************************************************* - git pull upstream master +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: -If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with git reset (but this never happens if you do not commit over master). +.. sourcecode:: bash -=== Start a new branch === + $ git checkout master + $ git fetch nsnam + $ git pull nsnam master -Now look at the available branches: +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). - git branch -a +Start a new branch to do some work +********************************** -you should see: +Look at the available branches: - * master - remotes/origin/master - remotes/upstream/master +.. sourcecode:: bash -The branch master is your local master branch; remotes/origin/master point at the master branch on your repository located in the Github server, while remotes/upstream/master points to the official master branch. + $ git branch -a -To create a new branch, which hopefully will contains new feature or bug correction, the command is +you should see something like: - git checkout -b [name_of_your_new_branch] +.. 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. + +To create a new branch, starting from master, which hopefully will contains new feature or bug correction, 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: - git branch -a +.. sourcecode:: bash - * master - [name_of_your_new_branch] - remotes/origin/master - remotes/upstream/master + $ git branch -a + * master + [name_of_your_new_branch] + remotes/origin/master + remotes/upstream/master -=== Edit and commit the modifications === +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: +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 - - 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: - -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, const TcpHeader& tcpHeader) - // There is a DupAck - ++m_dupAckCount; +.. 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, 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 -+ // 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: - git add src/internet/model/tcp-socket-base.cc +.. sourcecode:: bash + + $ git add src/internet/model/tcp-socket-base.cc and then commit the result: - git commit -m "My new TCP broken" +.. sourcecode:: bash -You can see the history of the commits with git log. To show a particular commit, copy the sha id and use git show . -Do this until you feature or bug is corrected; now, it is time to make a review request. + $ git commit -m "My new TCP broken" -=== Rebase your branch on master === +You can see the history of the commits with git log. To show a particular commit, copy the sha-id and use ``git show ``. Do this until you feature or bug is corrected; now, it is time to make a merge request. -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 as explained before; then +Rebase your branch on top of master +*********************************** - git checkout [name_of_your_new_branch] - git rebase 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 -this 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. +.. sourcecode:: bash -=== Creating a patch against master === + $ git checkout [name_of_your_new_branch] + $ git rebase master -If you are in a branch and want to diff it against master, you can type: +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. - git diff master +Pushing your changes to origin +****************************** -and redirect to a patch: +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. - git diff master > patch-against-master.patch +.. sourcecode:: bash -To preserve all your commits, it is preferable to create many patches, one for each commit: + $ git checkout [name_of_your_new_branch] + $ git push origin [name_of_your_new_branch] - git format-patch master +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. -and then you could submit them for a review. +Submit work for review +********************** -=== Rewrite your history === +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. -Let's suppose that, after a first round of review, you are asked to fix something. After you commited the fix of your (previously bad) commit, the log should be something like: +Porting patches from mercurial repositories to git +************************************************** - -nat@miyamoto ~/Work/ns-3-dev-git (tcp-next)$ git log -Sun Jan 17 14:43:36 2016 +0100 9cfa78e (HEAD -> tcp-next) Fix for the previous [Tony Spinner] -Sun Jan 17 14:43:16 2016 +0100 77ad6e1 first version of TCP broken [Tony Spinner] -Mon Jan 11 14:44:13 2016 -0800 e2fc90a (origin/master, upstream/master, master) update some stale tutorial info [Someone] -Mon Jan 11 21:11:54 2016 +0100 1df9c0d Bug 2257 - Ipv[4,6]InterfaceContainer::Add are not consistent [Someone] - +Section to write. -If you plan to resubmit a review, you would like to merge the commits (original and its fix). You can easily do this with git rebase -i (--interactive). +Working with git as a maintainer +-------------------------------- - git rebase -i master +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 (but that is not recommended), or push someone else's work. Let's investigate the two cases. -and an editor should pop up, with your commits, and various possibilities: +Pushing your own work +********************* - -pick 77ad6e1 first version of TCP broken -pick 9cfa78e Fix for the previous +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: -# Rebase e2fc90a..9cfa78e onto e2fc90a (10 command(s)) -# -# Commands: -# p, pick = use commit -# r, reword = use commit, but edit the commit message -# e, edit = use commit, but stop for amending -# s, squash = use commit, but meld into previous commit -# f, fixup = like "squash", but discard this commit's log message -# x, exec = run command (the rest of the line) using shell -# d, drop = remove commit -# -# These lines can be re-ordered; they are executed from top to bottom. -# -# If you remove a line here THAT COMMIT WILL BE LOST. -# -# However, if you remove everything, the rebase will be aborted. -# -# Note that empty commits are commented out - +.. sourcecode:: bash -What we want is to "fixup" the fix commit into the previous. So, changing "pick" to "fixup" (or simply f) and saving and quitting the editor is sufficient. The edited content: + $ git checkout master + $ git merge [your_branch_name] + $ git push nsnam master - -pick 77ad6e1 first version of TCP broken -f 9cfa78e Fix for the previous - +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. -The resulting history: +Review and merge someone else's work +************************************ - -nat@miyamoto ~/Work/ns-3-dev-git (tcp-next)$ git log -Sun Jan 17 14:43:16 2016 +0100 847e9a8 (HEAD -> tcp-next) first version of TCP broken [Tony Spinner] -Mon Jan 11 14:44:13 2016 -0800 e2fc90a (origin/master, upstream/master, master) update some stale tutorial info [Someone] -Mon Jan 11 21:11:54 2016 +0100 1df9c0d Bug 2257 - Ipv[4,6]InterfaceContainer::Add are not consistent [Someone] - - -Please remember that rewriting already published history is '''bad''', especially if someone other has synced your commits into their repository, but is necessary if you want to make clear commits. As a general rule, your personal development history can be rewritten as you wish; the history of your published features should be kept as they are. - -== Collaborating: an example of exchange between a maintainer and a contributor == -In the following we will explain a typical git workflow in the case of an exchange between a maintainer (M) and a contributor (C). It's clear that M is the only one that can push over the official ns-3-dev repo; but sometime, commits from C should be reviewed and tested out-of-the-tree. Now, we will follow two paths, corresponding to the actions of C and the actions of M. - -=== How a contributor could made commits to be reviewed by a maintainer === - -The first step for C is to set up a fork of the official ns-3-dev-git repository (see before). Then, if the M has it own repository, with some branches dedicated to future work that can be included next in the ns-3-dev repository, C should add its remote and fetch the index: - - git remote add [name] [url] - git fetch [name] - -For instance, let's assume we are working on TCP. Nat usually has his own "next-to-be-pushed" work in the branch "tcp-next" of his repo on github. Therefore, C should start its work from this branch. - - git remote add nat https://github.com/kronat/ns-3-dev-git - git fetch - git checkout -b [feature_name] nat/tcp-next - -Please note that this is an example; the repo name, address, and the branch name could be different. At this point, the (local) branch of C called [feature_name] is tracking nat/tcp-next, and so it has all the same commits. C can start to work, using the normal workflow. - -When the set of commit is ready, C can push the branch to its own repository. Just do: - - git push - -NO ! This will likely results in an error, since C does not have the permission into writing the M repo. C should create a new branch in his own repository: - - git push -u origin [feature_name] - -That command will change the upstream reference, setting it to your origin (which is likely your github repo), and pushing all the work into the remote "origin". For a visual representation of what is happening: - - -[commit 169] <----- C/tcp-next -.... ( work of C on tcp-next ) -[commit 160] <----- nat/tcp-next -.... (previous work on TCP) -[commit 123] <---- ns-3-dev-git -... (official ns-3 history) - - -Well, at this point C could notify M: "Please, see my work at github.com/C/ns-3-dev-git in the branch [feature_name]!" and maybe asking for a merge. And it's time to change the perspective, passing to M. - -=== A maintainer with a lot of contributor === - -M has been notified of the work of C. The first thing he has to do is to adding the C repository to his (long) list of remotes: - - git remote add [C_name] [C_repo] - git fetch [C_name] - -Then, he could quickly view the work done by the contributor: - - git checkout -b [local_C_name] [C_name]/[C_branch] - -If M thinks the work is well-done and ok, he could directly merge it into his branch: - - git checkout tcp-next - git checkout merge [local_C_name] - -At this point, after some time, if the works is ok M should push the changes to the ns-3-dev mercurial repo. This is really tedious, and should be done carefully.. And it will be explained later in this HOWTO. But, as it often happens, M could made comments, and then wait another patchset. - - git checkout master - git branch -D [local_C_name] - -=== A quick flash-back to C === - -Often the maintainer will made changes to that branch, because works of other contributor could have been merged, or whatever. So, C should be ready to _REBASE_ his own branch. Please note that a maintainer is *forced* to merge the contributor's work, because otherwise will broke the history of many. But each single contributor should *rebase* his work on the maintainer branch (or the master if the maintainer has no one). So, please go back and re-read carefully the section for rebasing the work. - -=== Pushing things to ns-3-dev mercurial repository === - -Of course this applies only for maintainers. When you have a local branch (e.g. tcp-next) that is ready to be merged in ns-3-dev, please do the following: -# Pull the ns-3-dev-git master into your master branch -# Rebase your local tcp-next branch to your local master branch -# Create a series of patch that applies on top of master: - git format-patch master -# Copy these patches in ns-3-dev mercurial repo -# Apply and commit one-by-one all these patches, paying attention to the right owner of the commit. - -One last thing: for binary patches this doesn't work: you need to update by hand all the files. We still need to figure a way to export correctly binary patches from git to mercurial. - -== Cheat sheet == -=== Removing all local changes not tracked in the index (Dangerous) === - - git clean -df - git checkout -- . +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. From a9f19edb3b1d959b88b4c658406b4c26083cfc04 Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Sun, 16 Dec 2018 11:24:14 +0100 Subject: [PATCH 5/9] doc: moved contributing-with-git to working-with-git --- doc/manual/Makefile | 2 +- doc/manual/source/index.rst | 5 ++--- .../{contributing-with-git.rst => working-with-git.rst} | 0 3 files changed, 3 insertions(+), 4 deletions(-) rename doc/manual/source/{contributing-with-git.rst => working-with-git.rst} (100%) diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 1f0b5df99..55469d13c 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -16,7 +16,7 @@ SOURCES = \ source/replace.txt \ source/attributes.rst \ source/callbacks.rst \ - source/contributing-with-git.rst \ + source/working-with-git.rst \ source/documentation.rst \ source/enable-modules.rst \ source/enable-tests.rst \ diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 37a2726da..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,7 +17,7 @@ This document is written in `reStructuredText Date: Sun, 16 Dec 2018 11:25:48 +0100 Subject: [PATCH 6/9] doc: Contributing added explicit ACK to Atom --- CONTRIBUTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2e557367..5e3fc9f39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,6 @@ # Contributing to ns-3 -[comment]: # (This file is heavily inspired by Atom's CONTRIBUTING.md file: https://raw.githubusercontent.com/atom/atom/master/CONTRIBUTING.md) - -:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: +*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. From 7c3388f09f282006a3bc0afddba46f25a22780ba Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Sun, 16 Dec 2018 18:24:36 +0100 Subject: [PATCH 7/9] doc: updated manual git section --- doc/manual/source/working-with-git.rst | 60 +++++++++++++++++++++----- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/doc/manual/source/working-with-git.rst b/doc/manual/source/working-with-git.rst index 1bef849cf..30c098e3d 100644 --- a/doc/manual/source/working-with-git.rst +++ b/doc/manual/source/working-with-git.rst @@ -13,11 +13,21 @@ 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](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics Git Book). +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/. +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. +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 ****************************** @@ -44,7 +54,7 @@ Assume that you are the user *john* on GitLab.com and that you want to create a #. 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. +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). 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. @@ -60,12 +70,12 @@ To clone the newly created fork to your system go to the homepage of your fork ( $ git clone https://gitlab.com/your-user-name/ns-3-dev $ cd ns-3-dev-git -In this example we used the HTTPS address, but if you have a permissive setup, it is recommended to use the git + ssh address to avoid the username/password typing at each request. +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. +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 *************************************************** @@ -135,7 +145,9 @@ you should see something like: 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. -To create a new branch, starting from master, which hopefully will contains new feature or bug correction, the command is +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 @@ -203,7 +215,25 @@ and then commit the result: $ git commit -m "My new TCP broken" -You can see the history of the commits with git log. To show a particular commit, copy the sha-id and use ``git show ``. Do this until you feature or bug is corrected; now, it is time to make a merge request. +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 *********************************** @@ -229,6 +259,13 @@ After you have done some work on a branch, if you would like to share it with ot 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 ********************** @@ -237,12 +274,12 @@ After you push your branch to origin, you can follow the instructions here https Porting patches from mercurial repositories to git ************************************************** -Section to write. + 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 (but that is not recommended), or push someone else's work. Let's investigate the two cases. +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 ********************* @@ -252,6 +289,7 @@ Since you have been added to the Developer list on Gitlab (if not, please open a .. sourcecode:: bash $ git checkout master + $ git pull nsnam master $ git merge [your_branch_name] $ git push nsnam master @@ -261,3 +299,5 @@ 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). From 79fd0747ac0b3bb2fe87afa0b4c4e6414ec75295 Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Mon, 17 Dec 2018 11:09:02 +0100 Subject: [PATCH 8/9] doc: Fixed Contributing.md --- CONTRIBUTING.md | 175 +++++++++++++++++++++++++++++------------------- README.md | 12 ++-- 2 files changed, 112 insertions(+), 75 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e3fc9f39..7dbffc5f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,8 +9,8 @@ The following is a set of guidelines for contributing to ns-3, which are hosted [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) - * [Atom and Packages](#atom-and-packages) - * [Atom Design Decisions](#design-decisions) + * [ns-3 Documentation](#ns-3-documentation) + * [ns-3 modules](#ns-3-modules) [How Can I Contribute?](#how-can-i-contribute) * [Reporting Bugs](#reporting-bugs) @@ -41,13 +41,11 @@ We have an official message board where the community chimes in with helpful adv If chat is more your speed, you can join the ns-3 Zulip channel: -* [Join the ns-3 Zulip chat](https://link) +* [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 `#ns3` channel for general questions or discussion about ns-3 - * Use the `#electron` channel for questions about Electron - * Use the `#packages` channel for questions or discussion about writing or contributing to Atom packages (both core and community) - * Use the `#ui` channel for questions and discussion about Atom UI and themes + * 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? @@ -77,20 +75,18 @@ When we make a significant decision in how we maintain the project and what we c 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). Fill out [the required template](ISSUE_TEMPLATE.md), the information it asks for helps us resolve issues faster. +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) -* **Check the [debugging guide](https://flight-manual.atom.io/hacking-atom/sections/debugging/).** You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem [in the latest version of Atom](https://flight-manual.atom.io/hacking-atom/sections/debugging/#update-to-the-latest-version), if the problem happens when you run Atom in [safe mode](https://flight-manual.atom.io/hacking-atom/sections/debugging/#check-if-the-problem-shows-up-in-safe-mode), and if you can get the desired behavior by changing [Atom's or packages' config settings](https://flight-manual.atom.io/hacking-atom/sections/debugging/#check-atom-and-package-settings). -* **Check the [FAQs on the forum](https://discuss.atom.io/c/faq)** for a list of common questions and problems. -* **Determine [which repository the problem should be reported in](#atom-and-packages)**. -* **Perform a [cursory search](https://github.com/search?q=+is%3Aissue+user%3Aatom)** 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. +* **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 the following information by filling in [the template](doc/ISSUE_TEMPLATE.md). +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: @@ -100,7 +96,7 @@ Explain the problem and include additional details to help maintainers reproduce * **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](https://flight-manual.atom.io/hacking-atom/sections/debugging/#diagnose-runtime-performance) with your report. +* **If the problem is related to performance or memory**, include a CPU profile capture with your report. Include details about your configuration and environment: @@ -112,7 +108,7 @@ Include details about your configuration and environment: 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). Fill in [the template](doc/ISSUE_TEMPLATE.md), including the steps that you imagine you would take if the feature you're requesting existed. +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 @@ -133,7 +129,7 @@ Enhancement suggestions are tracked as [Gitlab issues](https://docs.gitlab.com/e ### Your First Code Contribution -Unsure where to begin contributing to Atom? You can start by looking through these `beginner` and `help-wanted` issues: +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. @@ -193,62 +189,103 @@ Please open an issue on `infrastructure` if you have suggestions for new labels, #### Type of Issue and Issue State -| Label name | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | -| --- | --- | --- | --- | -| `enhancement` | [search][search-atom-repo-label-enhancement] | [search][search-atom-org-label-enhancement] | Feature requests. | -| `bug` | [search][search-atom-repo-label-bug] | [search][search-atom-org-label-bug] | Confirmed bugs or reports that are very likely to be bugs. | -| `question` | [search][search-atom-repo-label-question] | [search][search-atom-org-label-question] | Questions more than bug reports or feature requests (e.g. how do I do X). | -| `feedback` | [search][search-atom-repo-label-feedback] | [search][search-atom-org-label-feedback] | General feedback more than bug reports or feature requests. | -| `help-wanted` | [search][search-atom-repo-label-help-wanted] | [search][search-atom-org-label-help-wanted] | The Atom core team would appreciate help from the community in resolving these issues. | -| `beginner` | [search][search-atom-repo-label-beginner] | [search][search-atom-org-label-beginner] | Less complex issues which would be good first issues to work on for users who want to contribute to Atom. | -| `more-information-needed` | [search][search-atom-repo-label-more-information-needed] | [search][search-atom-org-label-more-information-needed] | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). | -| `needs-reproduction` | [search][search-atom-repo-label-needs-reproduction] | [search][search-atom-org-label-needs-reproduction] | Likely bugs, but haven't been reliably reproduced. | -| `blocked` | [search][search-atom-repo-label-blocked] | [search][search-atom-org-label-blocked] | Issues blocked on other issues. | -| `duplicate` | [search][search-atom-repo-label-duplicate] | [search][search-atom-org-label-duplicate] | Issues which are duplicates of other issues, i.e. they have been reported before. | -| `wontfix` | [search][search-atom-repo-label-wontfix] | [search][search-atom-org-label-wontfix] | The Atom core team has decided not to fix these issues for now, either because they're working as intended or for some other reason. | -| `invalid` | [search][search-atom-repo-label-invalid] | [search][search-atom-org-label-invalid] | Issues which aren't valid (e.g. user errors). | -| `package-idea` | [search][search-atom-repo-label-package-idea] | [search][search-atom-org-label-package-idea] | Feature request which might be good candidates for new packages, instead of extending Atom or core Atom packages. | -| `wrong-repo` | [search][search-atom-repo-label-wrong-repo] | [search][search-atom-org-label-wrong-repo] | Issues reported on the wrong repository (e.g. a bug related to the [Settings View package](https://github.com/atom/settings-view) was reported on [Atom core](https://github.com/atom/atom)). | +| 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 | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | -| --- | --- | --- | --- | -| `windows` | [search][search-atom-repo-label-windows] | [search][search-atom-org-label-windows] | Related to Atom running on Windows. | -| `linux` | [search][search-atom-repo-label-linux] | [search][search-atom-org-label-linux] | Related to Atom running on Linux. | -| `mac` | [search][search-atom-repo-label-mac] | [search][search-atom-org-label-mac] | Related to Atom running on macOS. | -| `documentation` | [search][search-atom-repo-label-documentation] | [search][search-atom-org-label-documentation] | Related to any type of documentation (e.g. [API documentation](https://atom.io/docs/api/latest/) and the [flight manual](https://flight-manual.atom.io/)). | -| `performance` | [search][search-atom-repo-label-performance] | [search][search-atom-org-label-performance] | Related to performance. | -| `security` | [search][search-atom-repo-label-security] | [search][search-atom-org-label-security] | Related to security. | -| `ui` | [search][search-atom-repo-label-ui] | [search][search-atom-org-label-ui] | Related to visual design. | -| `api` | [search][search-atom-repo-label-api] | [search][search-atom-org-label-api] | Related to Atom's public APIs. | -| `uncaught-exception` | [search][search-atom-repo-label-uncaught-exception] | [search][search-atom-org-label-uncaught-exception] | Issues about uncaught exceptions, normally created from the [Notifications package](https://github.com/atom/notifications). | -| `crash` | [search][search-atom-repo-label-crash] | [search][search-atom-org-label-crash] | Reports of Atom completely crashing. | -| `auto-indent` | [search][search-atom-repo-label-auto-indent] | [search][search-atom-org-label-auto-indent] | Related to auto-indenting text. | -| `encoding` | [search][search-atom-repo-label-encoding] | [search][search-atom-org-label-encoding] | Related to character encoding. | -| `network` | [search][search-atom-repo-label-network] | [search][search-atom-org-label-network] | Related to network problems or working with remote files (e.g. on network drives). | -| `git` | [search][search-atom-repo-label-git] | [search][search-atom-org-label-git] | Related to Git functionality (e.g. problems with gitignore files or with showing the correct file status). | - -#### `atom/atom` Topic Categories - -| Label name | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description | -| --- | --- | --- | --- | -| `editor-rendering` | [search][search-atom-repo-label-editor-rendering] | [search][search-atom-org-label-editor-rendering] | Related to language-independent aspects of rendering text (e.g. scrolling, soft wrap, and font rendering). | -| `build-error` | [search][search-atom-repo-label-build-error] | [search][search-atom-org-label-build-error] | Related to problems with building Atom from source. | -| `error-from-pathwatcher` | [search][search-atom-repo-label-error-from-pathwatcher] | [search][search-atom-org-label-error-from-pathwatcher] | Related to errors thrown by the [pathwatcher library](https://github.com/atom/node-pathwatcher). | -| `error-from-save` | [search][search-atom-repo-label-error-from-save] | [search][search-atom-org-label-error-from-save] | Related to errors thrown when saving files. | -| `error-from-open` | [search][search-atom-repo-label-error-from-open] | [search][search-atom-org-label-error-from-open] | Related to errors thrown when opening files. | -| `installer` | [search][search-atom-repo-label-installer] | [search][search-atom-org-label-installer] | Related to the Atom installers for different OSes. | -| `auto-updater` | [search][search-atom-repo-label-auto-updater] | [search][search-atom-org-label-auto-updater] | Related to the auto-updater for different OSes. | -| `deprecation-help` | [search][search-atom-repo-label-deprecation-help] | [search][search-atom-org-label-deprecation-help] | Issues for helping package authors remove usage of deprecated APIs in packages. | -| `electron` | [search][search-atom-repo-label-electron] | [search][search-atom-org-label-electron] | Issues that require changes to [Electron](https://electron.atom.io) to fix or implement. | +| 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 | `atom/atom` :mag_right: | `atom`‑org :mag_right: | Description -| --- | --- | --- | --- | -| `work-in-progress` | [search][search-atom-repo-label-work-in-progress] | [search][search-atom-org-label-work-in-progress] | Pull requests which are still being worked on, more changes will follow. | -| `needs-review` | [search][search-atom-repo-label-needs-review] | [search][search-atom-org-label-needs-review] | Pull requests which need code review, and approval from maintainers or Atom core team. | -| `under-review` | [search][search-atom-repo-label-under-review] | [search][search-atom-org-label-under-review] | Pull requests being reviewed by maintainers or Atom core team. | -| `requires-changes` | [search][search-atom-repo-label-requires-changes] | [search][search-atom-org-label-requires-changes] | Pull requests which need to be updated based on review comments and then reviewed again. | -| `needs-testing` | [search][search-atom-repo-label-needs-testing] | [search][search-atom-org-label-needs-testing] | Pull requests which need manual testing. | +| 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.md b/README.md index 5dfa7cec5..f45671266 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,8 @@ The current codebase is expected to build and run on the 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. ## Running ns-3 @@ -86,7 +86,7 @@ The program source can be found in the examples/routing directory. 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/. @@ -94,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 @@ -102,7 +102,7 @@ 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 @@ -110,7 +110,7 @@ This documentation includes: 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 [doc/mercurial.txt](doc/git.txt) but reading through the git +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. From 3329e8737b2f1c590a9339f1af67df90f7d717e0 Mon Sep 17 00:00:00 2001 From: Natale Patriciello Date: Mon, 17 Dec 2018 11:31:19 +0100 Subject: [PATCH 9/9] doc: finished last things --- CONTRIBUTING.md | 5 ++--- doc/manual/source/working-with-git.rst | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7dbffc5f2..db70750e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,9 +153,8 @@ The process described here has several goals: Please follow these steps to have your contribution considered by the maintainers: -1. Follow all instructions in [the template](doc/MERGE_REQUEST_TEMPLATE.md) -2. Follow the [styleguides](#styleguides) -3. 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.
+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. diff --git a/doc/manual/source/working-with-git.rst b/doc/manual/source/working-with-git.rst index 30c098e3d..53c95fd61 100644 --- a/doc/manual/source/working-with-git.rst +++ b/doc/manual/source/working-with-git.rst @@ -54,7 +54,7 @@ Assume that you are the user *john* on GitLab.com and that you want to create a #. 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). +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.