-
Notifications
You must be signed in to change notification settings - Fork 371
ContractorInstructions
- Weekly reports are required. Please send an email update weekly even if nothing happened.
- The repository for development shall be specified by the IETF's Project Manager (or equivalent). New projects will be set up in GitHub (see https://github.com/ietf-tools).
-
See https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md
-
Work is expected to be in a fork of a project that the designated project manager has access to. Unless otherwise specified, these forks must be public.
-
Progress will be monitored through activity in the fork. Commits should be frequent and regular. Commits must not introduce artifacts specific to local toolchains.
-
The full test suite must pass on any PR, with no exceptions. The full test suite SHOULD pass with thencompletion of each functional change or bugfix committed while working towards that PR. 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.
-
For projects with multiple contributors (particularly the datatracker) When there's a new release, please bring your fork up to date, and move your development branch(es) up to be based on at least the release.
- Unless otherwise specified, issue tracking will occur in the GitHub repository for each project.
New Projects will include the following:
-
A top-level README.md calling out (using links to separate files as appropriate)
- How to Contribute
- Documentation for installation
- Documentation for building a development environment
-
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.
-
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.
-
Testing should be configured to include coverage, and PRs 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 work towards a test suite with nearly-complete code coverage for new code and and other artifacts like django 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.
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.
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.
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.
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.
If the code has dependencies on OS level packages, the project manager must be consulted to make sure such dependencies are acceptable.
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.
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.
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.
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 env" in 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.)
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
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.