[Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)

[Prashanth Pai]

----- Original Message -----
> From: "Niels de Vos" <ndevos at redhat.com>
> To: "Jeff Darcy" <jdarcy at redhat.com>
> Cc: "Kaushal Madappa" <kmadappa at redhat.com>, "Humble Chirammal" <hchiramm at redhat.com>, gluster-devel at gluster.org,
> gluster-users at gluster.org
> Sent: Wednesday, 8 July, 2015 10:10:07 PM
> Subject: Re: [Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An
> Update)
> 
> On Wed, Jul 08, 2015 at 11:32:46AM -0400, Jeff Darcy wrote:
> > > My suggestions:
> > 
> > > * Differentiate between user doc(installation, administration, feature
> > > summary, tools, FAQ/troubleshooting etc) and developer doc(Design doc,
> > > developer workflow, coding guidelines etc).
> > 
> > I think there's a third category: feature/release planning and
> > tracking. That stuff doesn't belong in the online equivalent of a
> > manual, though it should be linked from there. It also doesn't belong
> > in the same git repository with code, because it's explicitly not
> > associated with a particular version of code. However, putting it in a
> > *separate* git repository might work.
> 
> Indeed, and I value tracking of who made comments a lot. Developers that
> are used to Gerrit can checkout a document, update it and push the new
> version for review. Feature and release planning is very much only done
> by developers, and they use Gerrit for their patches already too. Mostly
> the same workflow as they are used to, should make adoption easy.

+1
 
In Openstack Swift, we have the "specs" repo where design discussion over a feature
is carried out by devs. It's equivalent of GlusterFS feature pages but more lively.

http://specs.openstack.org/openstack/swift-specs/
https://review.openstack.org/#/q/status:open+project:openstack/swift-specs,n,z

> 
> > Having history would be nice.  Gerrit and github both provides
> > reasonable inline-commenting facilities to support the kinds of
> > discussions that need to occur, plus a way to finalize the results of
> > those discussions with a commit.
> 
> I do not agree that commenting in GitHub pull requests is usable.
> Comments get lost when a new version of the patch is posted, unless you
> have the URL to the actual git-commit of the previous version. This is
> one of the reasons why NFS-Ganesha moved from a GitHub based workflow to
> Gerrit.

+1 here too.
One either adds more commits after each round of review and end up having so many
commits in the tree or squash/amend the commit and lose history of comments.
For the same reasons, many openstack related projects have moved to to
stackforge (gerrit based) from github.

> 
> > My main concern is that such a setup might seem inaccessible to users
> > who aren't familiar with those developer-oriented workflows. For them,
> > probably nothing more cumbersome than a wiki would be sufficient. On
> > the other hand, I have yet to see such a user edit one of our
> > feature/planning pages even when those were in a wiki. I can barely
> > get my fellow developers to do so, even when the features are their
> > own, so maybe usability just isn't the issue.
> 
> Yeah, I have the same impression. Lets make it easier for developers to
> update the feature pages while they work on the planning/design.
> Depending on less different tools or hosted services would be an
> advantage IMHO.
> 
> > > * User documentation goes to glusterdocs repo and developer documentation
> > > stays in gluster repo.
> 
> Makes sense to me.
> 
> > > * An user/admin who installed through packages can do a man(and find man
> > > pages) or google(and find readthedocs pages) without going through
> > > gerrit/wiki etc.
> 
> Yeah, and installing offline documentation might become possible too :-)
> 
> > > * A developer who has cloned gluster repo finds all the development
> > > related
> > > info in the repo itself(git grep etc) and does not need to go out of the
> > > code base.
> 
> Yes, there are some good bits about mem-pool and bitrot under the doc/
> directory in the sources. I do not see a sensible use for those outside
> od the source tree. Changes to mem-pool or bitrot would also need to
> update the docs, we should try to prevent getting those out of sync.
> 
> > > * A patch which changes a struct member should change the relevant
> > > developer
> > > documentation in the same patch set.
> 
> +1
> 
> > > * A patch which changes a user facing behavior should be ideally followed
> > > by
> > > a PR on glusterdocs repo. (patch owner and feature maintainer to ensure
> > > that).
> 
> I would also add the component maintainers to the list who should be
> responsible for making sure the documentation gets addressed. I guess
> the glusterdocs repo on GitHub uses the "Issues" instead of Bugzilla?
> For each feature we should then at least file a GitHub issue there.
> 
> > > * Use github's PR for glusterfsdocs and hence use the comments system on
> > > github for that.
> 
> Yeah, and the documentation maintainers should involve the component
> maintainers for reviewing those proposed changes. Not sure how to add
> someone on CC of a pull request though...
> 
> > > * A developer doc change or a new feature proposal should be as patch on
> > > gluster repo and we can use gerrit's inline comments for discussion on
> > > that.
> 
> Like Jeff mentioned above, new feature documentation might be more
> useful to start in its own git repo. I think this would make it easier
> to integrate with the readthedocs stuff. How its done does not matter
> much to me (now at least), I'm all for using Gerrit to review proposed
> features and planning documents.
> 
> Thanks,
> Niels
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-devel
>