[Gluster-devel] Documentation expectations for 3.5 release

Jeff Darcy jdarcy at redhat.com
Tue Apr 15 22:09:04 UTC 2014


> > We all get that poor documentation hurts the project.  Some of us have
> > even tried to do something about that.  Most of us also realize that
> > releases dragging on too long *also* hurt the project in a variety of
> > ways.  Having to maintain an active current-release branch in addition
> > to master is a drag on development.  Users are ill served by being
> > unable to get fixes for actual bugs in easily consumable form.  We're
> > dealing with a tradeoff here, not something where one side gets to put
> > on a white hat and jam the black hat on somebody else.
> 
> Ok.  Hadn't really thought of 3.5 as a "fix" for 3.4 bugs.  Kind of
> thought 3.4.x series was for that.  So what you're saying is that
> 3.5 isn't just about releasing new features, it's also a more stable/better
> platform for people to run on?

That is generally true of every new release.  Fixes are backported *if
the benefit outweighs the risk* but are always present in the new release.
Some bugs aren't so much fixed as made irrelevant by refactoring.  Some
fixes have dependencies on other new code.  Whatever the reason, whether
it's more about risk or more about effort, there will always be some fixes
that don't go into older releases.

> > I'm deliberately not taking a position on whether or not we should
> > release with the documentation in its current state.  All I'm saying
> > is that making inequitable demands of one another, or trying to
> > portray one another as failing to appreciate users' needs, hurts
> > the project even more than either poor documentation or late
> > releases.  That's an issue on which I *am* willing to take a stand.
> 
> If people have things they _need_ that are only in 3.5 then I can
> definitely understand they're going to be unhappy with a delay.
> 
> But won't they also be unhappy with a 3.5 release where the features
> they want don't have docs?

Sure they will.  The question is which kind of unhappiness will be
worse for them, or for the project.  The answers are not simple.  I've
seen reasonable arguments for both sides.  We need to do two things
that will make our users happier; the only debate is about the order.

> Put it this way... my thinking is that at the moment the "lack of docs
> in Gluster 3.5" is a *developer* problem, not a user one.  If we
> release 3.5 without (even basic) docs for *all* of the new features,
> we've just promoted it to a user problem *as well as* a developer
> problem.

It's a developer problem *and* a user problem either way.




More information about the Gluster-devel mailing list