[Gluster-devel] Documentation expectations for 3.5 release

Fri Apr 11 13:40:20 UTC 2014

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
> > >>
> > >>--
> > >>Open Source and Standards @ Red Hat
> > >>
> > >>twitter.com/realjustinclift
> > >>
> > >>
> > >>_______________________________________________
> > >>Gluster-devel mailing list
> > >>Gluster-devel at nongnu.org
> > >>https://lists.nongnu.org/mailman/listinfo/gluster-devel
> > >--
> > >Open Source and Standards @ Red Hat
> > >
> > >twitter.com/realjustinclift
> > >
> > >
> > >_______________________________________________
> > >Gluster-devel mailing list
> > >Gluster-devel at nongnu.org
> > >https://lists.nongnu.org/mailman/listinfo/gluster-devel
> > 
> > 
> > _______________________________________________
> > Gluster-devel mailing list
> > Gluster-devel at nongnu.org
> > https://lists.nongnu.org/mailman/listinfo/gluster-devel
> 
> --
> Niels de Vos
> Sr. Software Maintenance Engineer
> Support Engineering Group
> Red Hat Global Support Services
> 
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel
> 