BIND 10 trac3278, updated. 543d7901daa0d5b7d5522cef6a37dd940c68a148 [3278] add a description and some of the requirements data
BIND 10 source code commits
bind10-changes at lists.isc.org
Tue Dec 31 16:39:33 UTC 2013
The branch, trac3278 has been updated
via 543d7901daa0d5b7d5522cef6a37dd940c68a148 (commit)
from 7715d34151a84d87702c18ea0717fdb7f63affb0 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 543d7901daa0d5b7d5522cef6a37dd940c68a148
Author: Jeremy C. Reed <jreed at isc.org>
Date: Tue Dec 31 10:37:19 2013 -0600
[3278] add a description and some of the requirements data
Still cleaning up this requirements data, in particular fixing
the RFC reference identifications for unenumerated paragraphs.
Also have lots more to add already written, but need to reformat
to this style.
-----------------------------------------------------------------------
Summary of changes:
doc/requirements/README | 101 ++++++++++++++++++++++++++++++++++++
doc/requirements/TODO | 13 +++++
doc/requirements/requirements.data | 65 +++++++++++++++++++++++
3 files changed, 179 insertions(+)
create mode 100644 doc/requirements/README
create mode 100644 doc/requirements/TODO
create mode 100644 doc/requirements/requirements.data
-----------------------------------------------------------------------
diff --git a/doc/requirements/README b/doc/requirements/README
new file mode 100644
index 0000000..154b83c
--- /dev/null
+++ b/doc/requirements/README
@@ -0,0 +1,101 @@
+Requirements
+============
+
+This directory contains compliance and conformance requirements,
+based on protocol specifications (such as RFCs) and real-world
+code implementations. These documented requirements are written
+and stored in a consistent and organized structured data so they
+may be reused or converted for other needs easily, such as:
+
+* Checklists for validating software capabilities/features
+* Checklists for identifying software development needs
+* Feature statements or descriptions for reuse for testing definitions
+ and/or output
+* Generating documentation
+* Generating cross-references
+
+Customers and end-users may use the generated reports to see how
+well our software conforms to known specifications.
+
+Requirements Document Contents
+------------------------------
+
+Each item in the requirements document is a single explanation or
+short statement. The meta data to help attribute and define it
+include:
+
+ID -- unique identifier for the specific item. This is not an RFC
+reference since one specific statement may be defined in multiple
+official protocol documents, for example. Test cases will reference
+these IDs.
+
+description -- a short clearly understandable statement describing
+the feature or behavior. This is usually a single complete sentence,
+but may be multiple sentences. The maximum is around 25 words and
+a common length is around ten words. If it takes a longer statement
+to describe it or the requirement cannot be easily defined in one
+succinct sentence, then consider splitting it up into multiple
+requirements.
+
+notes -- optional extra notes or explanation. For example, this
+may identify where some specifications are unclear or wrong.
+
+attribution -- the source of the requirement, e.g. a reference to
+an RFC or other official specifications document. This would be
+precise for the section, sub-section, paragraph number, etc. There
+may be multiple references for the same item. An example format is:
+RFC1035:3.2.1/2 for the RFC number, section and sub-sections identified
+in that document, and then a optional precise sentence or paragraph
+counter that is not enumerated in the document.
+
+The above fields will typically be included in every requirements
+document, although only "ID" and "description" are mandatory. Other
+information that may be useful is:
+
+context tags -- a keyword or few keywords to describe use at a high
+level, such as validator, signer, or authoritative (server), etc.
+
+source-code -- point to the source code implementation of this,
+such as a specific BIND 9 or other open source implementation's
+source file. This is useful if no outside official specification
+documents this behavior.
+
+dependency -- list of the IDs of pre-requisite requirements.
+
+test -- list of tests for this specified item. This may define:
+the type (e.g. Gtest, Lettuce etc.), source filename of the test
+code if applicable, and the specific name of the test. There may
+be multiple tests for a single item. This would be used to generate
+a report if the specifications are covered by tests and if they
+pass or not. It will also be useful to know if a test disappears.
+This field likely will not be used.
+
+Note that the document as currently organized does not include
+lengthy or multi-step higher level processes or use cases.
+Nevertheless, multiple single items could be referenced and ordered
+to define use case scenarios.
+
+Requirements Document Format
+----------------------------
+
+The requirements document is created as a tab-delimited spreadsheet
+with a single line per requirement: this makesit easier to organize
+and allows the sorting the requirements as desired. Storing the
+document as as a text file with tab-delimited fields allows it to
+be maintained directly in the source code repository and differences
+between versions easily seen using standard tools.
+
+The per-entry format is:
+
+ID description notes attribution context-tags source-code dependency test
+
+Lines beginning with a pound sign (#) will be ignored.
+
+Requirements Document Revision and Approval
+-------------------------------------------
+
+All requirements documents must be reviewed before use. Prior to
+adding any new feature or changing behavior of software, the
+appropriate requirements document must be updated. The revision
+should be reviewed before being used as the basis of implementation.
+Even minor updates to requirement entries should be reviewed.
diff --git a/doc/requirements/TODO b/doc/requirements/TODO
new file mode 100644
index 0000000..48cd37f
--- /dev/null
+++ b/doc/requirements/TODO
@@ -0,0 +1,13 @@
+
+- get ixfr and ddns details from wiki and provide list of problems
+ with those
+
+- create script to generate HTML output of specifications
+
+- script to verify that ID numbers are not reused.
+- script verify that entries are sane (not too long, correct amount of
+ fields, etc)
+
+- add unique test numbers to lettuce Scenario descriptive titles
+
+- script to parse lettuce output to generate report
diff --git a/doc/requirements/requirements.data b/doc/requirements/requirements.data
new file mode 100644
index 0000000..afde4a2
--- /dev/null
+++ b/doc/requirements/requirements.data
@@ -0,0 +1,65 @@
+#ID description notes attribution context-tags source-code dependency test
+100500 An unknown RRTYPE should not break loading. TODO ? master-file - - -
+100510 The owner name is the name of the node for an RR entry. - RFC1035:3.2.1/2 master-file - - -
+100530 Domain names are represented as a series of character strings (labels) that are separated by dots. BUG: RFC has two different definitions for domain-name, one says "terminated by a label with zero length" and other "do not end in a dot". RFC1035:3.3.2,RFC1035:5.1/15 master-file - - -
+1001000 Recommend rejecting obsolete MD RRs - RFC1035:3.3.4/5 master-file - - -
+1001010 Optionally convert MD RRs to MX with preference 0 - RFC1035:3.3.4/5 master-file - - -
+1001020 Recommend rejecting obsolete MF RRs - RFC1035:3.3.5/5 master-file - - -
+1001030 Optionally convert MF RRs to MX with preference 10 BUG: The RFC has an content mistake here. RFC1035:3.3.5/5 master-file - - -
+1001040 NULL RRs are not allowed in master files. - RFC1035:3.3.10/3 master-file - - -
+1001050 WKS RR ports and protocols may be defined using decimal numbers or mnemonics as defined in RFC1010. - RFC1035:3.4.2/6,RFC1035:3.4.2/10 master-file - - -
+1001060 Multiple values for a type are defined using multiple resource records. - RFC1035:3.6.5 master-file - -
+10011070 Parentheses can be used to continue an entry beyond a line; an entry is not terminated within parentheses. - RFC1035:5.1/1,RFC1035:5.1/22 master-file - -
+10011080 A carriage return plus linefeed (CRLF) can be part of a entry. TODO: mention and define text literal RFC1035:5.1/1 master-file - - -
+10011090 Both tabs '\t' and spaces ' ' can be used in any amount to separate items that make up an entry. - RFC1035:5.1/1 master-file - -
+10011100 Any line can end with a comment that starts with semicolon ';'; the comment is ignored. - RFC1035:5.1/1,RFC1035:5.1/23 master-file - -
+10011110 A comment marker ';' is proceeded by a blank character. BUG: this is wrong since a line can start with a semicolon RFC1035:5.1/1 master-file - - -
+10011120 An $ORIGIN control entry definition line may have a comment. - RFC1035:5.1/4 master-file - -
+10011130 An $INCLUDE control entry definition line may have a comment. - RFC1035:5.1/5,RFC1035:5.1/9 master-file - -
+10011140 An $INCLUDE control entry definition line may optionally define the relative domain origin with an optional second argument. - RFC1035:5.1/5,RFC1035:5.1/9 master-file - -
+10011150 Blank lines are allowed anywhere. - RFC1035:5.1/8 master-file - -
+10011160 The $ORIGIN control entry sets the current origin for relative domain names to the value set in its first (and only) argument. - RFC1035:5.1.2,RFC1035:5.1.4 master-file - -
+10011170 The $INCLUDE control entry inserts the file (filename is first argument) into the current file. - RFC1035:5.1.2,RFC1035:5.1.4 master-file - -
+10011180 The $INCLUDE control entry canno change the origin of the parent file. - RFC1035:5.1.4 master-file - -
+10011190 $ORIGIN names that do not end with a dot are usually interpreted as a warning, and should be reported. - ? master-file - -
+10011200 $ORIGIN names that do not end with a dot are interpreted as a normal name, relative to the current origin. - ? master-file - -
+10011200 If the $INCLUDE named file cannot be loaded it is an issue, and usually treated as an error; if treated as a warning, it is ignored for processing. TODO: what is usually? when to choose? ? master-file - - -
+10011190 A line that is not a $ control entry is a resource record. - RFC1035:5.1.2,RFC1035:5.1.5 master-file - -
+10011200 If the RR begins with a blank, then the owner name is the last stated owner. - RFC1035:5.1.5 master-file - -
+10011210 If the RR begins with a name, then the owner name is reset to that name. BUG: RFC says domain-name which implies "terminated by a label with zero length" trailing period. RFC1035:5.1.5 master-file - - -
+10011230 If there was no previous owner name, this is an issue and usually interpreted as an error; if treated as a warning, the RR can be checked but will not be added to the zone. TODO ? master-file - - -
+10011240 The RR contents begin with an optional TTL, or optional class field, or optionally both; the order of the optional class and TTL fields does not matter. TODO: need to describe when not recognized? RFC1035:5.1.6,RFC1035:5.1.7 master-file - - -
+10011250 If the optional class field is omitted, then it defaults to last explicitly defined class. - RFC1035:5.1.7 master-file - -
+10011260 The class field uses standard mnemonics. - RFC1035:5.1.7 master-file - -
+10011270 The RR contents contain type and RDATA fields; the RDATA is appropriate to the type and optional class. - RFC1035:5.1.7 master-file - -
+10011280 The TTL field is a decimal integer. TODO: this changed RFC1035:5.1.7 master-file - - -
+10011300 Quoting conventions may be used for domain names. - RFC1035:5.1.8 master-file - -
+10011310 A domain name without an ending dot '.' is relative and has the origin appended to it; the origin may be from a $ORIGIN or $INCLUDE control entry, or defined by an master file loading routine argument. - RFC1035:5.1.8 master-file - -
+10011320 If there is no origin (to use for a relative name), it is an error. - RFC1035:5.1.8 master-file - -
+10011330 If there is no origin (to use for a relative name), it is an issue that is usually interpreted as an error; if treated as a warning, the domain name is considered absolute. TODO: conflicts with m1132 ? master-file - - -
+10011340 Quoted strings (starting and ending with '"' characters) may contain any character including spaces, except a quote; a quote '"' may be used with a '\"'. - RFC1035:5.1.9 master-file - -
+10011350 A missing closing '"' is an issue, and usually treated as an error; if treated as a warning, then the end of file is treated as the closing quote. - ? master-file - -
+10011360 The @ by itself is treated as the origin. - RFC1035:5.1.10 master-file - -
+10011370 A backslash not followed by a digit may be used so the character as literal (and doesn't have a special meaning). - RFC1035:5.1.9,RFC1035:5.1.10 master-file - -
+10011380 A backslash followed by three digits results in its corresponding ASCII character and is used literally. BUG: RFC says "decimal number" but really is "decimal ASCII character" RFC1035:5.1.10 master-file - - -
+10011390 Parentheses do not nest; a second open parenthesis before a close parenthesis is an issue, and usually considered a warning; if treated as a warning, it is ignored. TODO: where documented? ? master-file - - -
+10011400 A missing closing parenthesis is considered an issue, and usually interpreted as an error; If treated as a warning, the end of file is treated as the closing parenthesis. TODO: where documented? ? master-file - - -
+10011410 A TTL is a positive number (or 0); it is stored in a signed 32 bit number; the maximum is 2147483647. BUG: RFC1035:2.3.4 says positive but it can be zero. RFC1035:2.3.4,RFC1035:3.2.1,RFC1035:4.1.3,RFC2181:8 master-file - - -
+10011420 If any errors happen when loading a zone, the loading should be ended and the results excluded. - RFC1035:5.2.1 master-file - -
+10011430 All records in a master file should be the same class. - RFC1035:5.2.2 master-file - -
+10011440 Master files with different classes is an issue, and usually treated as an error; if treated as a warning, then the first class used in the zone is used for the RR. TODO ? master-file - - -
+10011450 Only one SOA RR should exist. BUG: the RFC is vague since has only one should be present at the top -- what about elsewhere in same master file? RFC1035:5.2.2 master-file - - -
+10011460 If a SOA appears again with the same value, it is considered an issue and usually treated as a warning; if treated as a warning then the second value is ignored. TODO ? master-file - - -
+10011470 If a SOA appears again with a different value, it is considered an issue and usually treated as an error; if treated as a warning then the second value is ignored. TODO ? master-file - - -
+10011480 If glue is required for delegations (NS records) then it must be present. TODO: define how to require it RFC1035:5.2.2.3 master-file - - -
+10011490 For required glue, if neither an A nor an AAAA record is present, this is an issue and usually treated as a warning; if treated as a warning the zone is loaded without the necessary data and the delegation is broken. TODO ? master-file - - -
+10011500 Information outside of the authority for the zone (out-of-bailiwick data), other than glue, is an issue, and usually considered an error; if interpreted as a warning, it is ignored. TODO: RFC1035:5.2/2.4 master-file - - RFC is vague; where to define if its a error or not?
+10011510 An $TTL control entry definition line may have a comment. - RFC2308:4/4 master-file - -
+10011520 If the TTL field is omitted, then it defaults to the previous $TTL directive value; if no $TTL was defined, then it uses the last explicitly defined TTL. The $TTL supersedes RFC1035:5.1/6, the fallback is if is not defined, is not defined. RFC2308:4/5 master-file - - -
+10011530 If no TTL and no previous $TTL directive nor TTL defined, then this is an issue and is usually interpreted as a warning; ;f interpreted as a warning then the TTL from the last field of the SOA is used, unless the SOA has not yet been seen, in which case must be interpreted as an error. TODO: where is the concept of using the SOA MINIMUM/NEGATIVE defined? ? master-file - - -
+10011540 All RR's in a set of Resource Records must have the same TTL, unless it is a RRSIG RR; TTLs for RRSIG records must match the TTL value for the RRset that the signature is for. RFC4034 supersedes RFC2181 for the RRSIG rule. RFC2181:5.2/2,RFC4034:3/7 master-file - - -
+10011550 The keyword TYPE immediately followed by decimal number is used for unknown resource record types. - RFC3597:5/1 master-file - -
+10011560 The keyword CLASS immediately followed by decimal number is used for unknown classes. - RFC3597:5/1 master-file - -
+10011560 The RDATA for an unknown type begins with '\#' (backslash-pound), whitespace, the RDATA length in sockets specified with an unsigned decimal integer, whitespace, and then zero or more words of hexadecimal (even nummber of digits) encoding of the data; an empty RDATA can be represented with '\# 0'. - RFC3597:5/3,RFC3597:5/4 master-file - -
+10011570 The generic \# RDATA representation may be used for known types; but if known, the later processing must apply type-specific rules. - RFC3597:5/5,RFC3597:5/6 master-file - -
+10011580 Any error with the generic RDATA format, such as not having enough hexadecimal data for the length, is an issue usually considered an error; if considered as a warning, then the RR is skipped. TODO: where documented? ? master-file - - -
More information about the bind10-changes
mailing list