Commit Guidelines

From nsnam
Jump to: navigation, search

This page summarizes the commit guidelines for ns and related software.

General Hints

Important: When committing binary files to CVS, please don't forget to set the binary flag (cvs add -kb <files>). This has never been an issue with Unix-only development, but especially when committing binary traces.Z for the regression suite without the binary flag set, this will surely break the validation at least under Windows!

Bug fixes

Before committing, the developer must:

  • verify that the test suites still pass on your platform

Before commiting changes to ns, you should always run the validation test suites (run "./validate" in the top-level ns directory). Since ns is a large and complex piece of software it's critical to locate bugs early. This requirement applies to even "obviously correct" one-line changes. All too frequently there's a minor error that slips through and someone else has to fix it.

  • use a meaningful CVS commit message Commit text is important to help determine what changes do. Things like "bug fix" are not meaningful, while "fix TCP retransmit after timeout" is better. If you are committing several changes that affect several directories, commit changes one directory at a time, so that you will be prompted for a different message for each directory.
  • update CHANGES.html for medium-size or larger changes

NS and nam both have a CHANGES.html file. Please record "medium-sized" (or larger) changes in this file. What is a medium-sized change? A judgement call. Simple bug fixes aren't (the Makefile had an extra .o in OBJS and was breaking, I fixed it). Larger bug fixes are (the tahoe TCP module produced wrong results in a particular case). New features certainly are (multicast code is now present). If in doubt, ask someone.

New modules

New protocols or features can be added to ns-2 provided that the authors do the following:

  • provide a patch against the current main trunk of ns-2
  • contribute new regression tests to the validation suite (tcl/test directory) that cover a reasonable portion of the new code. Don't forget to set the binary flag on the trace .Z files!
  • provide documentation that integrates with the ns-2 documentation
  • contribute example scripts in the tcl/ex directory
  • verify that the test suites still pass (run "./validate" in the top-level ns directory), or if not, justify that changes to the regression output are not introducing errors to the protocol models. If regression output changes, there needs to be a review by the authors or maintainers of the models affected.
  • follow the guidelines above concerning the editing of CHANGES.html and a meaningful cvs commit message