Subject: [nfsv4] high-level comments on draft-ietf-nfsv4-versioning-02

From: Mike Kupfer <[email-masked]>
Date: Mon, 04 Jan 2016 16:21:12 -0800

I've finished one pass through the document, and I'm in the middle of a
second pass.  The second pass is mostly to help me get my head wrapped
around the spec, but I'm also finding some issues (mostly typos and
such) that I missed the first time through.

It's clear that a lot of time went into writing the document, and I
can't think of any important areas that were left uncovered.  I have
some notes about technical concerns, but all in all I think they're
minor, and some of them may go away as I complete my 2nd pass through
the document.  The basic approach of using XDR to structure and detect
support for extensions seems sound to me.

As alluded to above, I did have problems building up a mental "map" of
the spec.  I think part of the problem is the bottom-up organization of
the document: it starts with definitions and low-level XDR building
blocks, then discusses features, and finally discusses versions.  I
think a top-down approach would work better.  Start with minor versions,
since that concept is already known within the working group.  Then
introduce minor version groups and explain their relationship to minor
versions.  Then introduce extensions (features and feature packages) and
their relationship to minor versions and minor version groups.  Then
introduce feature elements and the XDR specifics.

I would also move the section on documentation closer to the end,
perhaps just before the section on correcting existing minor versions
and features.  Its current location interrupts the flow of the document
and makes it harder to understand the concepts being presented.

I also found myself confused by the use of the term "minor version".
The first bullet in Section 2.3 talks about how extensions can become
"part of" a minor version.  But then there's no term to mean the minor
version without extensions.  To make matters worse, I found this usage
unconventional and counter-intuitive.  My confusion was compounded by
apparently inconsistent usage in the spec. (For example, consider the 4
bullets at the bottom of Page 13.  The first bullet uses "minor version"
to include extensions.  The fourth bullet distinguishes "minor version"
from any extensions.)  I think it would be better to use "minor version"
to mean without extensions, and to introduce a new term--perhaps
"extended minor version"--to refer to the minor version plus extensions.

cheers,
mike

---

From: David Noveck <[email-masked]>
Date: Tue, 5 Jan 2016 09:54:53 -0500

Thanks for the review.

> I think part of the problem is the bottom-up organization of the
document: it starts with definitions and low-level XDR building blocks,
then discusses features, and finally discusses versions.

I took the opposite approach in earlier versions and, at least from my
point of view, it didn't work

> I think a top-down approach would work better.  Start with minor
versions, since that concept is already known within the working group.

I don't believe the minor version concept is well-defined and understood,
even though it is in some sense "known".  That is part of why it needs to
be clearly explained in the current document.  We have three existing minor
versions and they are each different in scope and concept.  So the only way
that the concept is known is that these three very different cases are felt
in some way to be examples of a particular (unclear) concept. The problem
is that if we are to retain the concept of minor versions, other than as a
piece of history, we have to address the issue of deciding what
future minor versions might consist of.  To be able to do that, the working
group has to decide  what might or might not be allowed in a future minor
version, which requires us to establish the vocabulary that you are
suggesting we can defer.  Without that base, the only explanation of minor
versions is inevitably handwavy, and then we wind up having to give a clear
explanation to replace the initial handwavy explanation.  I think it
is better to explain the (somewhat confusing) reality up front.

> and makes it harder to understand the concepts being presented.

I'll look at making that change.  As part of it, the current section 9.3
would be moved to be part of the documentation section.

> version without extensions.

Good point.  I propose adding the following material right after the
bullets in Section.2.3.

Because of the above, there can be multiple versions that are part of a
given minor version.  Two of these are worthy of special terms:

   - The term "base minor version" denotes the minor version as originally
   defined, including all protocol elements specified in
   the minor version definition document but incorporating no extensions or
   protool corrections.
   - At any given time, the term "current minor version" denotes the minor
   version as extended and corrected by all
   documents published as Proposed Standards.

Each version which is part of a given minor version is a subset of the
current minor version an a superset of the base minor version.  When the
term "minor version" is used without one of these qualifiers,
it should refer to something which is true of all versions within that
minor version.  For example, the set of REQUIRED features in a given minor
version is the same for all versions within the minor version.

> To make matters worse, I found this usage unconventional

I have to plead guilty with an explanation.  I found that all
the conventional terminology led us to a place we don't want to be.  If a
minor version is just one thing and cannot change, we are are back in the
land of feature batching.  "*Lasciate* o*gni speranza, voi ch'entrate".*

> and counter-intuitive.

Intuitions differ.  Given the change above, does it still seem
counter-intuitive and what would make things clearer?

> My confusion was compounded by apparently inconsistent usage in the spec.
(For example, consider the 4 bullets at the bottom of Page 13.

Given the addition to 2.3 just  above, I would revise the material in
question to read:

Which of these are validly returned by the responder depends on the
status of the feature element in the minor version.  The possibilities
which can exist are listed below.

   - The protocol element is not known in the minor version.  In this
case, all implementations of the minor version MUST indicate that the
protocol element is not known.
   - The protocol element is specified as mandatory to not implement
in the minor version.  In this case as well, all implementations of
the minor version MUST indicate that the protocol element is not known
   - The protocol element is defined as part of the current minor
version but is not part of the base minor version.  In this case, the
requester can encounter situations in which the protocol element is
not known, is known but not supported, or is supported.
   - The protocol element is defined as an OPTIONAL part of the base
minor version.  In this case, the requester can expect the protocol
element to be known but must deal with cases in which it is supported
or not supported.
   - The protocol element is defined as a REQUIRED part of the base
minor version.  In this case, the requester can expect the protocol
element to be both known and supported by the responder.

Does this help?

On Mon, Jan 4, 2016 at 7:21 PM, Mike Kupfer <[email-masked]> wrote:

> _______________________________________________
> nfsv4 mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/nfsv4
>

---

From: Mike Kupfer <[email-masked]>
Date: Tue, 05 Jan 2016 17:48:41 -0800

David Noveck wrote:

> even though it is in some sense "known".

Fair enough.  The idea of a major version number and minor version
number is understood, I think.  But I agree that the concept as a whole,
especially what is appropriate to go into a minor version, is not
well-defined.

> the working group has to decide what might or might not be allowed in
> a future minor version, which requires us to establish the vocabulary
> that you are suggesting we can defer.  Without that base, the only
> explanation of minor versions is inevitably handwavy, and then we wind
> up having to give a clear explanation to replace the initial handwavy
> explanation.  I think it is better to explain the (somewhat confusing)
> reality up front.

I still think that more of the skeleton of the overall system--how the
pieces fit together--needs to be shown early on.  Perhaps all that's
needed is some rework of Section 2.  I'll work on some text, with a due
date of next week (though I'll try to have something earlier).

> would be moved to be part of the documentation section.

That sounds fine.

>    documents published as Proposed Standards.

I'm happy with "base minor version" and "current minor version".

> current minor version an a superset of the base minor version.

I'm a little uneasy about "part of a given minor version", but I think
this is good enough to run with for now.

> When the

I still have concerns about using "minor version" this way.  Between the
length of the document and the unconventional use of the term, I expect
confusion to result.  Unfortunately, I'm not sure I have anything better
to offer, particularly since the term "minor version group" is already
taken.  (We could introduce some other term like "minor version family",
but then there's going to be confusion about "family" versus "group", so
I don't think that's a fruitful direction to go in.)

I guess I can live with it for now.  If we don't come up with something
better, one of the final review passes should be to ensure that the
document only uses the bare "minor version" in a way that is consistent
with this definition.

> element to be both known and supported by the responder.

Yes, thanks.  For the first bullet, I would prefer "the current minor
version" over just "the minor version".  For the second bullet, since
the mandatory-to-not-implement status only changes at a minor version
boundary, I'm okay with just "the minor version".  And bullets 3-5 look
fine to me.

thanks,
mike

---

From: David Noveck <[email-masked]>
Date: Wed, 6 Jan 2016 10:32:10 -0500

> Unfortunately, I'm not sure I have anything better

I looked at "set", "class", "field" and "space" and those don't work.

I think the fundamental problem we're dealing with is that a minor version
was once a single thing and is now collection of things.  There is some
degree of confusion inherent in
that shift, which having different words for different sort of collections
is not going to help.  I think using the word "version" the way it is used
in -02 may be making the issue worse.

Here's an alternate formulation to consider:

   - A given minor version may consist of multiple instances which differ,
   within certain limits, as to their set of known protocol elements
   - Examples are the base instance and the current instance of a given
   minor version.
   - Similarly, multiple implementations of the same instance, while they
   have the same known elements, may differ as to the set of supported
   protocol elements.

This would make the hierarchy look like this

   - major version
   - (minor) version group
         - minor version
            - instance
               - implementation

---

From: Mike Kupfer <[email-masked]>
Date: Wed, 06 Jan 2016 13:20:21 -0800

> This would make the hierarchy look like this

Yes, I like this.

thanks,
mike

---

From: Mike Kupfer <[email-masked]>
Date: Mon, 11 Jan 2016 17:18:55 -0800

> date of next week (though I'll try to have something earlier).

I eventually settled on a bunch of edits to the first part of Section
2.  I deferred suggesting any changes to Section 2.3; perhaps the change
in terms that we discussed earlier will be sufficient.

regards,
mike

-----8<-----8<-----
2.  Terminology

   A basic familiarity with NFSv4 terminology is assumed in this
   document and the reader is pointed to [RFC7530].

   In this document, the term "version" is not limited to minor
   versions.  When minor versions are meant, the term "minor version" is
   used explicitly.  For more discussion of this and related terms, see
   Section 2.3

   In this document, the word "feature" is used, except in the case of
   quotations, to denote a key structuring concept.  By organizing
   changes into features, defining RFCs can clearly specify what
   protocol elements a server must be able to recognize and what
   protocol elements a server must support.  See Section 6 for more
   details.

   A feature contains one or more "feature elements".  Often, at least
   one feature element will be a protocol extension that can help a
   sender determine whether the receiver supports a given feature.
   See Section 4.1.3 for more details.  A feature element may also be
   some other type of protocol change as described in Section 5.

   A "feature package" is a set of features that are defined together,
   either as part of a minor version or as part of the same protocol
   extension.

   We also need to introduce our vocabulary regarding specification of
   features and minor versions.  Given the ongoing shift to a finer-
   grained documentation model, it is important to be clear here.

   o  The term "minor version definition document" denotes the principal
      document defining a specific NFSv4 minor version.  It may be in
      the form of a complete protocol definition (e.g.  [RFC7530],
      [RFC5661]), a specification of changes relative to the previous
      minor version (e.g.  [NFSv42]), or in a document that specifies
      the features to be included, either by referencing their
      definition document normatively (see Section 10.4) or implicitly
      (see Section 9).

   o  The term "minor version documentation" includes the minor version
      definition document but also includes any corresponding XDR
      definition documents if they are published separately (e.g.
      [RFC7531], [RFC5662], [NFSv42-dot-x]).  Also included are
      documents separately specifying features newly incorporated in the
      minor version and the ancillary documents described in
      Section 9.3.

   o  The term "feature definition document" denotes a document
      describing a single feature or a set of closely related features,
      forming a feature package.

   o  The term "protocol definition document" denotes a minor version
      definition document, a feature definition document or any
      standards-track document updating one of these.

----->8----->8-----

mike