Subject: Re: [netmod] Revision-labels within filenames

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 26 Oct 2021 13:01:16 +0000

I wanted to close on this issue.  The alternative of overloading '@' would impact current tools that have not yet been updated.  Additionally, while '#' does come with some escaping (as does '@') we have already seen that symlinks are employed in areas like GitHub to provide an un-revisioned module name.  That would work for '#' as well.

I think the proposal, therefore, is still to go with '#' to designate a revision-label is to follow.

Joe

On 9/14/21, 12:56, "Joe Clarke (jclarke)" <[email-masked]> wrote:

    On 9/14/21 12:01, Rob Wilton (rwilton) wrote:
    > Hi Joe,
    >
    > Sorry, I was on PTO for the meeting where this was discussed.  I don't think that it is great that the character needs to be encoded in a URL.  It would seem to make references to YANG files in YANG packages a lot more awkward to read/write.

    The writing here will likely still be programmatically driven, but I get
    the reading argument.  While client automation won't care, a user
    reading %233.2.3 does not as easily grok that as #3.2.3.  That said, I
    wouldn't use the URL as a means to get the revision-label.  I'd use the
    revision leaf in the package for a given module.

    >
    > Perhaps reusing '@' is pragmatically the best choice.  We already have the constraint that a revision label cannot match the format of a revision-date anyway.
    >
    > Or, alternatively, if we really want to differentiate, then could '@@' work?

    @@ was discussed, but would likely still trip up current tools that
    expect '@' followed by a revision date.  But if we're good with
    disrupting this, I'd prefer we overload the single '@'.

    Joe

    >
    > Rob
    > // As an author/contributor.
    >
    >> -----Original Message-----
    >> From: netmod <[email-masked]> On Behalf Of Joe Clarke (jclarke)
    >> Sent: 14 September 2021 15:56
    >> To: [email-masked]
    >> Subject: [netmod] Revision-labels within filenames
    >>
    >> Carsten raised a point at the mic at IETF111 that the chosen character '#' to
    >> separate the module name and module revision-label in filenames is
    >> problematic.  Currently, the YANG module versioning draft says that if you
    >> want to use revision-label within the filename, you use
    >> MODULE_NAME#REVISION_LABEL (e.g., my-module#3.2.3.yang).  The reason
    >> for a new character is not to confuse existing tools that expect a revision-
    >> date to follow '@'.
    >>
    >> Carsten mentioned that '#' causes problem with shells and within URLs.
    >> While the position of the '#' in the name does not actually trigger issues with
    >> shells (it would if the filename began with a '#'), it does indeed cause issues
    >> in URLs if it's not encoded.  For example, https://example.com/my-
    >> module#3.2.3.yang will result in a 404 since a file "my-module" does not
    >> exist.  Jan also pointed out that '#' will cause issues in Makefiles, causing
    >> developers to have to escape them.
    >>
    >> On the last meeting, the authors and contributors spent some time running
    >> down other characters options, but all have their issues and require escaping
    >> or encoding.  The consensus on that call was that the #
    >> --> %23 URL encoding won't be as burdensome as initially thought.
    >> Platforms like GitHub (or its ilk) -- which are popular for hosting modules --
    >> will do this encoding automatically and downloading the module will produce
    >> a filename with the un-encoded '#'.  Additionally, yang-library location will
    >> have the encoded version of the URL (likely generated by tooling), which
    >> clients then download and typically get the un-encoded '#'.
    >>
    >> Ultimately, we do not foresee filesystems cluttered with "%23" in filenames
    >> nor do we expect a great deal of manual typing of "%23".  Yes, the '#' will
    >> cause some additional developer work for use in Makefiles, but the authors
    >> feel this is acceptable given the overall impact of choosing another character.
    >>
    >> More details on this, including our run-down of other characters can be
    >> found in GitHub Issue #104 (https://github.com/netmod-wg/yang-ver-
    >> dt/issues/104).
    >>
    >> Joe on behalf of the YANG versioning authors and contributors
    >>
    >> _______________________________________________
    >> netmod mailing list
    >> [email-masked]
    >> https://www.ietf.org/mailman/listinfo/netmod