Prashanth Pai
2015-Jul-09 07:06 UTC
[Gluster-users] [Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)
----- 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 >