NDN Platform Development Guidelines

These are guidelines for developers contributing to the NDN Platform projects.

Ownership

Each project has a project owner who is responsible for (at least):

  • Reviewing and merging changes (pull request)s in light of the project’s goals and philosophy,
  • Deciding when to make a new tagged version (release),
  • Maintaining the accuracy of the project documentation,
  • Making sure the project builds as needed,
  • Providing support for interoperability / consistency with other components in each platform release.

Hosting

Each project shall follow these guidelines for hosting:

Build support

Each project must have a build system to make it easy for users to build and install. The project should build on the following platforms:

  • The latest Ubuntu LTS release with the gcc which comes with apt, 64-bit, 2GB memory
  • The previous Ubuntu LTS release with the gcc which comes with apt, 64-bit, 2GB memory
  • Ubuntu 16.04 LTS, 32-bit, 2GB memory with the gcc which comes with apt. (Ubuntu 18.04 doesn’t support 32-bit.)
  • The latest three macOS releases with the clang which comes with XCode, 64-bit, 2GB memory
  • Optional: The previous Ubuntu LTS release with the gcc which comes with apt, 32-bit, 2GB memory
  • Optional: The latest Ubuntu release (if not LTS) with the gcc which comes with apt, 64-bit, 2GB memory
  • Optional: The latest Windows with Visual Studio, 64 bit, 2GB memory
  • Optional: The latest FreeBSD “RELEASE” with the clang which comes with ports, 64 bit, 2GB memory

So, as of September 2018 the required platforms are:

  • Ubuntu 18.04, 64-bit
  • Ubuntu 16.04, 64-bit
  • Ubuntu 16.04, 32-bit
  • macOS 10.14 “Mojave”
  • macOS 10.13 “High Sierra”
  • macOS 10.12 “Sierra”

This list will be updated in consultation with the platform component owners. Our intent is to provide clean VM instances for build testing.

The project’s owner will choose between a Makefile system or waf. (There should always be a configure step for these platform projects… no hardcoding of paths, etc.)

For a Makefile system, the project should build with:
./configure
make
sudo make install (optional)

For a waf system, the project should build with:

./waf configure
./waf
sudo ./waf install (optional)

Tracking changes

For projects which are part of the NDN platform, changes should come from a “feature” or “bug” Redmine issue. Depending on whether the project owner decides to use code review or not, this is done as follows:

  • Create the feature or bug Redmine issue (if it doesn’t exist).
  • Create a local git branch named issue/<issue-number>-some-description. Example:
    git checkout -b issue/1034-decodeTypeAndVal-infinite-loop
  • Make your changes.
  • Commit your changes in this branch. The commit message should start with the affected project directory and module (for example “daemon” or “doc”) and end with Refs #<issue-number>. Example:
    encoding: In decodeTypeAndVal, quit the loop if read past the end of the input. Refs #1034.
  • (If you are doing code review, have people review the change.)
  • Finally, merge the branch into master without fast-forward using git merge --no-ff. In the merge commit message, put Refs #<issue-number> and a link to the URL for the Redmine issue (for example Refs #1027 http://redmine.named-data.net/issues/1027).
    git checkout master
    git merge --no-ff issue/1034-decodeTypeAndVal-infinite-loop
    message (in the message editor): Merge branch 'issue/1034-decodeTypeAndVal-infinite-loop'. Refs #1034 http://redmine.named-data.net/issues/1034
  • Delete the issue branch. Example:
    git branch -d issue/1034-decodeTypeAndVal-infinite-loop
  • Push your changes.
  • (If you are doing code review, the project owner pushes the changes to GitHub.)
  • Close the Redmine issue.

Releasing

The project owner decides when to make a new release. Each release includes the following steps:

  • Changes must be noted in the CHANGELOG.
  • The new version is given an annotated tag in git. Versioning generally follows Semantic Versioning http://semver.org/. For example:
    git tag -a v1.2
    git push origin --tags
  • Send an announcement to ndn-interest@lists.cs.ucla.edu .

Basic documentation

Each project’s repository must have the following files in the top folder:

  • README or README.md: The README or README.md file contains a project description and getting started guide (not build instructions which are in INSTALL, or changes which are in CHANGELOG). If this is the only “home page” for the project, the README.md file should be in Markdown format so that the Github project displays it nicely. See http://daringfireball.net/projects/markdown/basics.
  • INSTALL or INSTALL.md: The INSTALL file has prerequisites, build and install instructions. At a minimum, there should be instructions for Ubuntu and OS X, with optional FreeBSD and Windows.
  • COPYING or LICENSE: This is referenced in the copyright header of each source file. See https://raw.github.com/named-data/ndn-js/master/COPYING.
  • NOTICES (optional): If the project distribution includes other people’s code, include a NOTICES file with information on their licenses.
  • CHANGELOG: The change log shows a list of bug fixes and other changes from the previous version.

Code documentation

Platform project authors are encouraged to:

  • Liberally comment their code with the intent of explaining design decision and operation.
  • Provide additional documentation in whatever format they feel is appropriate.
  • Provide doxygen-style auto-generated documentation, which will be hosted on named-data.net. (This is required for client libraries.)
  • Recommend:
    • Doxygen for C, C++ and Java
    • JSDoc for JavaScript
    • Docstrings for Python
  • Consider a mechanism (either manual or automatic) that publishes docs on a website for each platform release

License

Platform projects must have an explicitly stated license in a  COPYING or LICENSE file. Licenses must be an accepted open-source license: http://opensource.org/licenses.

Each code file should have:

  • A copyright notice with year following the policy of the institution. (U.C. system copyrights are not held by individuals but by the Regents of the University of California.)
  • A pointer to the COPYING or LICENSE file for the project.
  • An author list, preferably with email addresses.
  • An acknowledgement of incorporated code / derivation.

Code guidelines

For C-style languages (C, C++, C#, Java, JavaScript), follow the C++ etc. Code Guidelines.

For Python, follow the Python Code Guidelines.