Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Doug Hellmann]

Excerpts from Andreas Jaeger's message of 2017-01-03 19:29:25 +0100:
> On 01/03/2017 05:59 PM, Anne Gentle wrote:
> > 
> > What happens is you get a special notification and link to
> > CONTRIBUTING.txt (or rst, but only after comparing branches) as in this
> > screenshot:
> > 
> > https://postimg.org/image/wple5yudr/
> > 
> > But, based on testing, it's fine to keep what we have (rst) for the
> > scenarios that work today.
> 
> I just created pull requests for both a repo with .rst and .md and got
> the "contributing link" at exactly the same time in the workflow for
> both of them - in both cases when creating the pull request,
> 
> Andreas

OK, great. I assumed that's how it worked but it's good to have
verification.

Thanks, Andreas & Anne!


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andreas Jaeger]

On 01/03/2017 05:59 PM, Anne Gentle wrote:
> 
> What happens is you get a special notification and link to
> CONTRIBUTING.txt (or rst, but only after comparing branches) as in this
> screenshot:
> 
> https://postimg.org/image/wple5yudr/
> 
> But, based on testing, it's fine to keep what we have (rst) for the
> scenarios that work today.

I just created pull requests for both a repo with .rst and .md and got
the "contributing link" at exactly the same time in the workflow for
both of them - in both cases when creating the pull request,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Tue, Jan 3, 2017 at 10:47 AM, Doug Hellmann 
wrote:

> Excerpts from Anne Gentle's message of 2017-01-03 10:26:28 -0600:
> > On Tue, Jan 3, 2017 at 12:04 AM, Andreas Jaeger  wrote:
> >
> > > On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > > > [...]
> > > > Doug, I think the include in Sphinx can be a raw txt file? Then we
> get
> > > > the best of both worlds - rendered on both docs.openstack.org
> > > >  and github.com .
> > >
> > > We do not need an rst file, github handles .txt just fine. I see no
> > > reason to move to txt.
> > >
> > > > I'll give that a shot with these patches as a proof of concept:
> > > >
> > > > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > > > https://review.openstack.org/416109
> > > > 2. Update openstack-manuals rendered docs with an included
> > > > CONTRIBUTING.txt https://review.openstack.org/416112
> > > >
> > > > We won't really know the GitHub UI rendering of the include until
> > > > merged, but I've tested in other repos and changing the file
> extension
> > > > to .txt gives a link to that file.
> > >
> > > Works with RST as well for me - I just created a pull request for
> > > cookiecutter and got the contributing link as expected. There's no need
> > > to use txt files.
> > >
> >
> > To wrap this up - I saw different behavior when simply clicking "New Pull
> > Request." The GitHub UI behaves differently for RST files in that
> > particular scenario, prior to the act of comparing branches. But it's not
> > worthwhile to pursue, and is probably simply a bug in GitHub's UI, so
> I've
> > abandoned the cookie-cutter patch.
>
> Ah, that's a case I didn't look at. So you're saying that if we
> call it CONTRIBUTING.txt then it renders on the page where the pull
> request is being created? That does seem like something we want.
>

What happens is you get a special notification and link to CONTRIBUTING.txt
(or rst, but only after comparing branches) as in this screenshot:

https://postimg.org/image/wple5yudr/

But, based on testing, it's fine to keep what we have (rst) for the
scenarios that work today.

Anne


>
> Doug
>
> >
> > Anne
> >
> > >
> > > > Thoughts? Please comment on the reviews or here. I can work on it if
> we
> > > > think it's worthwhile to standardize upon, and/or collaborate with
> the
> > > > original contributor who wanted to standardize. I do believe the
> GitHub
> > > > experience is worthy of attention, similar in my mind to the recent
> > > > badges work.
> > >
> > > Andreas
> > > --
> > >  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
> > >   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> > >GF: Felix Imendörffer, Jane Smithard, Graham Norton,
> > >HRB 21284 (AG Nürnberg)
> > > GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272
> A126
> > >
> > >
> > > 
> __
> > > OpenStack Development Mailing List (not for usage questions)
> > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:
> unsubscribe
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > >
> >
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Doug Hellmann]

Excerpts from Anne Gentle's message of 2017-01-03 10:26:28 -0600:
> On Tue, Jan 3, 2017 at 12:04 AM, Andreas Jaeger  wrote:
> 
> > On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > > [...]
> > > Doug, I think the include in Sphinx can be a raw txt file? Then we get
> > > the best of both worlds - rendered on both docs.openstack.org
> > >  and github.com .
> >
> > We do not need an rst file, github handles .txt just fine. I see no
> > reason to move to txt.
> >
> > > I'll give that a shot with these patches as a proof of concept:
> > >
> > > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > > https://review.openstack.org/416109
> > > 2. Update openstack-manuals rendered docs with an included
> > > CONTRIBUTING.txt https://review.openstack.org/416112
> > >
> > > We won't really know the GitHub UI rendering of the include until
> > > merged, but I've tested in other repos and changing the file extension
> > > to .txt gives a link to that file.
> >
> > Works with RST as well for me - I just created a pull request for
> > cookiecutter and got the contributing link as expected. There's no need
> > to use txt files.
> >
> 
> To wrap this up - I saw different behavior when simply clicking "New Pull
> Request." The GitHub UI behaves differently for RST files in that
> particular scenario, prior to the act of comparing branches. But it's not
> worthwhile to pursue, and is probably simply a bug in GitHub's UI, so I've
> abandoned the cookie-cutter patch.

Ah, that's a case I didn't look at. So you're saying that if we
call it CONTRIBUTING.txt then it renders on the page where the pull
request is being created? That does seem like something we want.

Doug

> 
> Anne
> 
> >
> > > Thoughts? Please comment on the reviews or here. I can work on it if we
> > > think it's worthwhile to standardize upon, and/or collaborate with the
> > > original contributor who wanted to standardize. I do believe the GitHub
> > > experience is worthy of attention, similar in my mind to the recent
> > > badges work.
> >
> > Andreas
> > --
> >  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
> >   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> >GF: Felix Imendörffer, Jane Smithard, Graham Norton,
> >HRB 21284 (AG Nürnberg)
> > GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
> >
> >
> > __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> 

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Tue, Jan 3, 2017 at 12:04 AM, Andreas Jaeger  wrote:

> On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > [...]
> > Doug, I think the include in Sphinx can be a raw txt file? Then we get
> > the best of both worlds - rendered on both docs.openstack.org
> >  and github.com .
>
> We do not need an rst file, github handles .txt just fine. I see no
> reason to move to txt.
>
> > I'll give that a shot with these patches as a proof of concept:
> >
> > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > https://review.openstack.org/416109
> > 2. Update openstack-manuals rendered docs with an included
> > CONTRIBUTING.txt https://review.openstack.org/416112
> >
> > We won't really know the GitHub UI rendering of the include until
> > merged, but I've tested in other repos and changing the file extension
> > to .txt gives a link to that file.
>
> Works with RST as well for me - I just created a pull request for
> cookiecutter and got the contributing link as expected. There's no need
> to use txt files.
>

To wrap this up - I saw different behavior when simply clicking "New Pull
Request." The GitHub UI behaves differently for RST files in that
particular scenario, prior to the act of comparing branches. But it's not
worthwhile to pursue, and is probably simply a bug in GitHub's UI, so I've
abandoned the cookie-cutter patch.

Anne


>
> > Thoughts? Please comment on the reviews or here. I can work on it if we
> > think it's worthwhile to standardize upon, and/or collaborate with the
> > original contributor who wanted to standardize. I do believe the GitHub
> > experience is worthy of attention, similar in my mind to the recent
> > badges work.
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Doug Hellmann]

Excerpts from Andreas Jaeger's message of 2017-01-03 07:04:51 +0100:
> On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > [...]
> > Doug, I think the include in Sphinx can be a raw txt file? Then we get
> > the best of both worlds - rendered on both docs.openstack.org
> >  and github.com .
> 
> We do not need an rst file, github handles .txt just fine. I see no
> reason to move to txt.
> 
> > I'll give that a shot with these patches as a proof of concept:
> > 
> > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > https://review.openstack.org/416109
> > 2. Update openstack-manuals rendered docs with an included
> > CONTRIBUTING.txt https://review.openstack.org/416112
> > 
> > We won't really know the GitHub UI rendering of the include until
> > merged, but I've tested in other repos and changing the file extension
> > to .txt gives a link to that file.
> 
> Works with RST as well for me - I just created a pull request for
> cookiecutter and got the contributing link as expected. There's no need
> to use txt files.

github renders rst to HTML and makes links active. See
https://github.com/openstack/oslo.config/blob/master/CONTRIBUTING.rst

> 
> > Thoughts? Please comment on the reviews or here. I can work on it if we
> > think it's worthwhile to standardize upon, and/or collaborate with the
> > original contributor who wanted to standardize. I do believe the GitHub
> > experience is worthy of attention, similar in my mind to the recent
> > badges work.
> 
> Andreas

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andreas Jaeger]

On 01/03/2017 04:01 AM, Anne Gentle wrote:
> [...]
> Doug, I think the include in Sphinx can be a raw txt file? Then we get
> the best of both worlds - rendered on both docs.openstack.org
>  and github.com .

We do not need an rst file, github handles .txt just fine. I see no
reason to move to txt.

> I'll give that a shot with these patches as a proof of concept:
> 
> 1. Change cookie-cutter file to CONTRIBUTING.txt
> https://review.openstack.org/416109
> 2. Update openstack-manuals rendered docs with an included
> CONTRIBUTING.txt https://review.openstack.org/416112
> 
> We won't really know the GitHub UI rendering of the include until
> merged, but I've tested in other repos and changing the file extension
> to .txt gives a link to that file.

Works with RST as well for me - I just created a pull request for
cookiecutter and got the contributing link as expected. There's no need
to use txt files.

> Thoughts? Please comment on the reviews or here. I can work on it if we
> think it's worthwhile to standardize upon, and/or collaborate with the
> original contributor who wanted to standardize. I do believe the GitHub
> experience is worthy of attention, similar in my mind to the recent
> badges work.

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Mon, Jan 2, 2017 at 11:03 AM, Doug Hellmann <d...@doughellmann.com>
wrote:

> Excerpts from Paul Belanger's message of 2016-12-24 15:23:35 -0500:
> > On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:
> > > -Original Message-
> > > From: Andrey Kurilin <akuri...@mirantis.com>
> > > Reply: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> > > Date: December 21, 2016 at 10:13:09
> > > To: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> > > Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
> projects
> > >
> > > > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
> > > >
> > > > > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > > > > [...]
> > > > > > That said, I think there are two better places for this
> information
> > > > > > that are already standards in OpenStack:
> > > > > >
> > > > > > * README.rst
> > > > > > * HACKING.rst
> > > > > >
> > > > > > Most projects include links to the contributing documentation in
> at
> > > > > > least one of these files. I think the effort here is to
> standardize,
> > > > > > albeit in a brand new file, and that's admirable.
> > > > >
> > > > > If that's the goal - to standardize - then I would expect that we
> move
> > > > > all the documentation out of those files in one place.
> > > > >
> > > > > Right now, the changes duplicate information that exists - and the
> new
> > > > > information is often wrong. It points to place that do not exist or
> > > > > where better places exist. ;(
> > > > >
> > > >
> > > > Duplication can be reduced by using `.. include:: ` directive.
> > >
> > > That does not render anywhere except our documentation (via Sphinx).
> Git{Hub,Lab} don't render the include directive at all.
> > >
> > > So, no, that's not an option.
> > >
> > No, this is a valid option. We do it today with various documentation.
> >
> > They will however render to docs.o.o, which we consider source of truth.
> The
> > topic of rendering RST files to github has come up a few times, but each
> time
> > comes back to the fact we simply mirror to github.
> >
> > It is possible to have git.openstack.org render RST too, but we've
> opted to do
> > it with docs.openstack.org.
> >
>
> Using include works some places, but not others.
>
> The include directive is a feature of Sphinx, not docutils. We use
> Sphinx to convert reStructuredText to HTML for docs.o.o but github does
> not use Sphinx when rendering individual reStructuredText files such as
> CONTRIBUTING.rst or README.rst.
>
> Since the point of having CONTRIBUTING.rst be a separate file is
> to take advantage of the github.com integration to guide potential
> contributors to the right forum for their contributions, we need
> to ensure that those files render correctly by placing the content
> directly into those files.  Then we can have project contributor
> documentation use the include directive to avoid duplicating the
> information elsewhere.
>

Doug, I think the include in Sphinx can be a raw txt file? Then we get the
best of both worlds - rendered on both docs.openstack.org and github.com.

I'll give that a shot with these patches as a proof of concept:

1. Change cookie-cutter file to CONTRIBUTING.txt
https://review.openstack.org/416109
2. Update openstack-manuals rendered docs with an included CONTRIBUTING.txt
https://review.openstack.org/416112

We won't really know the GitHub UI rendering of the include until merged,
but I've tested in other repos and changing the file extension to .txt
gives a link to that file.

Thoughts? Please comment on the reviews or here. I can work on it if we
think it's worthwhile to standardize upon, and/or collaborate with the
original contributor who wanted to standardize. I do believe the GitHub
experience is worthy of attention, similar in my mind to the recent badges
work.

Anne


>
> Doug
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Doug Hellmann]

Excerpts from Paul Belanger's message of 2016-12-24 15:23:35 -0500:
> On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:
> > -Original Message-
> > From: Andrey Kurilin <akuri...@mirantis.com>
> > Reply: OpenStack Development Mailing List (not for usage questions) 
> > <openstack-dev@lists.openstack.org>
> > Date: December 21, 2016 at 10:13:09
> > To: OpenStack Development Mailing List (not for usage questions) 
> > <openstack-dev@lists.openstack.org>
> > Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to 
> > projects
> > 
> > > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
> > >  
> > > > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > > > [...]
> > > > > That said, I think there are two better places for this information
> > > > > that are already standards in OpenStack:
> > > > >
> > > > > * README.rst
> > > > > * HACKING.rst
> > > > >
> > > > > Most projects include links to the contributing documentation in at
> > > > > least one of these files. I think the effort here is to standardize,
> > > > > albeit in a brand new file, and that's admirable.
> > > >
> > > > If that's the goal - to standardize - then I would expect that we move
> > > > all the documentation out of those files in one place.
> > > >
> > > > Right now, the changes duplicate information that exists - and the new
> > > > information is often wrong. It points to place that do not exist or
> > > > where better places exist. ;(
> > > >
> > >  
> > > Duplication can be reduced by using `.. include:: ` directive.
> > 
> > That does not render anywhere except our documentation (via Sphinx). 
> > Git{Hub,Lab} don't render the include directive at all.
> > 
> > So, no, that's not an option.
> > 
> No, this is a valid option. We do it today with various documentation.
> 
> They will however render to docs.o.o, which we consider source of truth. The
> topic of rendering RST files to github has come up a few times, but each time
> comes back to the fact we simply mirror to github.
> 
> It is possible to have git.openstack.org render RST too, but we've opted to do
> it with docs.openstack.org.
> 

Using include works some places, but not others.

The include directive is a feature of Sphinx, not docutils. We use
Sphinx to convert reStructuredText to HTML for docs.o.o but github does
not use Sphinx when rendering individual reStructuredText files such as
CONTRIBUTING.rst or README.rst.

Since the point of having CONTRIBUTING.rst be a separate file is
to take advantage of the github.com integration to guide potential
contributors to the right forum for their contributions, we need
to ensure that those files render correctly by placing the content
directly into those files.  Then we can have project contributor
documentation use the include directive to avoid duplicating the
information elsewhere.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Paul Belanger]

On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:
> -Original Message-
> From: Andrey Kurilin <akuri...@mirantis.com>
> Reply: OpenStack Development Mailing List (not for usage questions) 
> <openstack-dev@lists.openstack.org>
> Date: December 21, 2016 at 10:13:09
> To: OpenStack Development Mailing List (not for usage questions) 
> <openstack-dev@lists.openstack.org>
> Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects
> 
> > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
> >  
> > > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > > [...]
> > > > That said, I think there are two better places for this information
> > > > that are already standards in OpenStack:
> > > >
> > > > * README.rst
> > > > * HACKING.rst
> > > >
> > > > Most projects include links to the contributing documentation in at
> > > > least one of these files. I think the effort here is to standardize,
> > > > albeit in a brand new file, and that's admirable.
> > >
> > > If that's the goal - to standardize - then I would expect that we move
> > > all the documentation out of those files in one place.
> > >
> > > Right now, the changes duplicate information that exists - and the new
> > > information is often wrong. It points to place that do not exist or
> > > where better places exist. ;(
> > >
> >  
> > Duplication can be reduced by using `.. include:: ` directive.
> 
> That does not render anywhere except our documentation (via Sphinx). 
> Git{Hub,Lab} don't render the include directive at all.
> 
> So, no, that's not an option.
> 
No, this is a valid option. We do it today with various documentation.

They will however render to docs.o.o, which we consider source of truth. The
topic of rendering RST files to github has come up a few times, but each time
comes back to the fact we simply mirror to github.

It is possible to have git.openstack.org render RST too, but we've opted to do
it with docs.openstack.org.

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Amrith Kumar]

So Jeremy, that's great. so all someone has to do is pick this file and
blast it out to 150 projects :)

Merry Christmas, Happy Hanukah, Happy Festivus and best wishes for the feats
of strenght, Happy Holidays, Have a good weekend ... (pick as many as you'd
like)

-amrith

> -Original Message-
> From: Jeremy Stanley [mailto:fu...@yuggoth.org]
> Sent: Saturday, December 24, 2016 9:58 AM
> To: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev@lists.openstack.org>
> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
projects
> 
> On 2016-12-22 09:52:21 -0600 (-0600), Anne Gentle wrote:
> [...]
> > Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be
> > .md for github, Ian?) for all projects? Is it similar to the nova 2012
> > version or is there a more modern take?
> 
> The reference example is maintained at
> http://git.openstack.org/cgit/openstack-
> dev/cookiecutter/tree/%7b%7bcookiecutter.repo_name%7d%7d/CONTRIB
> UTING.rst
> (or at least that's the closest we have to one that's supposed to be kept
> "modern").
> --
> Jeremy Stanley
> 
> __
> 
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-
> requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


smime.p7s
Description: S/MIME cryptographic signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Jeremy Stanley]

On 2016-12-22 09:52:21 -0600 (-0600), Anne Gentle wrote:
[...]
> Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
> for github, Ian?) for all projects? Is it similar to the nova 2012 version
> or is there a more modern take?

The reference example is maintained at
http://git.openstack.org/cgit/openstack-dev/cookiecutter/tree/%7b%7bcookiecutter.repo_name%7d%7d/CONTRIBUTING.rst
(or at least that's the closest we have to one that's supposed to be
kept "modern").
-- 
Jeremy Stanley

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Thu, Dec 22, 2016 at 10:47 AM, Andreas Jaeger  wrote:

> On 12/22/2016 04:52 PM, Anne Gentle wrote:
> >
> >
> > On Thu, Dec 22, 2016 at 8:32 AM, Doug Hellmann  > > wrote:
> >
> > Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> > >
> > > There is some ambiguity right now with projects as to where to put
> > > easy-to-find documentation (even if it is just a brief paragraph
> with
> > > a link to longer-form documentation) into our repositories. Let's
> > > focus on that discussion here. We can come up with a productive
> > > conclusion and work with this contributor. While you've chosen (and
> > > yes, you've chosen this) to have a negative assumption about this
> > > contributor's efforts, I've chosen to believe they're looking to
> fill
> > > a gap. Increasing the productivity of new contributors to
> OpenStack is
> > > a positive improvement for our community. It may not fix a bug or
> add
> > > a feature, but it helps ramp up the people who will do that.
> >
> > I thought we started adding these contributing files specifically
> > because of how they are rendered on github, as a way to try to
> prevent
> > folks from submitting pull requests there and then having them
> rejected
> > by the bot. It seemed more positive to give direction ahead of time
> than
> > through a rejection message.
> >
> >
> > +1 to this and Ian and Alex's sentiments.
> >
> > It'd be great to get people to click one more time (to a more specific
> > contributor guide), but let's face it, there has to be a lot of traffic
> > directly to github.com . Let's make sure there's a
> > decent entry.
> >
> > Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
> > for github, Ian?) for all projects? Is it similar to the nova 2012
> > version or is there a more modern take?
>
>
> I'm against *only* adding a CONTRIBUTING.rst file. Any such change,
> should remove the existing content so that we have no duplication. If we
> document in two or three places how to contribute, one will be out of sync.
>
> So, a well done patch would be welcome - but not just adding a file with
> wrong information and no integration into existing content,.
>


Sure, let's get accurate info, but the scenario I'm thinking of is this one:
https://help.github.com/articles/setting-guidelines-for-repository-contributors/

Where the link is automatically displayed.

Anne


>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andreas Jaeger]

On 12/22/2016 04:52 PM, Anne Gentle wrote:
> 
> 
> On Thu, Dec 22, 2016 at 8:32 AM, Doug Hellmann  > wrote:
> 
> Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> >
> > There is some ambiguity right now with projects as to where to put
> > easy-to-find documentation (even if it is just a brief paragraph with
> > a link to longer-form documentation) into our repositories. Let's
> > focus on that discussion here. We can come up with a productive
> > conclusion and work with this contributor. While you've chosen (and
> > yes, you've chosen this) to have a negative assumption about this
> > contributor's efforts, I've chosen to believe they're looking to fill
> > a gap. Increasing the productivity of new contributors to OpenStack is
> > a positive improvement for our community. It may not fix a bug or add
> > a feature, but it helps ramp up the people who will do that.
> 
> I thought we started adding these contributing files specifically
> because of how they are rendered on github, as a way to try to prevent
> folks from submitting pull requests there and then having them rejected
> by the bot. It seemed more positive to give direction ahead of time than
> through a rejection message.
> 
> 
> +1 to this and Ian and Alex's sentiments.
> 
> It'd be great to get people to click one more time (to a more specific
> contributor guide), but let's face it, there has to be a lot of traffic
> directly to github.com . Let's make sure there's a
> decent entry.
> 
> Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
> for github, Ian?) for all projects? Is it similar to the nova 2012
> version or is there a more modern take?


I'm against *only* adding a CONTRIBUTING.rst file. Any such change,
should remove the existing content so that we have no duplication. If we
document in two or three places how to contribute, one will be out of sync.

So, a well done patch would be welcome - but not just adding a file with
wrong information and no integration into existing content,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Flavio Percoco]

On 21/12/16 07:22 -0800, Ian Cordasco wrote:

Hey everyone,

It seems a contributor has written a script to add CONTRIBUTING.rst
files to each OpenStack project that exists. [1]

As a community we've struggled with new contributors creating tonnes
of patches like this at once, and that is emphatically not the purpose
of this email. Instead, I'd like to discuss the actual merits of this
change for OpenStack.

What is CONTRIBUTING.rst?
=

It's a convention created by GitHub to make up for the lack of issue
templating and encourage collaborators/contributors to read some
documentation before filing new issues or pull requests. It does this
by adding an unobtrusive link at the top of the New Issue and New Pull
Request pages for projects that have these files.

In my experience using these files on projects, they've been wildly ineffective.

Is there value in having a CONTRIBUTING.rst to OpenStack?
=

Well, let's consider a few things:

* The canonical source for OpenStack repositories is https://git.openstack.org/
* OpenStack /mirrors/ to GitHub so when we add Badges to our README,
they're displayed there for people who find the projects there
* OpenStack auto-closes all pull requests made to the GitHub mirrors
with instructions on how to contribute
* Having these files isn't really a *standard*. Other services
(GitLab, BitBucket) have added support for these files, but when you
look at projects not hosted on one of those service, these files
aren't as common.
* GitHub now allows the files that they look for to be in a .github
directory so the root of the repository isn't cluttered with markdown
and other files that only GitHub cares about for providing poorly made
bandaids for serious issues in their platform.

I'm not sure there's a great deal of benefit to OpenStack projects in
these patches. I'm sure most of us don't ever look to see how many
pull requests get opened against the GitHub mirrors. I doubt these
files would stop anyone from sending pull requests there in the first
place (based entirely on my own, purely anecdotal experiences).

Further, OpenStack already has a great deal of cross-project and
project-specific documentation around contributing that's easily
findable. Making that slightly more discoverable probably isn't a bad
thing.

On top of that, some projects have had CONTRIBUTING.rst files for a
while (Glance's goes back at least to 2014). Standardization about
where to look for that info wouldn't hurt us at all.

That said, I think there are two better places for this information
that are already standards in OpenStack:

* README.rst
* HACKING.rst

Most projects include links to the contributing documentation in at
least one of these files. I think the effort here is to standardize,
albeit in a brand new file, and that's admirable.



So, I'd even take it a step further. Standardizing the README files wouldn't
hurt either. I'm not suggesting that the entire README file should be the same
for everyone but we could have a common header/top sections for every project.

I recently hit this issue when submitting patches to add badges to the README
file and, understandably, some projects weren't too happy with how the top title
section looked like. If we can make this a simple community goal, I believe it'd
be valuable.

Recardless of whether the README and HACKING files are rendered, I believe some
consistency across repos would be great. I look at README files on cloned repos
too, I don't use GH to read these files if I already have them locally.

Flavio



If you look at the gerrit query, some projects have already merged or
abandoned some of the patches. Let's see if we can come to an
agreement about how to improve the experience for people finding our
projects and wanting to collaborate with us.

[1]: 
https://review.openstack.org/#/q/owner:zhouyunfeng%40inspur.com+topic:addCONTRIBUTING.rst
--
Ian Cordasco

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


--
@flaper87
Flavio Percoco


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Thu, Dec 22, 2016 at 8:32 AM, Doug Hellmann 
wrote:

> Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> >
> > There is some ambiguity right now with projects as to where to put
> > easy-to-find documentation (even if it is just a brief paragraph with
> > a link to longer-form documentation) into our repositories. Let's
> > focus on that discussion here. We can come up with a productive
> > conclusion and work with this contributor. While you've chosen (and
> > yes, you've chosen this) to have a negative assumption about this
> > contributor's efforts, I've chosen to believe they're looking to fill
> > a gap. Increasing the productivity of new contributors to OpenStack is
> > a positive improvement for our community. It may not fix a bug or add
> > a feature, but it helps ramp up the people who will do that.
>
> I thought we started adding these contributing files specifically
> because of how they are rendered on github, as a way to try to prevent
> folks from submitting pull requests there and then having them rejected
> by the bot. It seemed more positive to give direction ahead of time than
> through a rejection message.
>

+1 to this and Ian and Alex's sentiments.

It'd be great to get people to click one more time (to a more specific
contributor guide), but let's face it, there has to be a lot of traffic
directly to github.com. Let's make sure there's a decent entry.

Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
for github, Ian?) for all projects? Is it similar to the nova 2012 version
or is there a more modern take?

Anne


>
> Doug
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Doug Hellmann]

Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> 
> There is some ambiguity right now with projects as to where to put
> easy-to-find documentation (even if it is just a brief paragraph with
> a link to longer-form documentation) into our repositories. Let's
> focus on that discussion here. We can come up with a productive
> conclusion and work with this contributor. While you've chosen (and
> yes, you've chosen this) to have a negative assumption about this
> contributor's efforts, I've chosen to believe they're looking to fill
> a gap. Increasing the productivity of new contributors to OpenStack is
> a positive improvement for our community. It may not fix a bug or add
> a feature, but it helps ramp up the people who will do that.

I thought we started adding these contributing files specifically
because of how they are rendered on github, as a way to try to prevent
folks from submitting pull requests there and then having them rejected
by the bot. It seemed more positive to give direction ahead of time than
through a rejection message.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Alexandra Settle]

My recommendation, as a documenter for OpenStack, would be to include a link to 
each project’s contributor guidelines (as most tend to keep in their developer 
documentation pages) in the README file.

I appreciate the README as previously not always been for this purpose, but I 
believe it would be beneficial to include a link and not to create a whole new 
file for the purpose of 3 lines.

I have had people in the past ask me how to contribute to individual project 
repositories, not knowing that each project has developer documentation that 
includes contributing documentation. There is clearly a gap, and this is just 
one option to fix that.

I appreciate if people disagree whoever, I don’t overly believe this is a 
necessary step as the contributor guidelines are already documented and this is 
a form of duplication.

Cheers,

Alex

On 12/22/16, 12:46 PM, "Ian Cordasco" <sigmaviru...@gmail.com> wrote:

On Wed, Dec 21, 2016 at 11:20 PM, Zhenyu Zheng
<zhengzhenyul...@gmail.com> wrote:
> Agreed with Amrith, it might be useful and maybe also good for new
> contributors to learn how to have a commit to OpenStack. BUT over 130
> identical patches to 130 different projects from one company/person in one
> run? I don't think this is going to help OpenStack growing. We should not
> let this happen.
>
> On Thu, Dec 22, 2016 at 12:44 AM, Amrith Kumar <amr...@tesora.com> wrote:
>>
>> For those who would like to know exactly what this set of changes cost in
>> the CI, the answer is approximately 1050 jobs which consumed 190 compute
>> hours of CI time.
>>
>> -amrith
>>
>> -Original Message-
>> From: Amrith Kumar [mailto:amr...@tesora.com]
>> Sent: Wednesday, December 21, 2016 11:13 AM
>> To: OpenStack Development Mailing List (not for usage questions)
>> <openstack-dev@lists.openstack.org>
>> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
>> projects
>>
>> Ian, Andreas, Emilien,
>>
>> My sentiments on the subject of these kinds of "production line" changes
>> is unchanged from [1] and [2]. A complete list of these changes is at 
[3].
>>
>> I've updated all of the changes in this thread with a block comment and a
>> -1. My apologies to other reviewers (and active contributors in those
>> projects) for this automated comment across 131 commits.
>>
>> It is high time we eliminated these kinds of changes which do little to
>> improve the overall quality of the product and serve merely to generate a
>> huge amount of pointless work on the CI systems, and boost some 
meaningless
>> statistics that someone wants to put on a slide someplace.
>>
>> -amrith
>>
>> [1] http://openstack.markmail.org/thread/dsuxy2sxxudfbij4
>> [2] http://openstack.markmail.org/thread/3sr5c2u7fhpzanit
>> [3] https://review.openstack.org/#/q/topic:addCONTRIBUTING.rst

So, I want to reiterate why I started this thread:

I want a productive outcome of this contributor's efforts. -1'ing
everyone of their changes was not something I was looking for. Having
people pile on after those -1s is also not something that leads to a
productive outcome.

Yes, these mass produced changes are annoying. I get it. We're all a
little jaded, ostensibly because we've all seen the statistical
nonsense that people at our very own companies use for marketing or
whatever else. I understand it quite well.

All of that aside, I specifically asked that we not turn this thread into 
that.

There is some ambiguity right now with projects as to where to put
easy-to-find documentation (even if it is just a brief paragraph with
a link to longer-form documentation) into our repositories. Let's
focus on that discussion here. We can come up with a productive
conclusion and work with this contributor. While you've chosen (and
yes, you've chosen this) to have a negative assumption about this
contributor's efforts, I've chosen to believe they're looking to fill
a gap. Increasing the productivity of new contributors to OpenStack is
a positive improvement for our community. It may not fix a bug or add
a feature, but it helps ramp up the people who will do that.

So please, let's keep this productive. If you want to discuss ways of
ratelimiting patchset contributions or some other nonsense, please
start a new thread.

Cheers,
-- 
Ian Cordasco

__
OpenStack Development Mailing List (not for usage questi

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Ian Cordasco]

On Wed, Dec 21, 2016 at 11:20 PM, Zhenyu Zheng
<zhengzhenyul...@gmail.com> wrote:
> Agreed with Amrith, it might be useful and maybe also good for new
> contributors to learn how to have a commit to OpenStack. BUT over 130
> identical patches to 130 different projects from one company/person in one
> run? I don't think this is going to help OpenStack growing. We should not
> let this happen.
>
> On Thu, Dec 22, 2016 at 12:44 AM, Amrith Kumar <amr...@tesora.com> wrote:
>>
>> For those who would like to know exactly what this set of changes cost in
>> the CI, the answer is approximately 1050 jobs which consumed 190 compute
>> hours of CI time.
>>
>> -amrith
>>
>> -Original Message-
>> From: Amrith Kumar [mailto:amr...@tesora.com]
>> Sent: Wednesday, December 21, 2016 11:13 AM
>> To: OpenStack Development Mailing List (not for usage questions)
>> <openstack-dev@lists.openstack.org>
>> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
>> projects
>>
>> Ian, Andreas, Emilien,
>>
>> My sentiments on the subject of these kinds of "production line" changes
>> is unchanged from [1] and [2]. A complete list of these changes is at [3].
>>
>> I've updated all of the changes in this thread with a block comment and a
>> -1. My apologies to other reviewers (and active contributors in those
>> projects) for this automated comment across 131 commits.
>>
>> It is high time we eliminated these kinds of changes which do little to
>> improve the overall quality of the product and serve merely to generate a
>> huge amount of pointless work on the CI systems, and boost some meaningless
>> statistics that someone wants to put on a slide someplace.
>>
>> -amrith
>>
>> [1] http://openstack.markmail.org/thread/dsuxy2sxxudfbij4
>> [2] http://openstack.markmail.org/thread/3sr5c2u7fhpzanit
>> [3] https://review.openstack.org/#/q/topic:addCONTRIBUTING.rst

So, I want to reiterate why I started this thread:

I want a productive outcome of this contributor's efforts. -1'ing
everyone of their changes was not something I was looking for. Having
people pile on after those -1s is also not something that leads to a
productive outcome.

Yes, these mass produced changes are annoying. I get it. We're all a
little jaded, ostensibly because we've all seen the statistical
nonsense that people at our very own companies use for marketing or
whatever else. I understand it quite well.

All of that aside, I specifically asked that we not turn this thread into that.

There is some ambiguity right now with projects as to where to put
easy-to-find documentation (even if it is just a brief paragraph with
a link to longer-form documentation) into our repositories. Let's
focus on that discussion here. We can come up with a productive
conclusion and work with this contributor. While you've chosen (and
yes, you've chosen this) to have a negative assumption about this
contributor's efforts, I've chosen to believe they're looking to fill
a gap. Increasing the productivity of new contributors to OpenStack is
a positive improvement for our community. It may not fix a bug or add
a feature, but it helps ramp up the people who will do that.

So please, let's keep this productive. If you want to discuss ways of
ratelimiting patchset contributions or some other nonsense, please
start a new thread.

Cheers,
-- 
Ian Cordasco

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Zhenyu Zheng]

Agreed with Amrith, it might be useful and maybe also good for new
contributors to learn how to have a commit to OpenStack. BUT over 130
identical patches to 130 different projects from one company/person in one
run? I don't think this is going to help OpenStack growing. We should not
let this happen.

On Thu, Dec 22, 2016 at 12:44 AM, Amrith Kumar <amr...@tesora.com> wrote:

> For those who would like to know exactly what this set of changes cost in
> the CI, the answer is approximately 1050 jobs which consumed 190 compute
> hours of CI time.
>
> -amrith
>
> -Original Message-
> From: Amrith Kumar [mailto:amr...@tesora.com]
> Sent: Wednesday, December 21, 2016 11:13 AM
> To: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
> projects
>
> Ian, Andreas, Emilien,
>
> My sentiments on the subject of these kinds of "production line" changes
> is unchanged from [1] and [2]. A complete list of these changes is at [3].
>
> I've updated all of the changes in this thread with a block comment and a
> -1. My apologies to other reviewers (and active contributors in those
> projects) for this automated comment across 131 commits.
>
> It is high time we eliminated these kinds of changes which do little to
> improve the overall quality of the product and serve merely to generate a
> huge amount of pointless work on the CI systems, and boost some meaningless
> statistics that someone wants to put on a slide someplace.
>
> -amrith
>
> [1] http://openstack.markmail.org/thread/dsuxy2sxxudfbij4
> [2] http://openstack.markmail.org/thread/3sr5c2u7fhpzanit
> [3] https://review.openstack.org/#/q/topic:addCONTRIBUTING.rst
>
> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: Wednesday, December 21, 2016 10:47 AM
> To: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
> projects
>
> On 2016-12-21 16:22, Ian Cordasco wrote:
> > [...]
> > That said, I think there are two better places for this information
> > that are already standards in OpenStack:
> >
> > * README.rst
> > * HACKING.rst
> >
> > Most projects include links to the contributing documentation in at
> > least one of these files. I think the effort here is to standardize,
> > albeit in a brand new file, and that's admirable.
>
> If that's the goal - to standardize - then I would expect that we move all
> the documentation out of those files in one place.
>
> Right now, the changes duplicate information that exists - and the new
> information is often wrong. It points to place that do not exist or where
> better places exist. ;(
>
>
> I'm fine with the status quo - of using the two files that you mention.
> Having contribution information is important,
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Amrith Kumar]

For those who would like to know exactly what this set of changes cost in the 
CI, the answer is approximately 1050 jobs which consumed 190 compute hours of 
CI time.

-amrith

-Original Message-
From: Amrith Kumar [mailto:amr...@tesora.com] 
Sent: Wednesday, December 21, 2016 11:13 AM
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

Ian, Andreas, Emilien,

My sentiments on the subject of these kinds of "production line" changes is 
unchanged from [1] and [2]. A complete list of these changes is at [3].

I've updated all of the changes in this thread with a block comment and a -1. 
My apologies to other reviewers (and active contributors in those projects) for 
this automated comment across 131 commits. 

It is high time we eliminated these kinds of changes which do little to improve 
the overall quality of the product and serve merely to generate a huge amount 
of pointless work on the CI systems, and boost some meaningless statistics that 
someone wants to put on a slide someplace.

-amrith

[1] http://openstack.markmail.org/thread/dsuxy2sxxudfbij4
[2] http://openstack.markmail.org/thread/3sr5c2u7fhpzanit
[3] https://review.openstack.org/#/q/topic:addCONTRIBUTING.rst

-Original Message-
From: Andreas Jaeger [mailto:a...@suse.com]
Sent: Wednesday, December 21, 2016 10:47 AM
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

On 2016-12-21 16:22, Ian Cordasco wrote:
> [...]
> That said, I think there are two better places for this information 
> that are already standards in OpenStack:
> 
> * README.rst
> * HACKING.rst
> 
> Most projects include links to the contributing documentation in at 
> least one of these files. I think the effort here is to standardize, 
> albeit in a brand new file, and that's admirable.

If that's the goal - to standardize - then I would expect that we move all the 
documentation out of those files in one place.

Right now, the changes duplicate information that exists - and the new 
information is often wrong. It points to place that do not exist or where 
better places exist. ;(


I'm fine with the status quo - of using the two files that you mention.
Having contribution information is important,

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


smime.p7s
Description: S/MIME cryptographic signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Amrith Kumar]

Ian, Andreas, Emilien,

My sentiments on the subject of these kinds of "production line" changes is 
unchanged from [1] and [2]. A complete list of these changes is at [3].

I've updated all of the changes in this thread with a block comment and a -1. 
My apologies to other reviewers (and active contributors in those projects) for 
this automated comment across 131 commits. 

It is high time we eliminated these kinds of changes which do little to improve 
the overall quality of the product and serve merely to generate a huge amount 
of pointless work on the CI systems, and boost some meaningless statistics that 
someone wants to put on a slide someplace.

-amrith

[1] http://openstack.markmail.org/thread/dsuxy2sxxudfbij4
[2] http://openstack.markmail.org/thread/3sr5c2u7fhpzanit
[3] https://review.openstack.org/#/q/topic:addCONTRIBUTING.rst

-Original Message-
From: Andreas Jaeger [mailto:a...@suse.com] 
Sent: Wednesday, December 21, 2016 10:47 AM
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

On 2016-12-21 16:22, Ian Cordasco wrote:
> [...]
> That said, I think there are two better places for this information
> that are already standards in OpenStack:
> 
> * README.rst
> * HACKING.rst
> 
> Most projects include links to the contributing documentation in at
> least one of these files. I think the effort here is to standardize,
> albeit in a brand new file, and that's admirable.

If that's the goal - to standardize - then I would expect that we move
all the documentation out of those files in one place.

Right now, the changes duplicate information that exists - and the new
information is often wrong. It points to place that do not exist or
where better places exist. ;(


I'm fine with the status quo - of using the two files that you mention.
Having contribution information is important,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Ian Cordasco]

-Original Message-
From: Andrey Kurilin <akuri...@mirantis.com>
Reply: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Date: December 21, 2016 at 10:11:42
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

> Hi stackers!
>  
> On Wed, Dec 21, 2016 at 5:33 PM, Emilien Macchi wrote:
>  
> > On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco  
> > wrote:
> > > Hey everyone,
> > >
> > > It seems a contributor has written a script to add CONTRIBUTING.rst
> > > files to each OpenStack project that exists. [1]
> >
> > Thanks Ian for starting this discussion, it's very appreciated.
> >
> > It would have been great if the author of these patches would have run
> > this discussion before.
> > Just for Puppet OpenStack projects, it has consumed ~450 CI jobs
> > for... nothing (all patches will require some adjustments if we decide
> > to keep this file).
> >
>  
> You can configure your heavy jobs to not be launched on *.rst changes ;)
>  
>  
> > I can't imagine how many resources we consumed across all OpenStack
> > projects with this batch of patches...
> >
> > > As a community we've struggled with new contributors creating tonnes
> > > of patches like this at once, and that is emphatically not the purpose
> > > of this email. Instead, I'd like to discuss the actual merits of this
> > > change for OpenStack.
> > >
> > > What is CONTRIBUTING.rst?
> > > =
> > >
> > > It's a convention created by GitHub to make up for the lack of issue
> > > templating and encourage collaborators/contributors to read some
> > > documentation before filing new issues or pull requests. It does this
> > > by adding an unobtrusive link at the top of the New Issue and New Pull
> > > Request pages for projects that have these files.
> > >
> > > In my experience using these files on projects, they've been wildly
> > ineffective.
> > >
> > > Is there value in having a CONTRIBUTING.rst to OpenStack?
> > > =
> > >
> > > Well, let's consider a few things:
> > >
> > > * The canonical source for OpenStack repositories is
> > https://git.openstack.org/
> > > * OpenStack /mirrors/ to GitHub so when we add Badges to our README,
> > > they're displayed there for people who find the projects there
> >
>  
> Adding Badges is a sign that there are a lot of people who like finding
> everything in project
> repository.
> GitHub is just a mirror, but it is a first link of results list while
> googling, git.openstack.org is:
> - a second link in case of "openstack nova git" query;
> - a third link in case of "openstack keystone git;"
> - a fourth link in case of "openstack horizon git".
>  
> GitHub is a nice entry-point for new contributors. I do not want to say
> them
> "forget everything you know".

Except that learning to contribute to projects on GitHub is far from useful for 
them when looking at a project like ours or an Apache Software Foundation 
project or some of the projects open sourced by companies like Google.

> If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for
> adding it.

Anecdotally speaking, it doesn't help new contributors though. Hence why I sent 
this email. If I felt it would have a measurable positive impact, I wouldn't 
have written this email. :)

> > > * OpenStack auto-closes all pull requests made to the GitHub mirrors
> > > with instructions on how to contribute
> > > * Having these files isn't really a *standard*. Other services
> > > (GitLab, BitBucket) have added support for these files, but when you
> > > look at projects not hosted on one of those service, these files
> > > aren't as common.
> >
>  
> If GitHub, GitLab, BitBucket support that file, having CONTRIBUTING.rst
> sounds like
> a standard for me.

That's not what defines a standard. One company coming up with a bandaid that a 
few others scrambled to support isn't a standard, it's a fad.

> > > * GitHub now allows the files that they look for to be in a .github
> > > directory so the root of the repository isn't cluttered with markdown
> > > and other files that only GitHub cares about for providing poorly made
> > > bandaids for serious issues in their platform.
> > >
> > > I'm not su

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Ian Cordasco]

-Original Message-
From: Andrey Kurilin <akuri...@mirantis.com>
Reply: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Date: December 21, 2016 at 10:13:09
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

> On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
>  
> > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > [...]
> > > That said, I think there are two better places for this information
> > > that are already standards in OpenStack:
> > >
> > > * README.rst
> > > * HACKING.rst
> > >
> > > Most projects include links to the contributing documentation in at
> > > least one of these files. I think the effort here is to standardize,
> > > albeit in a brand new file, and that's admirable.
> >
> > If that's the goal - to standardize - then I would expect that we move
> > all the documentation out of those files in one place.
> >
> > Right now, the changes duplicate information that exists - and the new
> > information is often wrong. It points to place that do not exist or
> > where better places exist. ;(
> >
>  
> Duplication can be reduced by using `.. include:: ` directive.

That does not render anywhere except our documentation (via Sphinx). 
Git{Hub,Lab} don't render the include directive at all.

So, no, that's not an option.

--  
Ian Cordasco


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andrey Kurilin]

On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger  wrote:

> On 2016-12-21 16:22, Ian Cordasco wrote:
> > [...]
> > That said, I think there are two better places for this information
> > that are already standards in OpenStack:
> >
> > * README.rst
> > * HACKING.rst
> >
> > Most projects include links to the contributing documentation in at
> > least one of these files. I think the effort here is to standardize,
> > albeit in a brand new file, and that's admirable.
>
> If that's the goal - to standardize - then I would expect that we move
> all the documentation out of those files in one place.
>
> Right now, the changes duplicate information that exists - and the new
> information is often wrong. It points to place that do not exist or
> where better places exist. ;(
>

Duplication can be reduced by using `.. include:: ` directive.

>
>
> I'm fine with the status quo - of using the two files that you mention.
> Having contribution information is important,
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Best regards,
Andrey Kurilin.
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andrey Kurilin]

Hi stackers!

On Wed, Dec 21, 2016 at 5:33 PM, Emilien Macchi  wrote:

> On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco 
> wrote:
> > Hey everyone,
> >
> > It seems a contributor has written a script to add CONTRIBUTING.rst
> > files to each OpenStack project that exists. [1]
>
> Thanks Ian for starting this discussion, it's very appreciated.
>
> It would have been great if the author of these patches would have run
> this discussion before.
> Just for Puppet OpenStack projects, it has consumed ~450 CI jobs
> for... nothing (all patches will require some adjustments if we decide
> to keep this file).
>

You can configure your heavy jobs to not be launched on *.rst changes ;)


> I can't imagine how many resources we consumed across all OpenStack
> projects with this batch of patches...
>
> > As a community we've struggled with new contributors creating tonnes
> > of patches like this at once, and that is emphatically not the purpose
> > of this email. Instead, I'd like to discuss the actual merits of this
> > change for OpenStack.
> >
> > What is CONTRIBUTING.rst?
> > =
> >
> > It's a convention created by GitHub to make up for the lack of issue
> > templating and encourage collaborators/contributors to read some
> > documentation before filing new issues or pull requests. It does this
> > by adding an unobtrusive link at the top of the New Issue and New Pull
> > Request pages for projects that have these files.
> >
> > In my experience using these files on projects, they've been wildly
> ineffective.
> >
> > Is there value in having a CONTRIBUTING.rst to OpenStack?
> > =
> >
> > Well, let's consider a few things:
> >
> > * The canonical source for OpenStack repositories is
> https://git.openstack.org/
> > * OpenStack /mirrors/ to GitHub so when we add Badges to our README,
> > they're displayed there for people who find the projects there
>

Adding Badges is a sign that there are a lot of people who like finding
everything in project
repository.
GitHub is just a mirror, but it is a first link of results list while
googling, git.openstack.org is:
 - a second link in case of "openstack nova git" query;
 - a third link in case of "openstack keystone git;"
 - a fourth link in case of "openstack horizon git".

GitHub is a nice entry-point for new contributors. I do not want to say
them
"forget everything you know".
If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for
adding it.


> > * OpenStack auto-closes all pull requests made to the GitHub mirrors
> > with instructions on how to contribute
> > * Having these files isn't really a *standard*. Other services
> > (GitLab, BitBucket) have added support for these files, but when you
> > look at projects not hosted on one of those service, these files
> > aren't as common.
>

If GitHub, GitLab, BitBucket support that file, having CONTRIBUTING.rst
sounds like
a standard for me.


> > * GitHub now allows the files that they look for to be in a .github
> > directory so the root of the repository isn't cluttered with markdown
> > and other files that only GitHub cares about for providing poorly made
> > bandaids for serious issues in their platform.
> >
> > I'm not sure there's a great deal of benefit to OpenStack projects in
> > these patches. I'm sure most of us don't ever look to see how many
> > pull requests get opened against the GitHub mirrors. I doubt these
> > files would stop anyone from sending pull requests there in the first
> > place (based entirely on my own, purely anecdotal experiences).
> >
> > Further, OpenStack already has a great deal of cross-project and
> > project-specific documentation around contributing that's easily
> > findable. Making that slightly more discoverable probably isn't a bad
> > thing.
> >
> > On top of that, some projects have had CONTRIBUTING.rst files for a
> > while (Glance's goes back at least to 2014).
>

Nova has it since 21 Nov 2012 ;)


> Standardization about
> > where to look for that info wouldn't hurt us at all.
> >
> > That said, I think there are two better places for this information
> > that are already standards in OpenStack:
> >
> > * README.rst
> > * HACKING.rst
> >
> > Most projects include links to the contributing documentation in at
> > least one of these files. I think the effort here is to standardize,
> > albeit in a brand new file, and that's admirable.
>
>
It is true. Regularly, README.rst includes "how-to contribute" stuff, but
"ideal" README should describe a lot of things about projects and it can
become huge enough, so new contributors can miss "how-to contribute"
section
there (README often doesn't have content list at the top of file).

+1 on those files.
>
> > If you look at the gerrit query, some projects have already merged or
> > abandoned some of the patches. Let's see if we can come to an
> > agreement about how to improve the experience for 

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Ian Cordasco]

 

-Original Message-
From: Andreas Jaeger <a...@suse.com>
Reply: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Date: December 21, 2016 at 09:48:20
To: OpenStack Development Mailing List (not for usage questions) 
<openstack-dev@lists.openstack.org>
Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

> On 2016-12-21 16:22, Ian Cordasco wrote:
> > [...]
> > That said, I think there are two better places for this information
> > that are already standards in OpenStack:
> >
> > * README.rst
> > * HACKING.rst
> >
> > Most projects include links to the contributing documentation in at
> > least one of these files. I think the effort here is to standardize,
> > albeit in a brand new file, and that's admirable.
>  
> If that's the goal - to standardize - then I would expect that we move
> all the documentation out of those files in one place. 

The best reasoning I can come up with for a mass number of changes like this is 
to standardize a bit. I could be entirely wrong, but sending these changes in 
the interest of standardization is the best possible assumption I can make 
about the contributor's intentions.

> Right now, the changes duplicate information that exists - and the new
> information is often wrong. It points to place that do not exist or
> where better places exist. ;(

I agree. This is why I've been -1'ing or -2'ing these patches on projects.

> I'm fine with the status quo - of using the two files that you mention.
> Having contribution information is important,

The status quo is far from perfect, but it seems to have worked well enough for 
a few years now.

--  
Ian Cordasco


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Andreas Jaeger]

On 2016-12-21 16:22, Ian Cordasco wrote:
> [...]
> That said, I think there are two better places for this information
> that are already standards in OpenStack:
> 
> * README.rst
> * HACKING.rst
> 
> Most projects include links to the contributing documentation in at
> least one of these files. I think the effort here is to standardize,
> albeit in a brand new file, and that's admirable.

If that's the goal - to standardize - then I would expect that we move
all the documentation out of those files in one place.

Right now, the changes duplicate information that exists - and the new
information is often wrong. It points to place that do not exist or
where better places exist. ;(


I'm fine with the status quo - of using the two files that you mention.
Having contribution information is important,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Emilien Macchi]

On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco  wrote:
> Hey everyone,
>
> It seems a contributor has written a script to add CONTRIBUTING.rst
> files to each OpenStack project that exists. [1]

Thanks Ian for starting this discussion, it's very appreciated.

It would have been great if the author of these patches would have run
this discussion before.
Just for Puppet OpenStack projects, it has consumed ~450 CI jobs
for... nothing (all patches will require some adjustments if we decide
to keep this file).
I can't imagine how many resources we consumed across all OpenStack
projects with this batch of patches...

> As a community we've struggled with new contributors creating tonnes
> of patches like this at once, and that is emphatically not the purpose
> of this email. Instead, I'd like to discuss the actual merits of this
> change for OpenStack.
>
> What is CONTRIBUTING.rst?
> =
>
> It's a convention created by GitHub to make up for the lack of issue
> templating and encourage collaborators/contributors to read some
> documentation before filing new issues or pull requests. It does this
> by adding an unobtrusive link at the top of the New Issue and New Pull
> Request pages for projects that have these files.
>
> In my experience using these files on projects, they've been wildly 
> ineffective.
>
> Is there value in having a CONTRIBUTING.rst to OpenStack?
> =
>
> Well, let's consider a few things:
>
> * The canonical source for OpenStack repositories is 
> https://git.openstack.org/
> * OpenStack /mirrors/ to GitHub so when we add Badges to our README,
> they're displayed there for people who find the projects there
> * OpenStack auto-closes all pull requests made to the GitHub mirrors
> with instructions on how to contribute
> * Having these files isn't really a *standard*. Other services
> (GitLab, BitBucket) have added support for these files, but when you
> look at projects not hosted on one of those service, these files
> aren't as common.
> * GitHub now allows the files that they look for to be in a .github
> directory so the root of the repository isn't cluttered with markdown
> and other files that only GitHub cares about for providing poorly made
> bandaids for serious issues in their platform.
>
> I'm not sure there's a great deal of benefit to OpenStack projects in
> these patches. I'm sure most of us don't ever look to see how many
> pull requests get opened against the GitHub mirrors. I doubt these
> files would stop anyone from sending pull requests there in the first
> place (based entirely on my own, purely anecdotal experiences).
>
> Further, OpenStack already has a great deal of cross-project and
> project-specific documentation around contributing that's easily
> findable. Making that slightly more discoverable probably isn't a bad
> thing.
>
> On top of that, some projects have had CONTRIBUTING.rst files for a
> while (Glance's goes back at least to 2014). Standardization about
> where to look for that info wouldn't hurt us at all.
>
> That said, I think there are two better places for this information
> that are already standards in OpenStack:
>
> * README.rst
> * HACKING.rst
>
> Most projects include links to the contributing documentation in at
> least one of these files. I think the effort here is to standardize,
> albeit in a brand new file, and that's admirable.

+1 on those files.

> If you look at the gerrit query, some projects have already merged or
> abandoned some of the patches. Let's see if we can come to an
> agreement about how to improve the experience for people finding our
> projects and wanting to collaborate with us.
>
> [1]: 
> https://review.openstack.org/#/q/owner:zhouyunfeng%40inspur.com+topic:addCONTRIBUTING.rst
> --
> Ian Cordasco
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 
Emilien Macchi

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Ian Cordasco]

Hey everyone,

It seems a contributor has written a script to add CONTRIBUTING.rst
files to each OpenStack project that exists. [1]

As a community we've struggled with new contributors creating tonnes
of patches like this at once, and that is emphatically not the purpose
of this email. Instead, I'd like to discuss the actual merits of this
change for OpenStack.

What is CONTRIBUTING.rst?
=

It's a convention created by GitHub to make up for the lack of issue
templating and encourage collaborators/contributors to read some
documentation before filing new issues or pull requests. It does this
by adding an unobtrusive link at the top of the New Issue and New Pull
Request pages for projects that have these files.

In my experience using these files on projects, they've been wildly ineffective.

Is there value in having a CONTRIBUTING.rst to OpenStack?
=

Well, let's consider a few things:

* The canonical source for OpenStack repositories is https://git.openstack.org/
* OpenStack /mirrors/ to GitHub so when we add Badges to our README,
they're displayed there for people who find the projects there
* OpenStack auto-closes all pull requests made to the GitHub mirrors
with instructions on how to contribute
* Having these files isn't really a *standard*. Other services
(GitLab, BitBucket) have added support for these files, but when you
look at projects not hosted on one of those service, these files
aren't as common.
* GitHub now allows the files that they look for to be in a .github
directory so the root of the repository isn't cluttered with markdown
and other files that only GitHub cares about for providing poorly made
bandaids for serious issues in their platform.

I'm not sure there's a great deal of benefit to OpenStack projects in
these patches. I'm sure most of us don't ever look to see how many
pull requests get opened against the GitHub mirrors. I doubt these
files would stop anyone from sending pull requests there in the first
place (based entirely on my own, purely anecdotal experiences).

Further, OpenStack already has a great deal of cross-project and
project-specific documentation around contributing that's easily
findable. Making that slightly more discoverable probably isn't a bad
thing.

On top of that, some projects have had CONTRIBUTING.rst files for a
while (Glance's goes back at least to 2014). Standardization about
where to look for that info wouldn't hurt us at all.

That said, I think there are two better places for this information
that are already standards in OpenStack:

* README.rst
* HACKING.rst

Most projects include links to the contributing documentation in at
least one of these files. I think the effort here is to standardize,
albeit in a brand new file, and that's admirable.

If you look at the gerrit query, some projects have already merged or
abandoned some of the patches. Let's see if we can come to an
agreement about how to improve the experience for people finding our
projects and wanting to collaborate with us.

[1]: 
https://review.openstack.org/#/q/owner:zhouyunfeng%40inspur.com+topic:addCONTRIBUTING.rst
--
Ian Cordasco

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev