Re: Comments pack protocol description in "Git Community Book" (second round)

From: Jakub Narebski <jnareb@gmail.com>
Date: Jun 7, 2009, 08:21 UTC
Message-ID: <200906071021.08922.jnareb@gmail.com>
In-Reply-To: <d411cc4a0906061458g494d80dbwe3a5358edfd1d49e@mail.gmail.com>

On Sat, 6 June 2009, Scott Chacon wrote:

Show 13 quoted lines

> In addition to that, I started taking a shot at putting together an
> RFC formatted documentation of this protocol as was requested.  I may
> have _way_ missed the mark on what you were looking for originally,
> it's hard to say, not having read a lot of RFC documents - I probably
> ended up writing in a more bookish format rather than a technical
> spec, but whatever - maybe you'll find it helpful or can fix it up to
> more what you were expecting.  I'm not done with it - some of it is
> still basically unformatted comments from this previous thread, but at
> least it's laid out roughly how I thought it might be useful and I
> have fleshed out a lot of it.  You can find the RFC text output
> document here:
> 
> http://git-scm.com/gitserver.txt

[...]

> Thoughts?

Those are only preliminary thoughts; more detailed analysis is to follow (hopefully).

Usually RFC documents refer to RFC 2119 (Key words for use in RFCs to Indicate Requirement Levels) for definitions of words such as MUST, SHOULD, MAY in the following way:

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
   NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC 2119][1].

 [1]: http://tools.ietf.org/html/rfc2119

Definitions are done using RFC 5234 (Augmented BNF for Syntax 
Specifications: ABNF), referring to it for example in the following 
way:

   All the mechanisms specified in this document are described in both
   prose and an augmented Backus-Naur form (ABNF).  It is described in
   detail in [RFC 4234][2].

 [2]: http://tools.ietf.org/html/rfc5234

The description of pkt-line and pkt-line-sb formats is wrong: length includes the header. It is IMHO more natural to define it from generality to detail, and not in reverse direction; instead of this:

   pkt-length = 4HEXDIGIT   ; length of pkt-payload
   pkt-line   = pkt-length pkt-payload [ LF / CR ]

for example like this:

   pkt-line   = pkt-length pkt-payload [ LF ]
   pkt-length = 4HEXDIGIT   ; length of pkt-line (including pkt-length)

By the way, we probably accept any terminator, but I'd rather standarize on LF ("\n").

In description of sideband:

>  When a sideband is used, 2 means "progress messages, most likely
>  suitable for stderr". 1 means "pack data". 3 means "fatal error
>  message, and we're dead now".  No other channels are used or valid.

it is true that no other channels are used, but it is not true that other channels are invalid. If they are not supported by client, there are simply dropped. This opens possibility of future extension. I guess that channel 0 is invalid, because it would be understood as _input_ channel (for sending data from client to server), though.

Please correct me if I am wrong here...

P.S. Could you please try to not quote large fragments of email which you do not refer to in your reply, and which are not relevant to given post, like the long quoting at the end of your email without any word from you? Thanks in advance.

-- 
Jakub Narebski
Poland