[Gluster-devel] Documentation expectations for 3.5 release

Tue Apr 15 07:54:57 UTC 2014

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

> 
> Regards,
> Vijay
> 
> On 04/11/2014 06:40 AM, John Mark Walker wrote:
> >Thank you, guys, for taking this on. The community will greatly benefit from this effort.
> >
> >-JM
> >
> >
> >----- Original Message -----
> >>On Thu, Apr 10, 2014 at 11:47:08PM +0530, Lalatendu Mohanty wrote:
> >>>On 04/10/2014 11:20 PM, Justin Clift wrote:
> >>>>Note, the docs go in the /doc directory in the git repo, both 3.5 and
> >>>>master branches. ;)
> >>>>
> >>>>When submitting patches to gerrit, feel free to reuse the bug-xxxx
> >>>>branch that was used for the code submission, or even use the 3.5.0
> >>>>tracker bug (1049981).
> >>>
> >>>Here is the documentation about "how to send documentation patch" :
> >>>http://www.gluster.org/community/documentation/index.php/Submitting_Documentation_Patches
> >>
> >>Lala and I have been busy filing bugs for all of the features that are
> >>listed in the email below as having missing documentation:
> >>- https://bugzilla.redhat.com/showdependencytree.cgi?id=1049981
> >>
> >>All the bugs that are *not* in POST or MODIFIED state need to file
> >>patches. The ones that are in POST could probably benefit from reviews
> >>in Gerrit (see the respective bug for details).
> >>
> >>Note that these bugs need patches submitted against the release-3.5
> >>branch, as well as the master branch. We do not want documentation lost
> >>with future releases.
> >>
> >>If you have any questions, please let us know by replying to this email,
> >>or talk to us in #gluster-dev on Freenode.
> >>
> >>Thanks,
> >>Niels
> >>
> >>
> >>>
> >>>>+ Justin
> >>>>
> >>>>On 10/04/2014, at 6:21 PM, Justin Clift wrote:
> >>>>>Hi all,
> >>>>>
> >>>>>These are the features in Gluster 3.5 still needing documentation:
> >>>>>
> >>>>>* AFR CLI enhancements
> >>>>>* Exposing Volume Capabilities <- only if this made it in, which I can't
> >>>>>see atm
> >>>>>* File Snapshots in GlusterFS
> >>>>>* gfid-access
> >>>>>* On-Wire Compression/Decompression
> >>>>>* Preventing NFS restart on volume change
> >>>>>* Quota Scalability
> >>>>>* readdir-ahead
> >>>>>* zerofill API for GlusterFS
> >>>>>* Brick Failure Detection
> >>>>>* Disk Encryption
> >>>>>* Changelog based parallel geo-replication
> >>>>>* Improved block device translator
> >>>>>* Remove brick CLI change
> >>>>>* RDMA-connection manager (RDMA-CM)
> >>>>>* Support for NUFA translator
> >>>>>* Distributed Geo-Replication
> >>>>>
> >>>>>These are the features added in Gluster 3.4, still needing documentation:
> >>>>>
> >>>>>* Write Once Read Many (WORM) volume
> >>>>>* BD Xlator - Block Device translator
> >>>>>* Duplicate Request Cache (DRC)
> >>>>>* Server-Quorum
> >>>>>* Libgfapi
> >>>>>* Eager locking
> >>>>>* oVirt 3.2 integration
> >>>>>* qemu 1.3 - libgfapi integration
> >>>>>* Access Control List - Version 3 support for Gluster NFS
> >>>>>
> >>>>>
> >>>>>All of the required documentation is *end user focused*, which includes
> >>>>>three parts:
> >>>>>
> >>>>>a) Description of what a feature does, so a user knows if it's something
> >>>>>    they'd want to use or try
> >>>>>
> >>>>>b) Exact steps on setting it up, and full list of parameters that can
> >>>>>affect
> >>>>>    it.  For example:
> >>>>>
> >>>>>      * CLI parameters (if it has them)
> >>>>>      * Volume options/parameters (if it has them)
> >>>>>      * Dependencies, (eg on other features, external programs,
> >>>>>        etc)
> >>>>>
> >>>>>c) A fully worked example.  Step by step commands with comments are
> >>>>>optimal.
> >>>>>
> >>>>>A good way to start is by doing the setup/configuration for the feature
> >>>>>in your
> >>>>>local environment, starting from a new, un-configured installation.
> >>>>>Ensure your
> >>>>>terminal program has a lot of scroll back buffer available. :)
> >>>>>
> >>>>>After the environment is fully configured, cut-n-paste the scroll back
> >>>>>buffer
> >>>>>into a text mode document editor somewhere (or an etherpad).  Then go
> >>>>>through
> >>>>>it, removing everything except the needed commands and any useful output.
> >>>>>
> >>>>>Then go through it a 2nd time, adding line feeds and headings, spacing
> >>>>>things
> >>>>>out visually for clarity, and adding comments to describe what's going on
> >>>>>and
> >>>>>why it's being done.
> >>>>>
> >>>>>This becomes the c) in the list above.  With that in place, it's
> >>>>>generally
> >>>>>pretty straight forward to next make the b) part, and then finishing off
> >>>>>with
> >>>>>a full feature description appropriate for end users (if it hasn't
> >>>>>spontaneously come to mind already).
> >>>>>
> >>>>>The text format we're using is AsciiDoc.  Quick Reference here:
> >>>>>
> >>>>>http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
> >>>>>
> >>>>>:)
> >>>>>
> >>>>>Regards and best wishes,
> >>>>>
> >>>>>Justin Clift
> >>>>>
> >>>>>--
> 