On Thu, Apr 14, 2016 at 01:46:35PM +0100, Alex Bligh wrote: > I have a proposal for the more efficient treatment of experimental > protocol extensions. This primarily concerns doc/proto.md, but > potentially affects code too. > > At present the experimental protocol extensions are described in > 'experimental extensions' at the bottom of the document in master. > This causes some issues: > > * The document is longer for those that don't want to read about > protocol extensions. > > * The document is more volatile than it might be, as each change > to an experimental extension requires a change to proto.md > and these carry a high risk of conflict. > > * The body of the document inevitably ends up referring to > the experimental extensions, which is a pain, as you only > should need to know about the experimental extensions if you > implement them. > > * Worst of all, after all the careful wordsmithing of experimental > extensions, they then need to be promoted into the main document, > (when they cease to be experimental) which requires more wordsmithing.
Yeah, I realize that now.
> My proposal is as follows:
>
> * Experimental extensions do not appear in proto.md in master at all
> EXCEPT for reservation of codes (e.g. "NBD_OPT_FOOBAR (42) - reserved
> for experimental FOOBAR extension").
>
> * Experimental extensions themselves live in a git branch. This carries
> the wording of the extension as it would be if it were incorporated
> in to the main document. Part of the change set removes the
> above text and says "NBD_OPT_FOOBAR (42) - see FOOBAR" or descibes
> it in place).
>
> * The text re NBD_OPT_FOOBAR above has a link in proto.md (in master)
> to the relevant branch's proto.md, so you can simply click through
> to find it.
>
> * Merging (and thus promoting to non-experimental) an extension is
> as simple as merging the branches.
>
> * The extension branches could then also contain code to implement
> the extension on nbd-server.c and nbd-client.c as appropriate.
>
> * This means the documentation for an experimental feature and the
> code to implement it can be kept together, and can be merged easily.
> This should reduce proposed changes to master's proto.md, and
> it means resolving conflicts is the job of those writing the
> extension (i.e. they need to effectively rebase their patches
> on master).
This sounds like a viable approach, except that currently I'm still the
only person able to merge patches, which means I get to be a bottleneck
all the time. Not ideal.
Maybe I should fix that.
Alex: according to github, you've made the second-highest number of
commits to nbd. That, plus your actions on this mailinglist mean you've
been annoying me enough to be punished for it.
Consider yourself a committer ;-)
(I'll also add you to the sourceforge project if you have an account
there and tell me what it is...)
--
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
people in the world who think they really understand all of its rules,
and pretty much all of them are just lying to themselves too.
-- #debian-devel, OFTC, 2016-02-12
signature.asc
Description: PGP signature
------------------------------------------------------------------------------ Find and fix application performance issues faster with Applications Manager Applications Manager provides deep performance insights into multiple tiers of your business applications. It resolves application problems quickly and reduces your MTTR. Get your free trial! https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
_______________________________________________ Nbd-general mailing list Nbd-general@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/nbd-general
