Developer FAQ - Revision history

Tomh at 18:14, 19 April 2022

2022-04-19T18:14:09Z

← Older revision		Revision as of 18:14, 19 April 2022
Line 2:		Line 2:

	This FAQ is for developers who have accounts on the server code.nsnam.org, and for maintainers.		This FAQ is for developers who have accounts on the server code.nsnam.org, and for maintainers.

			'''Warning to readers:''' This info is really out of date and should be cleaned up/cleaned out. In the meantime, please review the Sphinx documentation maintained here, especially the contributing guide: https://www.nsnam.org/documentation/development-tree/

	== New accounts on code.nsnam.org ==		== New accounts on code.nsnam.org ==

			'''Node:''' code.nsnam.org is now legacy Mercurial server-- current users should use Gitlab.com.

	In general, we are restricting new accounts on code.nsnam.org to maintainers who need commit access to the main repositories. Going forward, we encourage other developers who want to host or stage code to use hosted services such as https://github.com (git) or https://bitbucket.org (mercurial).		In general, we are restricting new accounts on code.nsnam.org to maintainers who need commit access to the main repositories. Going forward, we encourage other developers who want to host or stage code to use hosted services such as https://github.com (git) or https://bitbucket.org (mercurial).
Line 52:		Line 56:

	== The WAF build system ==		== The WAF build system ==

			'''Note:''' Waf was removed in favor of CMake in release 3.36.

	See also the [http://www.nsnam.org/wiki/index.php/User_FAQ#WAF_.28new_build_process.29 Waf User FAQ].		See also the [http://www.nsnam.org/wiki/index.php/User_FAQ#WAF_.28new_build_process.29 Waf User FAQ].

Line 119:		Line 126:
	== Generating new python bindings ==		== Generating new python bindings ==

	See the [~~http~~://www.nsnam.org/~~wiki~~/~~index~~.~~php/NS-3_Python_Bindings~~ ns-3 python ~~wiki page~~].		See the [https://www.nsnam.org/docs/manual/html/python.html ns-3 python documentation].

	== Release Process ==		== Release Process ==

Tomh: /* Using gcov and lcov code coverage tools */

2017-10-10T13:21:29Z

Using gcov and lcov code coverage tools

← Older revision		Revision as of 13:21, 10 October 2017
Line 424:		Line 424:

	A custom version of lcov and its associated tools (geninfo, genhtml) is stored in the directory utils/lcov/, and this is the version that waf uses to run lcov. As of ns-3.13, the version of lcov in ns-3 is lcov-1.9, with geninfo patched to deal with [http://old.nabble.com/-Ltp-coverage--lcov-hangs-td28514226.html this branching bug].		A custom version of lcov and its associated tools (geninfo, genhtml) is stored in the directory utils/lcov/, and this is the version that waf uses to run lcov. As of ns-3.13, the version of lcov in ns-3 is lcov-1.9, with geninfo patched to deal with [http://old.nabble.com/-Ltp-coverage--lcov-hangs-td28514226.html this branching bug].

			* '''Note (Oct. 10, 2017):''' Please see https://www.nsnam.org/bugzilla/show_bug.cgi?id=2799 about recent problems with running lcov-report through Waf; you may be better to run lcov directly on the coverage files, as described in the bug report.

	You probably also need to have a version of lcovrc file installed somewhere (either at /etc/lcovrc or ~/.lcovrc). The easiest way to do this is to install lcov from your package manager; e.g.		You probably also need to have a version of lcovrc file installed somewhere (either at /etc/lcovrc or ~/.lcovrc). The easiest way to do this is to install lcov from your package manager; e.g.

Tomh: /* Checking in code */

2016-10-18T14:19:21Z

Checking in code

← Older revision		Revision as of 14:19, 18 October 2016
Line 243:		Line 243:
	Subscribe to ns-bugs mailing list, if you haven't already, so that you get the bug tracker notifications.		Subscribe to ns-bugs mailing list, if you haven't already, so that you get the bug tracker notifications.

	Please maintain a valid .hgrc in your home directory so that the proper username can be added to your commits.		Please maintain a valid .hgrc in your home directory so that the proper username can be added to your commits. Here is an example of a minimal one that provides a username for commit messages:

	[ui]		[ui]
	username = John Doe <john.doe@example.com>		username = John Doe <john.doe@example.com>

	Please always update your code to the tip of ns-3-dev before checking in. Never force a push (which creates another head on the repository); actually, ~~this~~ is now disabled on the server and the push will fail. If someone else pushed something before you got a chance to perform your push, you will need to pull those changes, resolve any possible conflicts, merge, and then push. Also don't push with "--new-branch" ([http://mailman.isi.edu/pipermail/ns-developers/2013-May/011169.html the use of ''named branches'' is not allowed]).		Please always update your code to the tip of ns-3-dev before checking in. Never force a push (which creates another head on the repository); actually, creating multiple heads is now disabled on the server and the push will fail. If someone else pushed something before you got a chance to perform your push, you will need to pull those changes, resolve any possible conflicts, merge, and then push. Also don't push with "--new-branch" ([http://mailman.isi.edu/pipermail/ns-developers/2013-May/011169.html the use of ''named branches'' is not allowed]).

	Before checking in code, it is good practice to pull from ns-3-dev and deal with any merge issues in advance:		Before checking in code, it is good practice to pull from ns-3-dev and deal with any merge issues in advance:
Line 259:		Line 259:
	./test.py		./test.py

	Depending on the intrusiveness and nature of your patch, you may want to go further with your testing, including testing debug, optimized, and static versions, and running test.py with the -g option for valgrind.		Depending on the intrusiveness and nature of your patch, you may want to go further with your testing, including testing debug, optimized, and static versions, generating new python bindings, and running test.py with the -g option for valgrind.

	When you are ready to push upstream, it is good practice to review the outgoing changesets. This can be done with the following command:		When you are ready to push upstream, it is good practice to review the outgoing changesets. This can be done with the following command:
Line 308:		Line 308:
	If you as a maintainer check in a patch authored by someone else, it is good practice to credit them in the commit message using the --user or -u option to hg; e.g.:		If you as a maintainer check in a patch authored by someone else, it is good practice to credit them in the commit message using the --user or -u option to hg; e.g.:

	hg commit -m"...commit message..." -u"A User <a.user@example.com>"		hg commit -m"...commit message..." -u"Another User <another.user@example.com>"

	You can sometimes find the appropriate user string by searching the hg log for their previous commits; e.g.		You can sometimes find the appropriate user string by searching the hg log for their previous commits; e.g.
Line 316:		Line 316:
	Reference: http://www.gnu.org/prep/maintain/html_node/Recording-Contributors.html		Reference: http://www.gnu.org/prep/maintain/html_node/Recording-Contributors.html

	If the author of the patch is a first-time author, please ask in private email beforehand whether he or she is comfortable with the commit string (name and email address) that you choose.		If the author of the patch is a first-time author, please ask in private email beforehand whether he or she is comfortable with the commit string (name and email address) that you choose. The reason is that people may want a specific email address (e.g. a non-work address, or a work address) to exist in the commit string.

	=== Checking that you don't introduce regressions or leaks ===		=== Checking that you don't introduce regressions or leaks ===

	~~just before~~ you do a checkin you should run the ns-3 tests. Make sure that you have valgrind installed, and change into the top level directory and type		Before you do a checkin that is somewhat intrusive, you should run the ns-3 tests. Make sure that you have valgrind installed, and change into the top level directory and type

	./test.py -g		./test.py -g
Line 329:		Line 329:

	Sometimes you will commit something that will fail on another regression buildslave (e.g. clang raises a warning that gcc does not). If you have access to both clang and gcc, it is good to check beforehand; if not, don't worry, another maintainer will try to clean it.		Sometimes you will commit something that will fail on another regression buildslave (e.g. clang raises a warning that gcc does not). If you have access to both clang and gcc, it is good to check beforehand; if not, don't worry, another maintainer will try to clean it.

			=== Updating python bindings ===

			Python bindings are kept loosely synchronized with ns-3-dev. Additions to the public API do not require a bindings rescan immediately; they should not break the build. Changes to the public API, however, will typically break the bindings compilation.

			We tend to prefer to keep the bindings update in a separate changeset, to make the C++ changes more readable in the codebase. That is, if you introduce a C++ API change in one changeset, commit it first, and then do the Python rescan and commit any changed bindings as a separate commit.

			At the moment (Oct. 2016), the bindings scanning process is limited to gcc-4 machines (there is an open bug on moving this over to CastXML). If this is a problem for you (i.e. your commit breaks the bindings but you don't have an easy facility to regenerate them), coordinate with Tom or Tommaso about the rescanning.

	=== Commit message formatting ===		=== Commit message formatting ===
Line 405:		Line 413:
	* check in the bug fix to ns-3-dev with a commit message that indicates the bug number, such as "bug 903: TapBridge doesn't close cleanly". If the patch was created by a user, you can use their name and email in the mercurial commit userstring.		* check in the bug fix to ns-3-dev with a commit message that indicates the bug number, such as "bug 903: TapBridge doesn't close cleanly". If the patch was created by a user, you can use their name and email in the mercurial commit userstring.

	* remember what the changeset number is; e.g.		* remember what the changeset number is; Mercurial provides both a local sequential integer, and a global hexadecimal value; e.g.

	changeset: 1763:4624d5aba98f		changeset: 1763:4624d5aba98f
	~~^^^^^^^^^^^^~~
	~~it is this hexadecimal value~~

	* mark the bug as "Resolved, Fixed" in Bugzilla, with a comment such as "fixed in changset 4624d5aba98f", or "fixed in changeset 1763:4624d5aba98f". Bugzilla will notify the ns-bugs mailing list of the fix, and the ns-commits list will be notified of the checkin.		* mark the bug as "Resolved, Fixed" in Bugzilla, with a comment such as "fixed in changset 4624d5aba98f", or "fixed in changeset 1763:4624d5aba98f". Bugzilla will notify the ns-bugs mailing list of the fix, and the ns-commits list will be notified of the checkin.

Tomh: /* merging vs. rebasing */

2016-05-10T19:24:10Z

merging vs. rebasing

← Older revision		Revision as of 19:24, 10 May 2016
Line 285:		Line 285:
	Mercurial does not have a native [https://git-scm.com/docs/git-rebase rebase feature] like git (or if it does, we do not use it). As a result, you can be working on some code for commit to ns-3-dev, get it all ready to push, and find that the tip of <code>ns-3-dev</code> has evolved since you forked. So you cannot push immediately; you would create two heads (which is forbidden). What to do?		Mercurial does not have a native [https://git-scm.com/docs/git-rebase rebase feature] like git (or if it does, we do not use it). As a result, you can be working on some code for commit to ns-3-dev, get it all ready to push, and find that the tip of <code>ns-3-dev</code> has evolved since you forked. So you cannot push immediately; you would create two heads (which is forbidden). What to do?

	# (preferred): Manually rebase on the latest ns-3-dev. That is, export your changeset or changesets to patch files, checkout a fresh ns-3-dev, and try to import (or patch and merge) your changesets. This tends to keep the mainline tree history very linear, which helps future maintainers.		# (preferred): Manually rebase on the latest ns-3-dev. That is, export your changeset or changesets to patch files, checkout a fresh ns-3-dev, and try to import (or patch and merge) your changesets. This tends to keep the mainline tree history very linear, which helps future maintainers. This can be very simple if you are trying to push just one changeset. Let's assume that you committed one patch and have one outgoing changeset (<code>hg outgoing -v</code> shows one changeset). You can try:
			## <code> hg export tip > my-changeset.patch</code> (this extracts your changeset with commit string intact)
			## <code> hg rollback</code> (this undoes the last commit
			## <code> hg pull -u</code> (this syncs your ns-3-dev to code.nsnam.org)
			## <code> hg import my-changeset.patch</code> (this reapplies your patch on top of the tip)
			## <code> hg outgoing -v</code> (everything look OK still?)
			## <code> hg push ssh://code@code.nsnam.org/repos/ns-3-dev</code> (should work now)
	# (alternative): Merge and resolve. That is, perform a 'hg pull -u' onto your local copy (with outgoing changesets), and one of two things will happen.		# (alternative): Merge and resolve. That is, perform a 'hg pull -u' onto your local copy (with outgoing changesets), and one of two things will happen.
	## ''simply merge heads.'' If the new changesets are orthogonal to yours, update will succeed, and you'll have to do a <code>hg commit -m"merge heads"</code> commit to merge the two heads into one. Then, you can try to <code>hg push</code> again.		## ''simply merge heads.'' If the new changesets are orthogonal to yours, update will succeed, and you'll have to do a <code>hg commit -m"merge heads"</code> commit to merge the two heads into one. Then, you can try to <code>hg push</code> again.

Tomh: /* Checking in code */

2016-05-10T19:19:53Z

Checking in code

← Older revision		Revision as of 19:19, 10 May 2016
Line 236:		Line 236:

	== Checking in code ==		== Checking in code ==

			This is mainly for maintainers who want to commit their code, or patches from others, to <code>ns-3-dev</code> or other mainline repositories.

	=== General guidelines ===		=== General guidelines ===

			Subscribe to ns-bugs mailing list, if you haven't already, so that you get the bug tracker notifications.

	Please maintain a valid .hgrc in your home directory so that the proper username can be added to your commits.		Please maintain a valid .hgrc in your home directory so that the proper username can be added to your commits.
Line 276:		Line 280:

	hg commit -m "bug 1365: unused variable declaration of a private data member"		hg commit -m "bug 1365: unused variable declaration of a private data member"

			=== merging vs. rebasing ===

			Mercurial does not have a native [https://git-scm.com/docs/git-rebase rebase feature] like git (or if it does, we do not use it). As a result, you can be working on some code for commit to ns-3-dev, get it all ready to push, and find that the tip of <code>ns-3-dev</code> has evolved since you forked. So you cannot push immediately; you would create two heads (which is forbidden). What to do?

			# (preferred): Manually rebase on the latest ns-3-dev. That is, export your changeset or changesets to patch files, checkout a fresh ns-3-dev, and try to import (or patch and merge) your changesets. This tends to keep the mainline tree history very linear, which helps future maintainers.
			# (alternative): Merge and resolve. That is, perform a 'hg pull -u' onto your local copy (with outgoing changesets), and one of two things will happen.
			## ''simply merge heads.'' If the new changesets are orthogonal to yours, update will succeed, and you'll have to do a <code>hg commit -m"merge heads"</code> commit to merge the two heads into one. Then, you can try to <code>hg push</code> again.
			## ''resolve conflicts and merge.'' If the update fails, you will have to work through the merge conflicts and commit the changes, merging also the two heads. This can be messy.

	=== When to commit ===		=== When to commit ===
Line 281:		Line 294:
	When is it OK to commit code (from a bugzilla patch, or from a code review)?		When is it OK to commit code (from a bugzilla patch, or from a code review)?
	* If you are the maintainer of an existing module, you can commit changes when you want, as long as you coordinate with the release manager (if it is close to a release or code freeze date).		* If you are the maintainer of an existing module, you can commit changes when you want, as long as you coordinate with the release manager (if it is close to a release or code freeze date).
	* If you are not the maintainer, please obtain +1 from the maintainer if the change is not trivial. You may have to remind him or her about it; if you do not get a response, email the release manager.		* If you are not the maintainer (e.g. your patch touches other modules too), please obtain +1 from the maintainer if the change is not trivial. You may have to remind him or her about it; if you do not get a response, email the release manager.
	* If you would like to add a new module, or to commit to a module that does not have a maintainer, it usually should have some review by core maintainers. Email the release manager for help.		* If you would like to add a new module, or to commit to a module that does not have a maintainer, it usually should have some review by core maintainers. Email the release manager for help.
	* When in doubt, email the release manager.		* When in doubt, email the release manager.
Line 296:		Line 309:

	Reference: http://www.gnu.org/prep/maintain/html_node/Recording-Contributors.html		Reference: http://www.gnu.org/prep/maintain/html_node/Recording-Contributors.html

			If the author of the patch is a first-time author, please ask in private email beforehand whether he or she is comfortable with the commit string (name and email address) that you choose.

	=== Checking that you don't introduce regressions or leaks ===		=== Checking that you don't introduce regressions or leaks ===
Line 306:		Line 321:

	FAIL: TestSuite test-tcp-large-transfer		FAIL: TestSuite test-tcp-large-transfer

			Sometimes you will commit something that will fail on another regression buildslave (e.g. clang raises a warning that gcc does not). If you have access to both clang and gcc, it is good to check beforehand; if not, don't worry, another maintainer will try to clean it.

	=== Commit message formatting ===		=== Commit message formatting ===

Tomh: /* General mercurial tips */

2016-05-10T19:07:38Z

General mercurial tips

← Older revision		Revision as of 19:07, 10 May 2016
Line 27:		Line 27:
	## <code>hg revert</code>: This can be used to revert the repository to a previous revision number. For example, to revert to changeset number #1000, type <code>hg revert -r 1000 --all</code>. This does '''not''' remove your checkin from the repository history. For example, if your mistaken checkin was number 1001, and you revert back to 1000 and then commit, you will be at changeset number 1002 now even though the code matches what was in there at changeset 1000.		## <code>hg revert</code>: This can be used to revert the repository to a previous revision number. For example, to revert to changeset number #1000, type <code>hg revert -r 1000 --all</code>. This does '''not''' remove your checkin from the repository history. For example, if your mistaken checkin was number 1001, and you revert back to 1000 and then commit, you will be at changeset number 1002 now even though the code matches what was in there at changeset 1000.
	## <code>hg rollback</code>: This can be used to completely wipe clean the last transaction only (commit, import, push, pull). Use with care-- cannot be undone.		## <code>hg rollback</code>: This can be used to completely wipe clean the last transaction only (commit, import, push, pull). Use with care-- cannot be undone.
	# '''How to restore repository to the tip'': Sometimes you want to just clean the repository of your local changes, to restore back to the last tip of the repository. This can be done globally or file-by-file.		# '''How to restore repository to the tip''': Sometimes you want to just clean the repository of your local changes, to restore back to the last tip of the repository. This can be done globally or file-by-file.
	## Globally: <code>hg update -C</code> (will ~~remove~~ _all_ ~~local changes~~)		## Globally: <code>hg update -C</code> (will restore _all_ tracked files to the last committed version; will leave untracked files untouched)
	## Per-file: <code>hg revert <filename></code> (replace 'filename' with the path to the file of interest.		## Per-file: <code>hg revert filename</code> (replace 'filename' with the path to the file of interest).
	# '''How to rename a file''': <code>hg rename old-file-name new-file-name</code> This is preferable to adding the new file name and removing the old file name, because it preserves revision history. Don't forget to commit after a rename once you are done.		# '''How to rename a file''': <code>hg rename old-file-name new-file-name</code> This is preferable to adding the new file name and removing the old file name, because it preserves revision history. Don't forget to commit after a rename once you are done.
	# '''How to merge a branch''': If you have forked a branch repository, have worked on it, and are ready to merge it back to ns-3-dev, here are the steps to take (Also, read [http://hgbook.red-bean.com/hgbookch3.html this chapter] to better understand how the mercurial source tree is structured when merging is occurring):		# '''How to merge a branch''': If you have forked a branch repository, have worked on it, and are ready to merge it back to ns-3-dev, here are the steps to take (Also, read [http://hgbook.red-bean.com/hgbookch3.html this chapter] to better understand how the mercurial source tree is structured when merging is occurring):

Tomh at 19:05, 10 May 2016

2016-05-10T19:05:54Z

← Older revision		Revision as of 19:05, 10 May 2016
Line 22:		Line 22:
	## check that the <code>Description</code> and <code>Contact</code> fields for this new repository are correct by browsing http://code.nsnam.org		## check that the <code>Description</code> and <code>Contact</code> fields for this new repository are correct by browsing http://code.nsnam.org

	==~~= Mercurial~~ tips ===		== General mercurial tips ==

	# '''How to undo a commit''': Let's suppose you are working on a private repository and you check something in, but some other files were inadvertently checked in, and you want to revert and start over. There are two ways to do this:		# '''How to undo a commit''': Let's suppose you are working on a private repository and you check something in, but some other files were inadvertently checked in, and you want to revert and start over. There are two ways to do this:
	## <code>hg revert</code>: This can be used to revert the repository to a previous revision number. For example, to revert to changeset number #1000, type <code>hg revert -r 1000 --all</code>. This does '''not''' remove your checkin from the repository history. For example, if your mistaken checkin was number 1001, and you revert back to 1000 and then commit, you will be at changeset number 1002 now even though the code matches what was in there at changeset 1000.		## <code>hg revert</code>: This can be used to revert the repository to a previous revision number. For example, to revert to changeset number #1000, type <code>hg revert -r 1000 --all</code>. This does '''not''' remove your checkin from the repository history. For example, if your mistaken checkin was number 1001, and you revert back to 1000 and then commit, you will be at changeset number 1002 now even though the code matches what was in there at changeset 1000.
	## <code>hg rollback</code>: This can be used to completely wipe clean the last transaction only (commit, import, push, pull). Use with care-- cannot be undone.		## <code>hg rollback</code>: This can be used to completely wipe clean the last transaction only (commit, import, push, pull). Use with care-- cannot be undone.
	# '''How to rename a file''': <code>hg rename old-file-name new-file-name</code> This is preferable to adding the new file name and removing the old file name, because it preserves revision history. Don't forget to commit once you are done.		# '''How to restore repository to the tip'': Sometimes you want to just clean the repository of your local changes, to restore back to the last tip of the repository. This can be done globally or file-by-file.
			## Globally: <code>hg update -C</code> (will remove _all_ local changes)
			## Per-file: <code>hg revert <filename></code> (replace 'filename' with the path to the file of interest.
			# '''How to rename a file''': <code>hg rename old-file-name new-file-name</code> This is preferable to adding the new file name and removing the old file name, because it preserves revision history. Don't forget to commit after a rename once you are done.
	# '''How to merge a branch''': If you have forked a branch repository, have worked on it, and are ready to merge it back to ns-3-dev, here are the steps to take (Also, read [http://hgbook.red-bean.com/hgbookch3.html this chapter] to better understand how the mercurial source tree is structured when merging is occurring):		# '''How to merge a branch''': If you have forked a branch repository, have worked on it, and are ready to merge it back to ns-3-dev, here are the steps to take (Also, read [http://hgbook.red-bean.com/hgbookch3.html this chapter] to better understand how the mercurial source tree is structured when merging is occurring):
	##''cd into your branch''		##''cd into your branch''

Tomh at 19:01, 10 May 2016

2016-05-10T19:01:54Z

← Older revision		Revision as of 19:01, 10 May 2016
Line 1:		Line 1:
	{{TOC}}		{{TOC}}

	== Mercurial repository layout for ~~developers~~ ==		This FAQ is for developers who have accounts on the server code.nsnam.org, and for maintainers.

			== New accounts on code.nsnam.org ==

			In general, we are restricting new accounts on code.nsnam.org to maintainers who need commit access to the main repositories. Going forward, we encourage other developers who want to host or stage code to use hosted services such as https://github.com (git) or https://bitbucket.org (mercurial).

			== Mercurial repository layout for code.nsnam.org ==

			These instructions pertain to users of code.nsnam.org who wish to host private repositories such as http://code.nsnam.org/tomh/ns-3-simple-wireless.

	# In your home dir on code.nsnam.org, you will find a new directory named "<code>repositories/username</code>". e.g.: <code>/home/tomh/repositories/tomh</code>. If you create a repository in this directory, it will appear automatically on http://code.nsnam.org		# In your home dir on code.nsnam.org, you will find a new directory named "<code>repositories/username</code>". e.g.: <code>/home/tomh/repositories/tomh</code>. If you create a repository in this directory, it will appear automatically on http://code.nsnam.org
	~~#* Note: To enable this for new users, edit /var/www/cgi-hg/hgweb.config~~		# You can ssh and rsync to your personal account and manage these repositories
	# You can ~~obviously~~ ssh to your personal account and manage these repositories		# You can push to these repositories with the command such as: <code>hg push ssh://tomh@code.nsnam.org/repositories/tomh/ns-3-simple-wireless</code>
	# You can push to these repositories with the command: <code>hg push ssh://tomh@code.nsnam.org/repositories/tomh/ns-3-~~com~~</code>		# You can pull with the usual commands: <code>hg clone http://code.nsnam.org/tomh/ns-3-simple-wireless</code>
	# You can pull with the usual commands: <code>hg clone http://code.nsnam.org/tomh/ns-3-~~com~~</code>		# If you want to have shared non-mainline repositories (e.g. the 'laa' or 'dcf' users), we can create a user by that name and add multiple public keys to that account.
	# If you want to ~~allow another user to push into your repository, all you~~ have ~~to do is change the unix permissions of your repository to allow this user write permissions~~. ~~This means that if you want to give everyone write permissions, you can "<code>chmod -R~~ g ~~+rw /home/tomh/repositories/tomh/ns-3-com/</code>"~~. ~~If you want to allow only a smaller subset of~~ users ~~to push~~, we ~~will need~~ to ~~create unix group which matches this subset~~
	# The push command for the main tree is still: <code>hg push ssh://code@code.nsnam.org/repos/ns-3-dev</code>		# The push command for the main tree is still: <code>hg push ssh://code@code.nsnam.org/repos/ns-3-dev</code>
	# '''New developers, please read this:''' When creating a new repository, do not "hg clone" it into your directory on code.nsnam.org (which will generate a big ns-commits mail message); instead, just copy (cp -r) or rsync it to your local "/home/username/repositories/username" directory.		# '''New developers on code.nsnam.org, please read this:''' When creating a new repository, do not "hg clone" it into your repositories directory on code.nsnam.org (which will generate a big ns-commits mail message); instead, just copy (cp -r) or rsync it to your local "/home/username/repositories/username" directory. Recommended steps:
			## <code>cp -rp /home/code/repos/ns-3-dev /path/to/my/repositories/ns-3-feature-name</code>
			## edit the .hgrc file in your new <code>ns-3-feature-name</code> repository
			## check that the <code>Description</code> and <code>Contact</code> fields for this new repository are correct by browsing http://code.nsnam.org

	=== Mercurial tips ===		=== Mercurial tips ===

Tomh: /* Checking in code */

2016-02-01T22:21:06Z

Checking in code

← Older revision		Revision as of 22:21, 1 February 2016
Line 293:		Line 293:

	FAIL: TestSuite test-tcp-large-transfer		FAIL: TestSuite test-tcp-large-transfer

			=== Commit message formatting ===

			Going forward, we prefer to follow the conventions adapted from http://chris.beams.io/posts/git-commit/

			# Separate subject from body with a blank line
			# Limit the subject line to 60 characters
			# Capitalize the subject line
			# Do not end the subject line with a period
			# Use the imperative mood in the subject line
			# Wrap the body at 72 characters
			# Use the body to explain what and why vs. how

			For the subject line, if the module name and bug number can be succinctly included, they may preface the subject string. The module name is lowercase as per the directory name, followed by a colon. If the commit closes a bug, it may parenthetically mention that bug, and use the '#' character. If it purely affects documentation or logging in a module, it can have '(documentation)' added. Documentation, logging, and doxygen-only commits outside of a module may be identified with 'documentation:' tag, and the build system with 'waf:' Examples:

			sixlowpan: (fixes #2272) Allow NetDevice to send packets larger than MTU

			sixlowpan: (documentation) Complete doxygen on input/output parameters

			documentation: Update RELEASE_NOTES and CHANGES.html

			waf: Update Waf to 1.8.12

			If the subject doesn't fit neatly into one of these categories, use your judgement within the 60 character limit.

			Here is an example with both subject and body:

			<pre>
			Summarize changes in around 60 characters or less

			More detailed explanatory text, if necessary. Wrap it to about 72
			characters or so. In some contexts, the first line is treated as the
			subject of the commit and the rest of the text as the body. The
			blank line separating the summary from the body is critical (unless
			you omit the body entirely); various tools like `log`, `shortlog`
			and `rebase` can get confused if you run the two together.

			Explain the problem that this commit is solving. Focus on why you
			are making this change as opposed to how (the code explains that).
			Are there side effects or other unintuitive consequences of this
			change? Here's the place to explain them.

			Further paragraphs come after blank lines.

			- Bullet points are okay, too

			- Typically a hyphen or asterisk is used for the bullet, preceded
			by a single space, with blank lines in between, but conventions
			vary here

			If you use an issue tracker, put references to them at the bottom,
			like this:

			Resolves: #123
			See also: #456, #789
			</pre>

	=== Logging your changes in the release notes ===		=== Logging your changes in the release notes ===

Tomh: /* Checking in code */

2015-02-06T18:39:55Z

Checking in code

← Older revision		Revision as of 18:39, 6 February 2015
Line 226:		Line 226:
	=== General guidelines ===		=== General guidelines ===

	Please always update your code to the tip of ns-3-dev before checking in. Never force a push (which creates another head on the repository). If someone else pushed something before you got a chance to perform your push, you will need to pull those changes, resolve any possible conflicts, and then push. Also don't push with "--new-branch" ([http://mailman.isi.edu/pipermail/ns-developers/2013-May/011169.html the use of ''named branches'' is not allowed]).		Please maintain a valid .hgrc in your home directory so that the proper username can be added to your commits.

			[ui]
			username = John Doe <john.doe@example.com>

			Please always update your code to the tip of ns-3-dev before checking in. Never force a push (which creates another head on the repository); actually, this is now disabled on the server and the push will fail. If someone else pushed something before you got a chance to perform your push, you will need to pull those changes, resolve any possible conflicts, merge, and then push. Also don't push with "--new-branch" ([http://mailman.isi.edu/pipermail/ns-developers/2013-May/011169.html the use of ''named branches'' is not allowed]).

	Before checking in code, it is good practice to pull from ns-3-dev and deal with any merge issues in advance:		Before checking in code, it is good practice to pull from ns-3-dev and deal with any merge issues in advance:
Line 239:		Line 244:
	Depending on the intrusiveness and nature of your patch, you may want to go further with your testing, including testing debug, optimized, and static versions, and running test.py with the -g option for valgrind.		Depending on the intrusiveness and nature of your patch, you may want to go further with your testing, including testing debug, optimized, and static versions, and running test.py with the -g option for valgrind.

	When you are ready to push upstream, the command to check in code is:		When you are ready to push upstream, it is good practice to review the outgoing changesets. This can be done with the following command:

			hg outgoing -v

			If this looks good, the command to check in code is:

	hg push ssh://code@code.nsnam.org/repos/ns-3-dev		hg push ssh://code@code.nsnam.org/repos/ns-3-dev
Line 279:		Line 288:
	just before you do a checkin you should run the ns-3 tests. Make sure that you have valgrind installed, and change into the top level directory and type		just before you do a checkin you should run the ns-3 tests. Make sure that you have valgrind installed, and change into the top level directory and type

	./test.py -~~-grind~~		./test.py -g

	If you do this, you will see a bunch of passing tests and then, if something goes wrong:		If you do this, you will see a bunch of passing tests and then, if something goes wrong:
Line 302:		Line 311:
	A. The typical thing to do is:		A. The typical thing to do is:

	* check in the bug fix to ns-3-dev with a commit message that indicates the bug number, such as "bug 903: TapBridge doesn't close cleanly"		* check in the bug fix to ns-3-dev with a commit message that indicates the bug number, such as "bug 903: TapBridge doesn't close cleanly". If the patch was created by a user, you can use their name and email in the mercurial commit userstring.

	* remember what the changeset number is; e.g.		* remember what the changeset number is; e.g.
Line 310:		Line 319:
	it is this hexadecimal value		it is this hexadecimal value

	* mark the bug as "Resolved, Fixed" in Bugzilla, with a comment such as "fixed in changset 4624d5aba98f". Bugzilla will notify the ns-bugs mailing list of the fix, and the ns-commits list will be notified of the checkin.		* mark the bug as "Resolved, Fixed" in Bugzilla, with a comment such as "fixed in changset 4624d5aba98f", or "fixed in changeset 1763:4624d5aba98f". Bugzilla will notify the ns-bugs mailing list of the fix, and the ns-commits list will be notified of the checkin.

	== Using gcov and lcov code coverage tools ==		== Using gcov and lcov code coverage tools ==