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

[Prashanth Pai]

- Original Message -
> From: "Niels de Vos" 
> To: "Jeff Darcy" 
> Cc: "Kaushal Madappa" , "Humble Chirammal" 
> , gluster-devel@gluster.org,
> gluster-us...@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).
> 

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

[Niels de Vos]

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.

> 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.

> 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@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

[Jeff Darcy]

> 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. 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. 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. 

> * User documentation goes to glusterdocs repo and developer documentation
> stays in gluster repo.
> * 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.
> * 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.
> * A patch which changes a struct member should change the relevant developer
> documentation in the same patch set.
> * 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).
> * Use github's PR for glusterfsdocs and hence use the comments system on
> github for that.
> * 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.
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

[Raghavendra Talur]

On 07/08/2015 07:07 PM, Raghavendra Talur wrote:









*Top posting with summary of mails above to enable better
discussion*







*Premise of original mail:*



  * Gluster related documentation was spread across
wiki/website-html/gluster-repo and difficult to find.


  * We want a new place for documentation(preferebly one
single place)


  * The workflow to contribute should be easy for
non-developers too.(should definitely not involve
cloning repo from gerrit and sending patch)







*Unanswered questions/ Concerns raised*



  * Developer documentation like struct members and
their uses should be in repo so that developers update
it along with code changes, else there is a good
chance docs go outdated.


  * What is the reviewing mechanism for patches against
documentation?

  * What tool/system gives a good inline commenting
feature and can be used for discussion?



*My suggestions:*

 * Differentiate between user doc(installation, administration, feature
   summary, tools, FAQ/troubleshooting etc) and developer doc(Design
   doc, developer workflow, coding guidelines etc).
 * User documentation goes to glusterdocs repo and developer
   documentation stays in gluster repo.
 * 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.
 * 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.
 * A patch which changes a struct member should change the relevant
   developer documentation in the same patch set.
 * 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).
 * Use github's PR for glusterfsdocs and hence use the comments system
   on github for that.
 * 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.
















On 06/23/2015 04:36 PM, Sankarshan Mukhopadhyay wrote:




On Mon, Jun 22, 2015 at 5:24 PM, Shravan Chandrashekar
  wrote:



We would like to finalize on the documentation contribution workflow by 26th 
June 2015.
As we have not yet received any comments/suggestion, we will confirm the 
recommend workflow after 26th June.


Kindly provide your suggestion on how we can improve this workflow.



There are a couple of aspects which need to be quickly looked through.

(a) a write-up of somewhat detail providing an overview of the new
workflow; how contributors can participate; reviewing mechanism for
patches against documentation; merge and release paths/cadence

(b) at  Niels has a comment
about "about design of structures used in the code" and how he thinks
that it is appropriate if "it stays part of the sources and does not
move out."

He also says "For example, I would like to document some of the memory
layout structures and functions, but this documentation will include
source-code comments and a .txt or .md file with additional details.
Spitting that makes it more difficult to keep in sync."

In this particular example, I'd probably say that it would be better
that such documentation is also part of the docs repo. It lends itself
to re-use as and when required (this particular example seems re-use
friendly).

I'd request that this switch-over to the new workflow and repositories
go ahead with the absolute "documentation" content. Examples/cases
like the above mentioned by Niels can be resolved via discussion and
probably not block the switch.




Currently, mediawiki is read-only. We have ported most of the documents from 
mediawiki to the new repository [1].
If you find any document which is not ported, feel free to raise this by 
opening an issue in [2] or if you would
like to port your documents, send a pull request.



[1]https://github.com/gluster/glusterdocs
[2]https://github.com/gluster/glusterdocs/issues


























___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

[Raghavendra Talur]

*Top posting with summary of mails above to enable better discussion*

*Premise of original mail:*

 * Gluster related documentation was spread across
   wiki/website-html/gluster-repo and difficult to find.
 * We want a new place for documentation(preferebly one single place)
 * The workflow to contribute should be easy for non-developers
   too.(should definitely not involve cloning repo from gerrit and
   sending patch)


*Unanswered questions/ Concerns raised*

 * Developer documentation like struct members and their uses should be
   in repo so that developers update it along with code changes, else
   there is a good chance docs go outdated.
 * What is the reviewing mechanism for patches against documentation?
 * What tool/system gives a good inline commenting feature and can be
   used for discussion?




On 06/23/2015 04:36 PM, Sankarshan Mukhopadhyay wrote:

On Mon, Jun 22, 2015 at 5:24 PM, Shravan Chandrashekar
 wrote:

We would like to finalize on the documentation contribution workflow by 26th 
June 2015.
As we have not yet received any comments/suggestion, we will confirm the 
recommend workflow after 26th June.


Kindly provide your suggestion on how we can improve this workflow.

There are a couple of aspects which need to be quickly looked through.

(a) a write-up of somewhat detail providing an overview of the new
workflow; how contributors can participate; reviewing mechanism for
patches against documentation; merge and release paths/cadence

(b) at  Niels has a comment
about "about design of structures used in the code" and how he thinks
that it is appropriate if "it stays part of the sources and does not
move out."

He also says "For example, I would like to document some of the memory
layout structures and functions, but this documentation will include
source-code comments and a .txt or .md file with additional details.
Spitting that makes it more difficult to keep in sync."

In this particular example, I'd probably say that it would be better
that such documentation is also part of the docs repo. It lends itself
to re-use as and when required (this particular example seems re-use
friendly).

I'd request that this switch-over to the new workflow and repositories
go ahead with the absolute "documentation" content. Examples/cases
like the above mentioned by Niels can be resolved via discussion and
probably not block the switch.


Currently, mediawiki is read-only. We have ported most of the documents from 
mediawiki to the new repository [1].
If you find any document which is not ported, feel free to raise this by 
opening an issue in [2] or if you would
like to port your documents, send a pull request.



[1] https://github.com/gluster/glusterdocs
[2] https://github.com/gluster/glusterdocs/issues










___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel