Skip to content

ContractorInstructions

Jump to bottom
henrik edited this page Sep 11, 2013 · 29 revisions

TOC

Instructions for IETF Software Development Contractors

''' This page is incomplete, and until this annotation is removed, should be considered only a place to jot down notes on instructions'''

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 primary repository for the 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).

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 usesrs
  • 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

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.
  • 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.

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