[Standards] long specs
Peter Saint-Andre
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-----
Dave Cridland
> 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:da...@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
Peter Saint-Andre
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-----
Dave Cridland
> > 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.
>
>
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.
Matthew Wild
> 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
Dave Cridland
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.
Kevin Smith
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
Peter Saint-Andre
Hash: SHA1
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-----
Alexey Melnikov
> 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.
Kurt Zeilenga
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
Wayne Franklin
I agree with Kurt. I don't think that XEP-0045 and XEP-0060 need to be split.
Wayne
Peter Saint-Andre
Hash: SHA1
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-----
Ben Langfeld
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
Matthew Wild
> 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
Peter Saint-Andre
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-----
Winfried Tilanus
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
Peter Saint-Andre
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-----