Re: [Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 2/27/12 4:02 PM, Peter Saint-Andre wrote: > On 2/15/12 1:07 PM, Peter Saint-Andre wrote: >> On 2/15/12 12:48 PM, Kurt Zeilenga wrote: > >>> On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: > I'd be willing to work on this, but I want to make sure that people think there's value in doing so. > >>> Personally, I not sure what I hate more, overly long documents >>> or specifications unnecessarily split over multiple documents. > >>> I don't consider XEP 45 or XEP 60 to be overly long. > >> Half the feedback I receive is (a) it's too hard to read a long >> spec. The other half is (b) it's too hard to read multiple >> specs. For XEP-0060, the feedback is heavily weighted toward (a). >> For XEP-0045, it's about evenly weighted. My conclusion is that >> we really need to split up XEP-0060, and that splitting XEP-0045 >> into user vs. admin use cases would be helpful. > > Over the weekend I took a rough cut at splitting up XEP-0045. > Here's what I came up with (page lengths are based on print-to-PDF > in Firefox): > > XEP-0045 = 141 pages > > Architecture, Requirements, Discovery, Security = 35 pages > > Occupant Use Cases = 56 pages > > Administration = 68 pages Because more than one person has asked about the split files, I've placed them here: http://www.saint-andre.com/jabber/tmp/muc-arch.html http://www.saint-andre.com/jabber/tmp/muc-occupant.html http://www.saint-andre.com/jabber/tmp/muc-admin.html Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk9NN+oACgkQNL8k5A2w/vwYKACgkVYFy00xLTlppsW/KJl0yk8u lc0AoNe44vM9zidMpipzOho74jncGE4N =Ia5C -END PGP SIGNATURE-
Re: [Standards] long specs
On 02/28/2012 12:02 AM, Peter Saint-Andre wrote: Hi, > Over the weekend I took a rough cut at splitting up XEP-0045. > Here's what I came up with (page lengths are based on print-to-PDF > in Firefox): > > XEP-0045 = 141 pages > > Architecture, Requirements, Discovery, Security = 35 pages > > Occupant Use Cases = 56 pages > > Administration = 68 pages > > The document that most client developers would read is the one on > occupant use cases. Would they find 56 pages less intimidating > than 141 pages? Probably. (And probably we could move some stuff > out of the occupant use cases -- requesting voice, that kind of > thing.) Would it be worth our time to split things up this way? > Perhaps. For me a split up like this, would have no added value. We need all three parts, having them in one (long) document makes things for me more easy to oversee. Winfried
Re: [Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 2/15/12 1:07 PM, Peter Saint-Andre wrote: > On 2/15/12 12:48 PM, Kurt Zeilenga wrote: > >> On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: > >>> I'd be willing to work on this, but I want to make sure that >>> people think there's value in doing so. > >> Personally, I not sure what I hate more, overly long documents >> or specifications unnecessarily split over multiple documents. > >> I don't consider XEP 45 or XEP 60 to be overly long. > > Half the feedback I receive is (a) it's too hard to read a long > spec. The other half is (b) it's too hard to read multiple specs. > For XEP-0060, the feedback is heavily weighted toward (a). For > XEP-0045, it's about evenly weighted. My conclusion is that we > really need to split up XEP-0060, and that splitting XEP-0045 into > user vs. admin use cases would be helpful. Over the weekend I took a rough cut at splitting up XEP-0045. Here's what I came up with (page lengths are based on print-to-PDF in Firefox): XEP-0045 = 141 pages Architecture, Requirements, Discovery, Security = 35 pages Occupant Use Cases = 56 pages Administration = 68 pages The document that most client developers would read is the one on occupant use cases. Would they find 56 pages less intimidating than 141 pages? Probably. (And probably we could move some stuff out of the occupant use cases -- requesting voice, that kind of thing.) Would it be worth our time to split things up this way? Perhaps. Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk9MC2kACgkQNL8k5A2w/vxtXgCdEcshiapn1LRQT79pwrQ0k6QO 4+AAoM3YYDxYJvoHAzsKtuF47LYLKOow =slhU -END PGP SIGNATURE-
Re: [Standards] long specs
On 15 February 2012 22:47, Ben Langfeld wrote: > I like the idea of splitting out non-essential elements of XEP-0045 > into separate documents. I can then say my code fully implements > MUC-basic, but not MUC-admin, etc. > > As for the versioning issue. Why not have XEPs follow semver? They sort of do (and sort of don't). See for example: http://xmpp.org/extensions/xep-0045.html#appendix-revs However XEP-0001 mandates that Draft == 1.0, and Final == 2.0, regardless of the actual changes made between the status change. I don't have strong feeling about "fixing" this, since namespaces are our mechanism for versioning different incompatible versions of the same protocol. XEP-0001 doesn't mention the distinction between which changes should increment the second component and which the third component of the version. Again, I'm not sure it's something we need to change. Finally, we already use rc numbers for candidate changes to an existing XEP: http://xmpp.org/extensions/diff/api/xep/0045/diff/1.25/vs/1.25rc9 . Typically these "interim" versions are quite short-lived, and I'm not sure anyone would really implement them from an interim document. What I believe Dave is referring to is essentially keeping the interim versions around for longer, and making them more public - expecting people to implement them before they become the next "official" version of the XEP. Personally I find that a bit over the top... one version of a XEP works well enough in my opinion. If we really want to make such drastic changes to a XEP that we're concerned about replacing an existing stable version, we really should make the changes a new XEP. We're not going to run out of numbers just yet :) Regards, Matthew
Re: [Standards] long specs
I like the idea of splitting out non-essential elements of XEP-0045 into separate documents. I can then say my code fully implements MUC-basic, but not MUC-admin, etc. As for the versioning issue. Why not have XEPs follow semver? Regards, Ben Langfeld On 15 February 2012 20:07, Peter Saint-Andre wrote: > -BEGIN PGP SIGNED MESSAGE- > Hash: SHA1 > > On 2/15/12 12:48 PM, Kurt Zeilenga wrote: >> >> On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: >> >>> I'd be willing to work on this, but I want to make sure that >>> people think there's value in doing so. >> >> Personally, I not sure what I hate more, overly long documents or >> specifications unnecessarily split over multiple documents. >> >> I don't consider XEP 45 or XEP 60 to be overly long. > > Half the feedback I receive is (a) it's too hard to read a long spec. > The other half is (b) it's too hard to read multiple specs. For > XEP-0060, the feedback is heavily weighted toward (a). For XEP-0045, > it's about evenly weighted. My conclusion is that we really need to > split up XEP-0060, and that splitting XEP-0045 into user vs. admin use > cases would be helpful. > > Peter > > - -- > Peter Saint-Andre > https://stpeter.im/ > > > -BEGIN PGP SIGNATURE- > Version: GnuPG v1.4.8 (Darwin) > Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ > > iEYEARECAAYFAk88EG8ACgkQNL8k5A2w/vyaOwCfUBBv7bE94Om9ImDOoeIQmiTi > 8a8AoLqKW6ul2QrXIuhMZJEWVILGjXVt > =x30E > -END PGP SIGNATURE-
Re: [Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 2/15/12 12:48 PM, Kurt Zeilenga wrote: > > On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: > >> I'd be willing to work on this, but I want to make sure that >> people think there's value in doing so. > > Personally, I not sure what I hate more, overly long documents or > specifications unnecessarily split over multiple documents. > > I don't consider XEP 45 or XEP 60 to be overly long. Half the feedback I receive is (a) it's too hard to read a long spec. The other half is (b) it's too hard to read multiple specs. For XEP-0060, the feedback is heavily weighted toward (a). For XEP-0045, it's about evenly weighted. My conclusion is that we really need to split up XEP-0060, and that splitting XEP-0045 into user vs. admin use cases would be helpful. Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk88EG8ACgkQNL8k5A2w/vyaOwCfUBBv7bE94Om9ImDOoeIQmiTi 8a8AoLqKW6ul2QrXIuhMZJEWVILGjXVt =x30E -END PGP SIGNATURE-
Re: [Standards] long specs
On Feb 15, 2012, at 2:48PM, Kurt Zeilenga wrote: > > On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: > >> I'd be willing to work on this, but I want to make sure that people >> think there's value in doing so. > > Personally, I not sure what I hate more, overly long documents or > specifications unnecessarily split over multiple documents. > > I don't consider XEP 45 or XEP 60 to be overly long. > > -- Kurt > > I agree with Kurt. I don't think that XEP-0045 and XEP-0060 need to be split. Wayne
Re: [Standards] long specs
On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote: > I'd be willing to work on this, but I want to make sure that people > think there's value in doing so. Personally, I not sure what I hate more, overly long documents or specifications unnecessarily split over multiple documents. I don't consider XEP 45 or XEP 60 to be overly long. -- Kurt
Re: [Standards] long specs
On 15/02/2012 16:35, Dave Cridland wrote: b) I'd like to be able to have the ability to enter a XEP that's been hived off from another mature XEP (or RFC) directly into Draft, for instance. This has come up previously. Sounds sensible to me.
Re: [Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 2/15/12 10:17 AM, Kevin Smith wrote: > On Wed, Feb 15, 2012 at 5:15 PM, Dave Cridland > wrote: >> On Wed Feb 15 17:00:18 2012, Matthew Wild wrote: >>> >>> On 15 February 2012 16:39, Dave Cridland >>> wrote: On Wed Feb 15 16:38:27 2012, Peter Saint-Andre wrote: > >> a) I'd like to be able to have "stable" and "working" >> copies of the same spec, particularly for major revisions >> like XEP-0045 is currently going through. > > I think this is a matter of best practices for how the spec > authors work, i.e., placing interim versions in a source > control branch. > > There are informal methods for handling this, yes - I think we'd benefit from formal ones. >>> >>> I'm not overly keen on this. Could you describe a bit more what >>> a world where we implement this looks like? Multiple live >>> versions of the same spec seems... a step in the wrong >>> direction. >> >> >> RFC 822 is an Internet Standard (STD 11) >> >> RFC 2822 was a Proposed Standard, which obsoleted RFC 822. >> >> RFC 5322 obsoletes 2822, and is a Draft Standard. >> >> So we're in the interesting position of having a "standard" which >> is obsoleted twice over. This is rather weird - and a bit sucky. >> >> In the XMPP world, this doesn't happen - we only have XEP-0045. >> But for lengthy revision processes, I think having actual >> published sub-versions would make more sense - that is, we have >> XEP-0045, but we also have (say) XEP-0045-1 which might be >> Experimental. It'd allow review cycles to be shorter, but also >> allow the "newer" spec to be seen at an easy to find location. >> >> For a similar example, look at the progression of >> draft-ietf-xmpp-3920bis-XX against RFC 3920. The drafts weren't >> stable (we considered them equivalent in principle to an >> Experimental XEP), up until RFC 6120 was published, when RFC 3920 >> effectively vanished. But it meant that in most cases, we could >> do incremental reviews. > > But this works with what we have, doesn't it? Peter often posts RC > versions, which work with Tobias's fancy XEP-diff tool, and which > we can review in full, etc. etc. Yeah, I think that works fine. We just need to start putting those interim versions in a source control branch so that they don't get published accidentally. Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk878loACgkQNL8k5A2w/vyLXgCeNcfHDFO9a4uSEWD8+7khYbkm H2gAnR38f1mXRtIMem6v36zrwQwdFjBh =Mduv -END PGP SIGNATURE-
Re: [Standards] long specs
On Wed, Feb 15, 2012 at 5:15 PM, Dave Cridland wrote: > On Wed Feb 15 17:00:18 2012, Matthew Wild wrote: >> >> On 15 February 2012 16:39, Dave Cridland wrote: >> > On Wed Feb 15 16:38:27 2012, Peter Saint-Andre wrote: >> >> >> >> > a) I'd like to be able to have "stable" and "working" copies of the >> >> > same spec, particularly for major revisions like XEP-0045 is >> >> > currently going through. >> >> >> >> I think this is a matter of best practices for how the spec authors >> >> work, i.e., placing interim versions in a source control branch. >> >> >> >> >> > There are informal methods for handling this, yes - I think we'd benefit >> > from formal ones. >> > >> >> I'm not overly keen on this. Could you describe a bit more what a >> world where we implement this looks like? Multiple live versions of >> the same spec seems... a step in the wrong direction. > > > RFC 822 is an Internet Standard (STD 11) > > RFC 2822 was a Proposed Standard, which obsoleted RFC 822. > > RFC 5322 obsoletes 2822, and is a Draft Standard. > > So we're in the interesting position of having a "standard" which is > obsoleted twice over. This is rather weird - and a bit sucky. > > In the XMPP world, this doesn't happen - we only have XEP-0045. But for > lengthy revision processes, I think having actual published sub-versions > would make more sense - that is, we have XEP-0045, but we also have (say) > XEP-0045-1 which might be Experimental. It'd allow review cycles to be > shorter, but also allow the "newer" spec to be seen at an easy to find > location. > > For a similar example, look at the progression of draft-ietf-xmpp-3920bis-XX > against RFC 3920. The drafts weren't stable (we considered them equivalent > in principle to an Experimental XEP), up until RFC 6120 was published, when > RFC 3920 effectively vanished. But it meant that in most cases, we could do > incremental reviews. But this works with what we have, doesn't it? Peter often posts RC versions, which work with Tobias's fancy XEP-diff tool, and which we can review in full, etc. etc. /K
Re: [Standards] long specs
On Wed Feb 15 17:00:18 2012, Matthew Wild wrote: On 15 February 2012 16:39, Dave Cridland wrote: > On Wed Feb 15 16:38:27 2012, Peter Saint-Andre wrote: >> >> > a) I'd like to be able to have "stable" and "working" copies of the >> > same spec, particularly for major revisions like XEP-0045 is >> > currently going through. >> >> I think this is a matter of best practices for how the spec authors >> work, i.e., placing interim versions in a source control branch. >> >> > There are informal methods for handling this, yes - I think we'd benefit > from formal ones. > I'm not overly keen on this. Could you describe a bit more what a world where we implement this looks like? Multiple live versions of the same spec seems... a step in the wrong direction. RFC 822 is an Internet Standard (STD 11) RFC 2822 was a Proposed Standard, which obsoleted RFC 822. RFC 5322 obsoletes 2822, and is a Draft Standard. So we're in the interesting position of having a "standard" which is obsoleted twice over. This is rather weird - and a bit sucky. In the XMPP world, this doesn't happen - we only have XEP-0045. But for lengthy revision processes, I think having actual published sub-versions would make more sense - that is, we have XEP-0045, but we also have (say) XEP-0045-1 which might be Experimental. It'd allow review cycles to be shorter, but also allow the "newer" spec to be seen at an easy to find location. For a similar example, look at the progression of draft-ietf-xmpp-3920bis-XX against RFC 3920. The drafts weren't stable (we considered them equivalent in principle to an Experimental XEP), up until RFC 6120 was published, when RFC 3920 effectively vanished. But it meant that in most cases, we could do incremental reviews. Our system works great up until Draft, basically, but after that things get awkward. Dave. -- Dave Cridland - mailto:d...@cridland.net - xmpp:d...@dave.cridland.net - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/ - http://dave.cridland.net/ Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade
Re: [Standards] long specs
On 15 February 2012 16:39, Dave Cridland wrote: > On Wed Feb 15 16:38:27 2012, Peter Saint-Andre wrote: >> >> > a) I'd like to be able to have "stable" and "working" copies of the >> > same spec, particularly for major revisions like XEP-0045 is >> > currently going through. >> >> I think this is a matter of best practices for how the spec authors >> work, i.e., placing interim versions in a source control branch. >> >> > There are informal methods for handling this, yes - I think we'd benefit > from formal ones. > I'm not overly keen on this. Could you describe a bit more what a world where we implement this looks like? Multiple live versions of the same spec seems... a step in the wrong direction. Regards, Matthew
Re: [Standards] long specs
On Wed Feb 15 16:38:27 2012, Peter Saint-Andre wrote: > a) I'd like to be able to have "stable" and "working" copies of the > same spec, particularly for major revisions like XEP-0045 is > currently going through. I think this is a matter of best practices for how the spec authors work, i.e., placing interim versions in a source control branch. There are informal methods for handling this, yes - I think we'd benefit from formal ones. > b) I'd like to be able to have the ability to enter a XEP that's > been hived off from another mature XEP (or RFC) directly into > Draft, for instance. This has come up previously. Yes, we need that. Dave. -- Dave Cridland - mailto:d...@cridland.net - xmpp:d...@dave.cridland.net - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/ - http://dave.cridland.net/ Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade
Re: [Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 2/15/12 9:35 AM, Dave Cridland wrote: > On Wed Feb 15 16:26:25 2012, Peter Saint-Andre wrote: >> We have two really long specs: XEP-0045 and XEP-0060. >> >> In the XMPP Council meeting just now, we talked about some ways >> to shorten these documents. >> >> The rough consensus seemed to be that for XEP-0045 we could >> probably move the moderator/admin/owner use cases to a separate >> spec. A quick visual comparison of the following two URLs >> indicates that we'd cut about 40% (or more) of XEP-0045 by doing >> that: >> >> http://xmpp.org/extensions/xep-0045.html#moderator >> >> http://xmpp.org/extensions/xep-0045.html#statuscodes >> >> Notice also the length of these sections: >> >> http://xmpp.org/extensions/xep-0045.html#registrar-formtype >> http://xmpp.org/extensions/xep-0045.html#schemas-admin >> http://xmpp.org/extensions/xep-0045.html#schemas-owner >> >> I'd be willing to work on this, but I want to make sure that >> people think there's value in doing so. >> >> Ralph Meijer might post separately about XEP-0060. > > I'm happy with splitting these up, but can we also manage to sort > out some related updates to XEP-0001: > > a) I'd like to be able to have "stable" and "working" copies of the > same spec, particularly for major revisions like XEP-0045 is > currently going through. I think this is a matter of best practices for how the spec authors work, i.e., placing interim versions in a source control branch. > b) I'd like to be able to have the ability to enter a XEP that's > been hived off from another mature XEP (or RFC) directly into > Draft, for instance. This has come up previously. Yes, we need that. Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk8734MACgkQNL8k5A2w/vyYiQCgqEylSmab3FyyoJmTy1s1O1hh TFEAoJYedTE2ZXbgXGht7yC57M4Kv9Q1 =dIVE -END PGP SIGNATURE-
Re: [Standards] long specs
On Wed Feb 15 16:26:25 2012, Peter Saint-Andre wrote: We have two really long specs: XEP-0045 and XEP-0060. In the XMPP Council meeting just now, we talked about some ways to shorten these documents. The rough consensus seemed to be that for XEP-0045 we could probably move the moderator/admin/owner use cases to a separate spec. A quick visual comparison of the following two URLs indicates that we'd cut about 40% (or more) of XEP-0045 by doing that: http://xmpp.org/extensions/xep-0045.html#moderator http://xmpp.org/extensions/xep-0045.html#statuscodes Notice also the length of these sections: http://xmpp.org/extensions/xep-0045.html#registrar-formtype http://xmpp.org/extensions/xep-0045.html#schemas-admin http://xmpp.org/extensions/xep-0045.html#schemas-owner I'd be willing to work on this, but I want to make sure that people think there's value in doing so. Ralph Meijer might post separately about XEP-0060. I'm happy with splitting these up, but can we also manage to sort out some related updates to XEP-0001: a) I'd like to be able to have "stable" and "working" copies of the same spec, particularly for major revisions like XEP-0045 is currently going through. b) I'd like to be able to have the ability to enter a XEP that's been hived off from another mature XEP (or RFC) directly into Draft, for instance. This has come up previously. Any interest? Dave. -- Dave Cridland - mailto:d...@cridland.net - xmpp:d...@dave.cridland.net - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/ - http://dave.cridland.net/ Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade
[Standards] long specs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 We have two really long specs: XEP-0045 and XEP-0060. In the XMPP Council meeting just now, we talked about some ways to shorten these documents. The rough consensus seemed to be that for XEP-0045 we could probably move the moderator/admin/owner use cases to a separate spec. A quick visual comparison of the following two URLs indicates that we'd cut about 40% (or more) of XEP-0045 by doing that: http://xmpp.org/extensions/xep-0045.html#moderator http://xmpp.org/extensions/xep-0045.html#statuscodes Notice also the length of these sections: http://xmpp.org/extensions/xep-0045.html#registrar-formtype http://xmpp.org/extensions/xep-0045.html#schemas-admin http://xmpp.org/extensions/xep-0045.html#schemas-owner I'd be willing to work on this, but I want to make sure that people think there's value in doing so. Ralph Meijer might post separately about XEP-0060. Peter - -- Peter Saint-Andre https://stpeter.im/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.8 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk873LEACgkQNL8k5A2w/vyESgCg8yF0UCmUj4ByeRX5f4jrkmc7 Ar4AoIbq3BRwQN1Xaf2oUQP5rtLK/Wj8 =Zj2k -END PGP SIGNATURE-
