interface on GitLab.com), clone your fork of ns-3-dev to your local machine,
create a new feature branch that is based on the
current tip of ns-3-dev, push that new feature branch up to your fork,
and then from the GitLab.com user interface, generate a Merge Request back
to the |ns3| mainline. You will want to monitor and respond to any
comments from reviewers, and try to resolve threads.
Remember the documentation
==========================
If you add or change API to the simulator, please include `Doxygen <https://www.doxygen.nl>`_ changes as appropriate. Please scan the module documentation
(written in `Restructured Text <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ in the `docs` directory) to check if an update is needed to align with the patch proposal.
Commit messages should be written as follows. For examples, please look
at the output of `git log` command.
1. The author string should be formatted such as "John Doe <john.doe@example.com>". It is a good idea to run
`git config <https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration>`_ on your machine, or hand-edit the `.gitconfig` file in your home directory,
to ensure that your name and email are how you want them to be displayed.
..raw:: latex
\newpage
2. The first line of the commit message should be limited to 72 columns if possible. This is not a hard requirement but a preference. If you prefer to add
more detail, you can add subsequent message lines below the first one, separated by a blank line. Example:
In the course of developing and responding to review comments, you may
add more commits, so what started out as a single commit might grow into
several. Please consider to squash any such revisions if they do not
need to be preserved as separate commits in the mainline Git history.
If you squash commits, you must force-push your branch back to your fork.
Do not worry about this; GitLab.com will update the Merge Request
automatically. This `tutorial <https://docs.gitlab.com/ee/topics/git/git_rebase.html>`_ may be helpful to learn about Git rebase, force-push, and merge
conflicts.
Note that GitLab can squash the commits while merging. However, it is often
preferred to keep multiple commit messages, especially when the merge request
contains multiple parts or multiple authors.
It is a good practice to NOT squash commits while the merge request is being
reviewed and updated (this helps the reviewers), and perform a selective
squash before the merge.
Rebasing on ns-3-dev
====================
It is also helpful to maintainers to keep your feature branch up to date
so that the commits are appended to the tip of the mainline code. This
is not strictly required; maintainers may do such a rebase upon merging
your finalized Merge Request. This may help catch possible merge conflicts
before the time to merge arrives.
Note that sometimes it is not possible to rebase a merge request through
GitLab's web interface. Hence, it is a good practice to keep your merge
request in line with the mainline (i.e., rebase it periodically and push
the updated branch).
Resolving discussion threads
============================
Any time someone opens a new comment thread on a Merge Request, a counter
of 'Unresolved threads' is incremented (near the top of the Merge Request).
If you are able to successfully resolve the comment thread (either by
changing your code, or convincing the reviewer that no change is needed),
then please mark the thread as resolved. Maintainers will look at the
count of unresolved threads and make decisions based on this count as to
whether the Merge Request is ready. Maintainers prefer that all threads
are resolved successfully before moving forward with a merge.
Adding a label
==============
You can use labels to indicate whether the Merge Request is a bug, pertains
to a specific module or modules, is documentation related, etc. This is
not required; if you do not add a label, a maintainer probably will.
Other metadata
==============
It is not necessary to set other metadata on the Merge Request such as
milestone, reviewers, etc.
Feature requests
****************
Feature requests are tracked as `GitLab.com issues <https://gitlab.com/nsnam/ns-3-dev/-/issues>`_. If you want to suggest an enhancement, create an issue and provide the following information:
1. Use a clear and descriptive title for the issue to identify the suggestion.
2. Provide a step-by-step description of the suggested enhancement in as many details as possible.
3. Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples.
4. Describe the current behavior and explain which behavior you expected to see instead and why.
5. Explain why this enhancement would be useful to most ns-3 users.
The |ns3| project does not have professional developers available to respond
to feature requests, so your best bet is to try to implement it yourself and
work with maintainers to improve it, but the project does like to hear back
from users about what would be a useful improvement, and you may find
like-minded collaborators in the community willing to work on it with you.
Use the `enhancement` Label on your feature request.
