Semantic Versioning and Structure for IETF Specifications
draft-claise-semver-00

Network Working Group                                          B. Claise
Internet-Draft                                                 R. Barnes
Intended status: Standards Track                               J. Clarke
Expires: December 22, 2017                                         Cisco
                                                           June 20, 2017

       Semantic Versioning and Structure for IETF Specifications
                         draft-claise-semver-00

Abstract

   In the Internet engineering ecosystem, there is increasingly a need
   for specifications that evolve over time, and are encoded directly in
   structured formats (e.g., YANG models).  Internet-Drafts are a poor
   fit for working groups that want to produce structured
   specifications, and publishing versions of an evolving specification
   as RFC makes it difficult to track the specification over time.  This
   document outlines recommendations for how working groups can provide
   semantic versioning for, and work directly on, structured documents
   while still fitting within established IETF processes.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on December 22, 2017.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents

Claise, et al.          Expires December 22, 2017               [Page 1]
Internet-Draft                   SemVer                        June 2017

   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Managing Semantic Versions  . . . . . . . . . . . . . . . . .   3
     2.1.  Versioning for Work in Progress . . . . . . . . . . . . .   4
   3.  IETF Consensus for Structured Specifications  . . . . . . . .   5
   4.  Example history . . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Creating Internet-Drafts from a Repository  . . . . . . . . .   8
     6.1.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   The pace at which the software that drives the Internet is developed
   and deployed today is much faster than it was early in the Internet's
   history.  In this environment, maintaining interoperability can be
   more challenging.

   Two of the major mechanisms that have been developed for driving
   interoperability in a more dynamic ecosystem are semantic versioning
   and structured specifications.  Structured specifications allow much
   of the work of implementing a specification to be automated, so that
   developers can focus on the parts of a specification that really need
   human involvement.  Semantic versioning helps operators know what
   versions can be deployed without breaking running systems, so that
   they can safely deploy updated versions of a specification more
   quickly.

   The traditional practices of the IETF interact poorly with these
   mechanisms.  Each document presented to the IETF for last call and
   IESG approval must be formatted as an Internet-Draft, i.e., as
   unstructured text.  All RFCs across the IETF share a single, common
   numbering space, so that RFC numbers have no useful semantic with
   respect to versioning.  Nonetheless, there is still a need to be able
   to capture the consensus of the IETF at critical points in the life-
   cycle of a specification.

   This document describes recommendations for how a working group (WG)
   that wishes to produce structured specifications with semantic
   version numbers can interact best with IETF processes.

Claise, et al.          Expires December 22, 2017               [Page 2]
Internet-Draft                   SemVer                        June 2017

2.  Managing Semantic Versions

   While some of this process might apply to completely new work (such
   as a YANG module), the process in this document applies to WG adopted
   work items or to modification of an existing IETF-approved work item
   (typically a bis document ).

   We start from the premise that a working group controls a version-
   controlled repository (e.g., Git, SVN, etc.) for a structured
   specification (not formatted as an Working Group Internet-Draft), and
   can "tag" commits in the repository as having certain version
   numbers.  We assume that there is one repository per specification,
   so that version tags don't need to specify which specification they
   refer to.

   The recommended structure for semantic versions follows the widely-
   used three-part convention, with an additional field for use in
   working group processes:

     MAJOR.MINOR.PATCH

   The fields in such a structured version have the following semantics
   (cf.  semver.org):

   o  MAJOR is incremented when the new version of the specification is
      incompatible with previous versions.

   o  MINOR is incremented when new functionality is added in a manner
      that is backward-compatible with previous versions.

   o  PATCH is incremented when bug fixes are made in a backward-
      compatible manner.

   In IETF terms, this versioning scheme provides functionality
   analogous to several parts of the traditional IETF process.

   o  MAJOR is analogous to an "obsoletes" relation between RFCs

   o  MINOR is analogous to an "updates" relation between RFCs

   o  PATCH is analogous to use of the RFC errata process

   The more major a change to the specification, the more consensus is
   required.  When the WG wants to make a MAJOR change to a structured
   specification, the specification MUST be converted into Internet-
   Draft format and run through the typical IETF consensus process.
   Every commit that is tagged with a MAJOR version change MUST also
   have a tag indicating the number of the RFC describing the change.

Claise, et al.          Expires December 22, 2017               [Page 3]
Internet-Draft                   SemVer                        June 2017

   For MINOR changes, WG consensus is required.  The WG chairs can
   additionally decide whether IETF consensus is required.  Any change
   to the structured specification that significantly changes the
   security considerations for the protocol or requires additional IANA
   actions MUST be converted into Internet-Draft format and submitted
   for IETF consensus.  Changes without such impacts MAY be approved by
   consensus of the working group.  PATCH-level changes MAY be made by
   the editors, with the consent of the WG chairs.

   When a working group starts up work on a new version of the
   specification, regardless of whether it's a minor update or a
   complete rewrite, they SHOULD create a dedicated branch of the
   repository for the new version, where changes related to the new
   version will be committed.  The semantic version, i.e. MAJOR and
   MINOR is assigned when this branch is merged back to the main
   specification.  Once there is consensus to update the main
   specification to that version, the branch should be merged, and the
   merge commit tagged with the new version number.

   When working on modification to an existing work item (typically a
   bis document), the process is to fork a git repo, branch, make a
   proposal, then push the branch back over to the Working Group when/if
   the Working Group adopts it.

2.1.  Versioning for Work in Progress

   It can be useful to mark certain versions of a work in progress as
   checkpoints, e.g., for reference at a hackathon.  These checkpoints
   should follow their own version sequence, much like Internet drafts:

     LABEL-VERSION

   o  LABEL is a string that identifies the feature branch

   o  VERSION is incremented whenever a new revision is tagged

   These tags are analogous to Internet-Draft names.  Much like an
   Internet-Draft name, the choice of LABEL values is up to the editors
   and WG chairs.  In cases what they expect the completed work to
   result in a given version, then they might use that as a label value.
   For example, if the WG has agreed to embark on a major revision to
   the protocol, then they might use the label "v2.0.0-beta", so that
   the working revisions would be "v2.0.0-beta-0", "v2.0.0-beta-1", etc.

   It's important to note that not every commit needs a version.  Much
   like working groups using Github to manage Internet-Drafts today only
   periodically submit them to the IETF, a WG can do work in a
   repository and only tag versions when they are useful to the WG.

Claise, et al.          Expires December 22, 2017               [Page 4]
Internet-Draft                   SemVer                        June 2017

   Beta versions should be tagged at key points in the development
   process:

   o  Before an IETF meeting or WG interim meeting

   o  Before a hackathon or interop event

   o  Before a working group or IETF last call

   Work on a new version SHOULD be conducted on a dedicated branch.
   Once there is consensus to update the main specification to that
   version, the branch should be merged, and the merge commit tagged
   with the new version number.

3.  IETF Consensus for Structured Specifications

   While working groups may use any format for specifications under
   development, the Internet Standards process requires that a document
   proposed as an RFC must be submitted in the RFC format, i.e., as
   unstructured text.  Proposed RFCs are also required to contain
   explanatory text not typically contained in structured
   specifications, most notably Security Considerations and IANA
   Considerations.  Thus, a working group that is focused mainly on a
   structured specification will have to convert the structured
   specification to the RFC format and add the additional explanatory
   text.

   In order to keep the repository as the primary home for the
   specification, the working group should keep any required explanatory
   text in the repository alongside the structured specification, and
   use automated tools to generate an RFC-formatted document from the
   artifacts in the repository.  As the outputs are reviewed in the IETF
   last call and IESG processes, the editors should reflect their
   responses in the repository, generating updated versions of the RFC-
   formatted document as necessary.

   Whenever an Internet-Draft is generated from the repository, the
   corresponding commit in the repository should be tagged with the full
   name and version of the Internet-Draft.  Additionally, a reference to
   the repository (e.g., a URL) should exist in the text of the
   resulting Internet-Draft.  These steps enable the evolution of the
   draft to easily be tied back to the evolution of the repository.

4.  Example history

   The below sequence of commits and tags shows the progress of a
   structured specification through several stages of its life-cycle.

Claise, et al.          Expires December 22, 2017               [Page 5]
Internet-Draft                   SemVer                        June 2017

   (Time flows up from the bottom, as is common in version control
   logs.)

   An initial version of a protocol is proposed for a Birds of a Feather
   (BoF) and a WG is formed.  The WG develops version 1.0.0 of the
   specification.  Along the way, they tag betas when they need an easy
   way to refer to a version, e.g., before working group last call
   (WGLC).

   Once the WG has reached consensus, an Internet-Draft is created from
   the repository (draft-ietf-wg-proto-00) and submitted for the IETF
   consensus process, resulting in an RFC (RFC XXX1) that describes the
   first version of the protocol.  In this example, there is never a
   need to publish an individual (author-named) internet-draft, because
   the WG worked directly on the structured specification and obtained
   consensus on it.

   Comments from the IETF last call (LC) and the IESG are incorporated
   in the repository, and new versions of the Internet-Draft are
   generated for IESG review and submission to the RFC editor.

   ...
   |
   * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1)
   |         Responses to IESG comments
   |
   * 7494725 (tag:draft-ietf-wg-proto-01) Responses to IETF LC comments
   |
   * 8e2be54 (tag:proto-2, tag:draft-ietf-wg-proto-00)
   |         Responses to WGLC comments
   |
   * 9703a60 (tag:proto-1) Responses to comments at IETF meeting
   |
   * 2b83977 Responses to J. Smith comments
   |
   * 8b75e1e (tag:proto-0) Responses to BoF comments
   |
   * 1991498 Initial submission

   The WG adds two features to the specification.  The first feature is
   major enough that the chairs decide it needs IETF consensus,
   resulting in a second Internet-Draft going through the IETF consensus
   process (draft-ietf-wg-proto-feature-00) to become an RFC (RFC XXX2).
   The second feature is minor enough that it can be approved by WG
   consensus.

Claise, et al.          Expires December 22, 2017               [Page 6]
Internet-Draft                   SemVer                        June 2017

...
|
*   a5f3214 (tag:v1.2.0) Merge branch 'v1.2'
|\
| * 8fb9cb6 Responses to WGLC comments on feature Y
| |
| * 39322e9 (tag:featureY-1) Responses to WG comments; ready for WGLC
| |
| * 39322e9 Add feature Y
|/
*   d1d201d (tag:v1.1.1) Fix validation errors
|
*   6571483 (tag:v1.1.0, tag:draft-ietf-wg-proto-feature-04,
|           tag:RFCXXX2) Merge branch 'v1.1'
|\
| * abc3f5e (tag:draft-ietf-wg-proto-feature-03) Resolution of DISCUSSes
| |         from Security AD
| |
| * 3ab54f3 (tag:draft-ietf-wg-proto-feature-02) Resolution of DISCUSSes
| |         from Internet and Transport ADs
| |
| * cabb1f6 (tag:draft-ietf-wg-proto-feature-01) Responses to WGLC
| |         and IETF LC comments on feature X
| |
| * fbfaa6b (tag:featureX-0, tag:draft-ietf-wg-proto-feature-00)
| |         Responses to comments on feature X
| |
| * 0630638 Add feature X
|/
* e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1)
|         Responses to IESG comments
|
...

   The WG develops a major revision of the protocol, resulting in a
   third Internet-Draft (draft-ietf-wg-protobis-00) going through the
   IETF consensus process, resulting in RFC XXX3.

Claise, et al.          Expires December 22, 2017               [Page 7]
Internet-Draft                   SemVer                        June 2017

   ...
   |
   * a9d7d29 (tag:v2.0.0, tag:draft-ietf-wg-protobis-01 tag:RFCXXX3)
   |         Merge branch 'v2'
   |\
   | * df5d437 (tag:draft-ietf-wg-protobis-00) Responses to
   | |         WGLC and IETF LC comments
   | |
   | * 986ebb6 (tag:v2.0.0-beta-1) Checkpoint for hackathon
   | |
   | * d86986e (tag:v2.0.0-beta-0) Some more v2 features
   | |
   | * ca02154 Restructure for v2
   |/
   *   a5f3214 (tag:v1.2.0) Merge branch 'v1.2'
   |
   ...

   This example history is greatly simplified.  In a real WG, there will
   be far more commits without versions, as the WG incorporates
   proposals, edits explanatory text, etc.  But this example highlights
   the key moments in the life-cycle of a specification.

5.  Creating Internet-Drafts from a Repository

   As noted above, WGs should have one repository per specification.
   Over the lifetime of the specification, it will be necessary for
   automated tools to build Internet-Drafts from this repository.  A
   standardized repository layout can help automate this process.

   The root level of the repository should have a file named "index.xml"
   or "index.md", depending on whether XML [1] or Markdown [2] is being
   used.  This file should itself be a valid source for an Internet-
   Draft, including information about the title to be used, authors' /
   editors' names, security considerations, etc.  It will act as a
   template into which the structured specification will be included
   when an Internet-Draft is created.

   The template file should include files that comprise the structured
   specification as figures at appropriate points in the draft.  The
   Markdown syntax provided by "mmark" provides a syntax for including
   code fragments [3] from external files, including the ability to
   selectively include parts of a file.

Claise, et al.          Expires December 22, 2017               [Page 8]
Internet-Draft                   SemVer                        June 2017

6.  References

6.1.  URIs

   [1] https://tools.ietf.org/html/rfc7991

   [2] https://github.com/miekg/mmark/wiki/Syntax

   [3] https://github.com/miekg/mmark/wiki/Syntax#including-code-
       fragments

Authors' Addresses

   Benoit Claise
   Cisco

   Email: bclaise@cisco.com

   Richard Barnes
   Cisco

   Email: rlb@ipv.sx

   Joe Clarke
   Cisco

   Email: jclarke@cisco.com

Claise, et al.          Expires December 22, 2017               [Page 9]