On Mon, Mar 14, 2011 at 10:51 AM, Michael Meffie <[email protected]> wrote: > Simon Wilkinson wrote: >> >> [On afs3-standardisation, Andrew wrote: ] >> >>>> However, that does not preclude a specification, which raises >>>> another question: can/should we publish OpenAFS-specific standards? >>>> If we make I-Ds that clearly demarcate themselves as for OpenAFS and >>>> not AFS-3 in general, it would seem valuable as a standard >>>> specification for these kinds of things. The same thing could go for >>>> the Ubik voting/beacon protocols, cmdebug, and other things that so >>>> far have appeared to be considered "internal" to OpenAFS, but still >>>> travel over the wire. >> >> [and Tom replied ... ] >> >>> As one of the people Andrew spoke with about this earlier today, I'd >>> like to second this proposal. Even if we merely use the I-D format-- >>> yet publish via our own OpenAFS-specific document submission stream-- >>> I think there would be a lot of value in formalizing the process of >>> changing/documenting OpenAFS-specific behavior. >> >> This is the wrong place to be having this discussion - it really >> belongs on the OpenAFS lists. I've CC'd openafs-devel with this >> response, hopefully we can continue this discussion there. >> >> I have a number of concerns with this approach. Firstly, it's >> important to note that I-Ds are not an archival document series. >> Publishing an I-D may serve as a useful, if heavyweight, means of >> encouraging discussion, but it does nothing in terms of ensuring that >> the document is available in the future. The only way to do so is to >> advance the I-D to an RFC. However, discussing OpenAFS implementation >> details within the RFC series is definitely inappropriate. >> >> Secondly, we already have a mechanism for discussing code changes to >> OpenAFS, and I can't see why structure changes can't use that same >> mechanism. If it's an OpenAFS implementation detail, then surely it >> should be decided in exactly the same way as every other OpenAFS >> implementation detail. If a better form of documentation is required, >> then I would much rather that that documentation lived within the >> source tree, than in some location on the web that's subject to a far >> worse degree of bit rot. We've already discussed, at length, on how we >> should be using openafs-devel for design review in advance of coding, >> and this seems like just another instance of that. > > Hello Simon, > > I think we are all in agreement these structures need to be documented, > and since debugging information is inherently implementation specific, > I do agree this documentation should be the responsibility of the > implementers. > > I think initially (when this thread first started), the intention was > to fully document anything and everything with respect to AFS client > and servers transmitted over the wire. However, some structures are > completely implementation specific. Such as the structures from the > cmdebug output, as Jeff and others have pointed out. The rxdebug > structures seem to fit within that realm. I think when I started this > thread so long ago, my understanding was was mistaken in that the rxdebug > information was to be documented as part of the Rx layer, which is why > we started the discussion here.
The problem is there are actually 3 classes of things to be documented: 1) Rx itself. This isn't even (just) a question for AFS implementors, but at least needs to be addressed in a body like afs3-stds. 2) AFS3 extensions. The initial point of afs3-stds. 3) Implementation-specific details. Aside from where feedback from a larger community of implementors might provide perspective missing (did someone else solve this already and it's not widely known?) this is really an "internal" matter for whichever implementation. > Personally, at this point I do think the debugging or introspection > structures are inherently implementation (and version) specific, and > should be out-of-scope for afs3 standardization, and should be > documented as part of an implementation. It would be important for > afs3 I-Ds to explicitly document such portions are implementation > specific and may change from version to version. Actually, I'd think that would be limited to disclaiming items which are explicitly not standardized (for afs3) and thus up to implementations. > I suppose, I would > expect some standard mechanism to at least identify an implementation > level but the debugging data would be opaque from the AFS3 point of view. An extensible, tagged implementation-specific debug payload (both request and reply) would be as much as I would expect afs3 (in the guise of 1, not 2, above) to be involved. -- Derrick _______________________________________________ OpenAFS-devel mailing list [email protected] https://lists.openafs.org/mailman/listinfo/openafs-devel
