[Gluster-devel] Documentation expectations for 3.5 release

[Vijay Bellur]

On 04/15/2014 07:36 AM, Justin Clift wrote:
> On 15/04/2014, at 11:28 AM, Lalatendu Mohanty wrote:
>> On 04/15/2014 01:24 PM, Niels de Vos wrote:
>>> On Tue, Apr 15, 2014 at 12:12:22AM -0700, Vijay Bellur wrote:
>>>> Thank you all for your efforts in arriving at better user documentation.
>>>>
>>>> Since we did not do a thorough job of blocking patches that did not
>>>> have adequate updates to the admin guide in the run upto 3.5.0, it
>>>> certainly seems difficult to get all admin-guide content ready in
>>>> short
>>>> order. Hence I think it might be prudent to treat the documentation
>>>> bugs as blockers for 3.5.1. There is documentation for most features
>>>> mentioned in the bugs in some form (git commit messages, feature
>>>> pages, blog posts) etc.It might be a good idea to consolidate all
>>>> such links in one place.
>>>>
>>>> My preference would be to release 3.5.0 and ensure that our admin
>>>> guide is ready in terms of content by 3.5.1.
>>>  From my understanding, the demand for documentation was that it gets
>>> included in the sources, not necessarily in the Admin Guide. But anyway,
>>> it seems that getting the documentation isn't that quick for all new
>>> features.
>>>
>>> The blocker for 3.5.1 already has some needed fixes listed:
>>> - https://bugzilla.redhat.com/show_bug.cgi?id=glusterfs-3.5.1
>>> - https://bugzilla.redhat.com/showdependencytree.cgi?hide_resolved=1&id=glusterfs-3.5.1
>>>
>>> Getting a 3.5.0 out now and release a doc+bugfix update relatively
>>> quickly (target in 2 months?) would have my preference.
>>>
>>> Thanks,
>>> Niels
>>
>> We can release 3.5 and move the doc blockers to 3.5.1 as an exception for 3.5 as we had not decided about doc blockers in the beginning of the 3.5 planning.  IMO for future releases , docs should be treated as blockers with all seriousness.
>
>
> I'm completely against releasing 3.5.0 until the documentation is in the
> repo.
>
> Punting it to 3.5.1 isn't going to help people.  We need to fix our
> most immediate documentation problem right here, right now, before
> moving forward.
>

Here is an analysis of features that need documentation as per the 3.5.0 
tracker (only considering bugs in new/assigned state):


1. Features in 3.4 or earlier
----------------------------

  RDMA-connection manager (RDMA-CM)
  Support for NUFA translator
  Write Once Read Many (WORM) volume
  BD Xlator - Block Device translator
  Duplicate Request Cache (DRC)
  Server-Quorum
  Libgfapi
  Access Control List - Version 3 support for Gluster NFS
  Eager locking

2. Features already documented
-------------------------------

  Distributed Geo-Replication
  On-Wire Compression/Decompression
  Changelog based parallel geo-replication

3. Features not requiring end user documentation
------------------------------------------------

Exposing Volume Capabilities - did not make it to 3.5.
gfid-access - not an end user visible feature
Preventing NFS restart on volume change - no change in configuration


4. Other features
------------------

We already have some detail online, mostly in gerrit but hey that is 
still consumable!

* AFR CLI enhancements
* readdir-ahead
* Quota Scalability - mostly the same as previous admin guide, soft 
quota configuration to be covered
* Disk Encryption
* Improved block device translator
* zerofill API for GlusterFS

I do not think holding 3.5.0 back for documentation backlog that has not 
been covered earlier is right. I certainly think that there's no one 
stroke of the brush that can fix all our documentation limitations. 
Given that we have adequate information available (in some form) for 
features in 3.5, I am still inclined to move these bugs as blockers for 
3.5.1 and go ahead with 3.5.0 as it exists today.

Let us ensure that we do not run into the same problem with 3.6.

-Vijay

[1] http://review.gluster.org/6044
[2] http://review.gluster.org/4519
[3] http://review.gluster.org/4667
[4] http://review.gluster.org/4809
[5] http://review.gluster.org/5327