Skip to content

ContractorInstructions

Jump to bottom
henrik edited this page Jun 28, 2016 · 29 revisions

TOC

Instructions for IETF Software Development Contractors

Last modified: LastModified

Reporting

  • Weekly reports are required. A report template will be sent out each Friday. Please fill in and return even if nothing has happened.

Repository Commits

  • The repository for development shall be the repository set up for the project by the IETF's Project Manager (or equivalent). For instance, here is the repository for the IESG tracker conversion project: http://svn.tools.ietf.org/svn/tools/ietfdb/branch/iola/iesg-tracker/.

  • Best Current Practice for repository commits should be followed, which means that commits should be done for each completed functional change and bugfix, with commit messages indicating what has been fixed. If a bug has been fixed, that should be indicated as 'Fixes bug #42' or similar as described in SvnTracHooks.

  • When there's a new datatracker release, please merge your current development branch to a new branch copied off the new release. Doing this ensures that you get the chance to make sure your changes are merged correctly to the current codebase, and also makes life easier for the guy who is eventually going to merge your project into trunk. (If don't do this, and trunk and your development branch diverges too much, it's quite likely that some of your beautiful code will be lost or mangled in the final merge to trunk).

  • Progress will be monitored through this repository. Commits should be frequent and regular. Commits and merges must not introduce artifacts specific to local toolchains.

  • The full test suite must pass on a commit that is ready for merge into trunk, with no exceptions. The full test suite SHOULD pass with the completion of each functional change or bugfix committed while working towards a commit that is ready for merge. If you find yourself making a series of several interim commits where there are failing tests, please stop and focus on bringing things back to a passing state.

Issue Tracking

  • A Trac instance will be set up for each project, or an existing Trac instance will be set up with a specific 'component' for the project.

  • The project documentation (and web pages, if the project creates such) should provide a URL / Link to the issue tracker to make it easy to report issues there.

  • Users should be expected to report issues in the issue tracker.

  • Developers should close issues when handled (this is most easily done using the SvnTracHooks when committing a fix).

Required Files

  • INSTALL: Installation instructions for end users

  • BUILD: How to build a release, for developers

  • README: Description of the project, like 'Introduction' in a draft

  • LICENCE: The license prescribed by the IETF Trustees in the latest Trust Legal Provisions document at http://trustee.ietf.org/license-info. The current license as of 23 Nov. 2011 is reproduced below under [#CurrentLicense Current Licence] for ease of reference, but the license to be used is at all times that prescribed by the IETF Trust, with the removal of the words 'and the persons identified as authors of the code' when the code has been produced as Work for Hire.

  • changelog: A file at the top of the code tree for each separately distributable part of the project. Normally there are only one, but if the project contains for instance separate CLI and GUI parts, they would have separate changelog files. This file should be in the debian changelog format. It should contain descriptions of all major functional changes and additions for each release. For an example, see trunk/changelog

  • A debian control file is desired, also in cases where the package is not directly intended for debian packaging. Content from this file is used to automatically build some of the tools description pages at tools.ietf.org. See the debian control file description

Coding Practices

Multiple contractors and a bunch of individuals are working on this code. To make things go smoothly, there are some practices which are common in team coding efforts that must be followed:

  • >>> import this

  • Follow the coding style in the piece of code you are working on. Don't re-format code you're not working on to fit your preferred style. As a whole, the piece of code you're working on will be more readable if the style is consistent, even if it's not your style.

  • For Python code, PEP 8 is the style guide. Please adhere to it, except when in conflict with the bullet above.

  • Don't change whitespace in files you are working on, (except for in the code you're actually adding/changing, of course); and don't let your editor do end-of-line space stripping on saving. Gratuitous whitespace changes may give commit logs and diffs an appearance of there being a lot of changes, and your actual code change can be buried in all the whitespace-change noise.

  • Now and then, code clean-up projects are run. During those, it can be the right thing to do whitespace clean-up, coding style alignment, moving code around in order to have it live in a more appropriate place, etc. The point in those cases is that when you do that kind of work, it is labelled as such, and actual code changes are not to be inserted in style and whitespace-change commits. If you are not in a clean-up project, don't move code around if you're not actually doing work on it.

  • If you are modifying existing code, consider whether you're bending it out of shape in order to support your needs. If you're bending it too much out of shape, consider refactoring. Always try to leave code you change in a better shape than you found it.

Testing

  • Reasonably comprehensive test suites should be written and committed to the project repository.

  • Projects written for Django should use Django's test facility, in files tests.py in each application directory.

  • Other projects, written in Python, should use Python's doctests or unittest framework.

  • Other projects should use the best practice for the respective code environment for testing.

  • As of release 5.12.0, the Django test suite for the datatracker includes tests which measure the test suite's code, template, and URL coverage and fails if it drops below that of the latest release. When merged in, your code should not make the test coverage drop below the latest release. Please run the full test suite regularly, to keep an eye on your coverage numbers.

  • Please shoot for a test suite with at least 80% code coverage for new code, as measured by the built-in coverage tests for the datatracker or standalone use of coverage.py for other Python projects. For non-Python projects, use the most appropriate test coverage measurement tool.

  • For the datatracker, aim for 100% test suite template coverage for new templates.

  • When a reported functional bug is being addressed, a test must be written or updated to fail while the bug is present and succeed when it has been fixed, and made part of the bugfix. This is not applicable for minor functional bugs, typos or template changes.

Dependencies

Python

If the code produced as part of the project has dependencies on Python library modules outside of the standard Python library, those modules should be known to the "pip" (Package Installer for Python) tool, and should be captured in the standard requirements file format for pip, in a file named "requirements.txt". This file should be made part of the deliverable, in the revision control repository. It should be placed at top level in the delivered repository branch.

PHP

If the code has dependencies on PHP modules, these modules should be described in a Composer-compatible "composer.json" file. The appropriate composer command should be included in the installation instructions, and the composer.json file should be made part of the deliverable, in the revision control repository. It should be placed at top level in the delivered repository branch.

Perl

If the code has dependencies on Perl modules, those modules must either be available in the CPAN repository, or provided in source form by the designer as a part of the package delivery. The packages should be listed as dependencies in the product Makefile, and must compile and/or install as a "make deps" step.

C / C++

If the code has dependencies on C or C++ functions, those functions must either (a) be a part of the GLIBC C Standard Library, or (b) be a a part of the Boost library collection, or (c) provided in full source form as a part of the deliverable. Functions provided should be described in the product Makefile, and should build as a part of the "make" for the compilation step.

OS libs

If the code has dependencies on OS level packages, the project manager must be consulted to make sure such dependencies are acceptable.

Packaging

If the project deliverable is intended for a single or small number of server installations, such as is the case for a web project or database front-ends, it should be possible to install a version the project by simply checking it out from the code repository and running packaged setup scripts (provided of course that the appropriate web-server configuration has been set up). See the [#ServerDeploymentExample Server Deployment Example] below.

If the project deliverable is a Python tool that is to be distributed to and installed by end users, it should be packaged as a python package according to the "Python Packaging User Guide", and uploaded to the "Python Package Index" (PyPI). The web-page "Distributing Python Modules" provides an introduction to the packaging guide and the package index.

Deployment

Python

For Python-based stand-alone user-installed tools, deployment should normally be possible by simply using the "pip" tool to install the package. Assuming the package name is foobaz, the command to download the packaged code from PyPI and install it would be

  $ pip install foobaz

For server-installed projects, installation in a virtual python environment, a "virtualenv", is strongly preferred. This isolates the specific versions of the project's dependencies from other projects, and makes it easy to install up-to-date requirements from the specification in the "requirements.txt" file.

Non-Python

For all other server-installed projects, use of a Makefile is strongly preferred. Additional steps, such as CPAN module installations, and/or Composer integrations, can be specified. Use of a server-based "configure" tool is optional. The Makefile should be written to current standards, describing dependencies, build procedures for all dependencies and main targets, configuration file deployment, documentation processing, and final target installation. The software should be installable using "make; sudo make install" or a similar, common procedure. The Makefile should be upgrade-aware, and should not disturb existing modified configuration files, but should deploy new example configuration files alongside the live files when an upgrade install is performed.

Server Deployment Examples

Python/Django

As an example of how a project could follow the guidelines above, here is a brief list of the actual actions done to deploy a new version of the IETF datatracker (A Django project, using the Django manage.py management command):

  • Check out the release from repository in a version-named directory
  • Run virtualenv" on the top directory
  • Activate the environment
  • Run pip install --upgrade -r requirements.txt
  • Run (if needed) .../manage.py collectstatic
  • Run .../manage.py migrate
  • Run .../manage.py check
  • Symlink the version-named directory to the name served by apache
  • Reload Apache

(The datatracker INSTALL file gives more detailed information.)

Non-Python

As an example of how a C- or PHP-based project could follow the guidelines above, here is a brief list of the typical actions taken to deploy a typical C-based program.

  • Check out the release from repository in a version-named directory
  • Run ./configure
  • Run make
  • Run sudo make install
  • Reload Apache

Current License

This is the Simplified BSD Licence:

Copyright (c) <insert year> IETF Trust. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above copyright notice, this
 list of conditions and the following disclaimer.

 * Redistributions in binary form must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution.

 * Neither the name of Internet Society, IETF or IETF Trust, nor the names of
 specific contributors, may be used to endorse or promote products derived
 from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Clone this wiki locally