Gluster users - Apr 2018 - Proposal to make Design Spec and Document for a feature mandatory.

Hi all,

A better documentation about the feature, and also information about how to
use the features are one of the major ask of the community when they want
to use glusterfs, or want to contribute by helping get the features, bug
fixes for features, etc.

Finally, we have taken some baby steps to get that ask of having better
design and documentation resolved. We had discussed this in our automation
goals [1], to make having design spec, and documentation mandatory for a
feature patch. Now, thanks to Shyam and Nigel, we have the patch ready to
automate this process [2].

Feel free to review the patch, and comment on this.

A heads up on how it looks like after this patch gets in.

* A patch for a github reference won't pass smoke unless these labels are
present on github issue.
* Everyone, feel free to review and comment on the issue / patch regarding
the document. But, the label is expected to be provided only by Project's
general architects, and any industry experts we as community nominate for
validating feature. Initially for making sure we have a valid process,
where I don't provides flags quickly, expectation is to have two people
comment about approving the flags, and then the label can be provided.
* Some may argue, the rate of development can reduce if we make this flag
mandatory, but what is the use of having a feature without design and
documentation on how to use it?

For those who want to provide Spec and Doc approved flags, you can have a
quick link [3], to see all the tests which fail smoke. Not all smoke
failures would be for missing Spec and Doc flag, but this is just a quick
start.

[1] - https://docs.google.com/document/d/1AFkZmRRDXRxs21GnGauieIyiIiRZ-
nTEW8CPi7Gbp3g/edit
[2] - https://github.com/gluster/glusterfs-patch-acceptance-tests/pull/126
[3] -
https://review.gluster.org/#/dashboard/?foreach=status:open%20project:glusterfs%20branch:master%20&title=Github%2520Validation&&Awaiting%2520Reviews=(label:Smoke=-1)

We would like to implement this check soon, and happy to accommodate the
feedback and suggestions along the way.

Regards,
Amar
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.gluster.org/pipermail/gluster-users/attachments/20180402/a37abfe3/attachment.html>

All,

Thanks to Nigel, this is now deployed, and any new patches referencing
github (ie, new features) need the 'DocApproved' and
'SpecApproved' label.

Regards,
Amar

On Mon, Apr 2, 2018 at 10:40 AM, Amar Tumballi <atumball at redhat.com>
wrote:
> Hi all,
>
> A better documentation about the feature, and also information about how
> to use the features are one of the major ask of the community when they
> want to use glusterfs, or want to contribute by helping get the features,
> bug fixes for features, etc.
>
> Finally, we have taken some baby steps to get that ask of having better
> design and documentation resolved. We had discussed this in our automation
> goals [1], to make having design spec, and documentation mandatory for a
> feature patch. Now, thanks to Shyam and Nigel, we have the patch ready to
> automate this process [2].
>
> Feel free to review the patch, and comment on this.
>
> A heads up on how it looks like after this patch gets in.
>
> * A patch for a github reference won't pass smoke unless these labels
are
> present on github issue.
> * Everyone, feel free to review and comment on the issue / patch
> regarding the document. But, the label is expected to be provided only by
> Project's general architects, and any industry experts we as community
> nominate for validating feature. Initially for making sure we have a valid
> process, where I don't provides flags quickly, expectation is to have
two
> people comment about approving the flags, and then the label can be
> provided.
> * Some may argue, the rate of development can reduce if we make this flag
> mandatory, but what is the use of having a feature without design and
> documentation on how to use it?
>
> For those who want to provide Spec and Doc approved flags, you can have a
> quick link [3], to see all the tests which fail smoke. Not all smoke
> failures would be for missing Spec and Doc flag, but this is just a quick
> start.
>
> [1] - https://docs.google.com/document/d/1AFkZmRRDXRxs21GnGauieI
> yiIiRZ-nTEW8CPi7Gbp3g/edit
> [2] - https://github.com/gluster/glusterfs-patch-acceptance-tests/pull/126
> [3] - https://review.gluster.org/#/dashboard/?foreach=status:
>
open%20project:glusterfs%20branch:master%20&title=Github%2520Validation&&
> Awaiting%2520Reviews=(label:Smoke=-1)
>
> We would like to implement this check soon, and happy to accommodate the
> feedback and suggestions along the way.
>
> Regards,
> Amar
>
>

-- 
Amar Tumballi (amarts)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.gluster.org/pipermail/gluster-users/attachments/20180413/3e20f9a3/attachment.html>

On Fri, Apr 13, 2018 at 11:34:12AM +0530, Amar Tumballi
wrote:
> All,
> 
> Thanks to Nigel, this is now deployed, and any new patches referencing
> github (ie, new features) need the 'DocApproved' and
'SpecApproved' label.
Great! I hope we'll get more written down how new features are expected
to work and how users can benefit from them.

I thought we had a document that explained the different GitHub Issue
tags somewhere? Unfortunately I cant find it... Maybe someone can add it
in the Contrubtors Guide?
  https://docs.gluster.org/en/latest/Contributors-Guide/Index/

Thanks,
Niels

> 
> Regards,
> Amar
> 
> On Mon, Apr 2, 2018 at 10:40 AM, Amar Tumballi <atumball at
redhat.com> wrote:
> 
> > Hi all,
> >
> > A better documentation about the feature, and also information about
how
> > to use the features are one of the major ask of the community when
they
> > want to use glusterfs, or want to contribute by helping get the
features,
> > bug fixes for features, etc.
> >
> > Finally, we have taken some baby steps to get that ask of having
better
> > design and documentation resolved. We had discussed this in our
automation
> > goals [1], to make having design spec, and documentation mandatory for
a
> > feature patch. Now, thanks to Shyam and Nigel, we have the patch ready
to
> > automate this process [2].
> >
> > Feel free to review the patch, and comment on this.
> >
> > A heads up on how it looks like after this patch gets in.
> >
> > * A patch for a github reference won't pass smoke unless these
labels are
> > present on github issue.
> > * Everyone, feel free to review and comment on the issue / patch
> > regarding the document. But, the label is expected to be provided only
by
> > Project's general architects, and any industry experts we as
community
> > nominate for validating feature. Initially for making sure we have a
valid
> > process, where I don't provides flags quickly, expectation is to
have two
> > people comment about approving the flags, and then the label can be
> > provided.
> > * Some may argue, the rate of development can reduce if we make this
flag
> > mandatory, but what is the use of having a feature without design and
> > documentation on how to use it?
> >
> > For those who want to provide Spec and Doc approved flags, you can
have a
> > quick link [3], to see all the tests which fail smoke. Not all smoke
> > failures would be for missing Spec and Doc flag, but this is just a
quick
> > start.
> >
> > [1] - https://docs.google.com/document/d/1AFkZmRRDXRxs21GnGauieI
> > yiIiRZ-nTEW8CPi7Gbp3g/edit
> > [2] -
https://github.com/gluster/glusterfs-patch-acceptance-tests/pull/126
> > [3] - https://review.gluster.org/#/dashboard/?foreach=status:
> >
open%20project:glusterfs%20branch:master%20&title=Github%2520Validation&&
> > Awaiting%2520Reviews=(label:Smoke=-1)
> >
> > We would like to implement this check soon, and happy to accommodate
the
> > feedback and suggestions along the way.
> >
> > Regards,
> > Amar
> >
> >
> 
> 
> -- 
> Amar Tumballi (amarts)
> _______________________________________________
> maintainers mailing list
> maintainers at gluster.org
> http://lists.gluster.org/mailman/listinfo/maintainers