llvm dev - Nov 2019 - [RFC] Let's add a CONTRIBUTING.md file to llvm-project

Hi,

With multiple proposals to improve the situation for newcomers in flight, let me
add another brief proposal:

Let’s add a CONTRIBUTING.md file to the top-level directory of llvm-project.

I think this would make the information about how to contribute more visible and
Github uses CONTRIBUTING.md to display ‘Contributing Guidelines’ at a few
places, like when creating new issues or pull requests
(https://github.blog/2012-09-17-contributing-guidelines/
<https://github.blog/2012-09-17-contributing-guidelines/>). This would be
a suitable place to mention that we are not using Github issues/PRs and point to
the current procedures for filing issues and sharing patches.

If we decide to add a CONTRIBUTING.md file, the next question is what the
content should be. We already have a page intended to summarize the information
necessary to file bugs and contribute patches:
https://llvm.org/docs/Contributing.html
<https://llvm.org/docs/Contributing.html>

We could either 

1. Duplicate the content of llvm/docs/Contributing.rst in the CONTRIBUTING.md
file (I put up a patch to do that a while ago before the transition to the
mono-repo, but abandoned it  because the feedback was that it was not the right
time to do it https://reviews.llvm.org/D59108
<https://reviews.llvm.org/D59108>)

2. Have CONTRIBUTING.md mention that Github Issues/PRs are not used at the
moment and link to https://llvm.org/docs/Contributing.html
<https://llvm.org/docs/Contributing.html>.

3. Move the contents of llvm/docs/Contributing.rst from the docs to
CONTRIBUTING.md. Have https://llvm.org/docs/Contributing.html
<https://llvm.org/docs/Contributing.html> redirect to CONTRIBUTING.md on
Github.

Personally I think we should either go with 2. or 3.

Please let me know what you think!

Cheers,
Florian
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191122/0210e59f/attachment.html>

I don't have any strong opinion on this except that I'd like to avoid
1),
because just as in code, duplicated documentation invariably ends up with
one or both versions going stale. If push came to shove, I think I'd
marginally prefer 2, since the rest of our documentation is on the website.

James

On Fri, 22 Nov 2019 at 14:40, Florian Hahn via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> Hi,
>
> With multiple proposals to improve the situation for newcomers in flight,
> let me add another brief proposal:
>
> Let’s add a CONTRIBUTING.md file to the top-level directory of
> llvm-project.
>
> I think this would make the information about how to contribute more
> visible and Github uses CONTRIBUTING.md to display ‘Contributing
> Guidelines’ at a few places, like when creating new issues or pull requests
> (https://github.blog/2012-09-17-contributing-guidelines/). This would be
> a suitable place to mention that we are not using Github issues/PRs and
> point to the current procedures for filing issues and sharing patches.
>
> If we decide to add a CONTRIBUTING.md file, the next question is what the
> content should be. We already have a page intended to summarize the
> information necessary to file bugs and contribute patches:
> https://llvm.org/docs/Contributing.html
>
> We could either
>
> 1. Duplicate the content of llvm/docs/Contributing.rst in the
> CONTRIBUTING.md file (I put up a patch to do that a while ago before the
> transition to the mono-repo, but abandoned it  because the feedback was
> that it was not the right time to do it https://reviews.llvm.org/D59108)
>
> 2. Have CONTRIBUTING.md mention that Github Issues/PRs are not used at the
> moment and link to https://llvm.org/docs/Contributing.html.
>
> 3. Move the contents of llvm/docs/Contributing.rst from the docs to
> CONTRIBUTING.md. Have https://llvm.org/docs/Contributing.html redirect to
> CONTRIBUTING.md on Github.
>
> Personally I think we should either go with 2. or 3.
>
> Please let me know what you think!
>
> Cheers,
> Florian
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191122/6e82c70b/attachment-0001.html>

I think you could go ahead and do 2 in the interim without waiting for this
to reach consensus.

In the long run, I suppose I prefer 3. Our doc update system is down at the
moment anyway. Might as well leverage github for now.

On Fri, Nov 22, 2019 at 6:40 AM Florian Hahn via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> Hi,
>
> With multiple proposals to improve the situation for newcomers in flight,
> let me add another brief proposal:
>
> Let’s add a CONTRIBUTING.md file to the top-level directory of
> llvm-project.
>
> I think this would make the information about how to contribute more
> visible and Github uses CONTRIBUTING.md to display ‘Contributing
> Guidelines’ at a few places, like when creating new issues or pull requests
> (https://github.blog/2012-09-17-contributing-guidelines/). This would be
> a suitable place to mention that we are not using Github issues/PRs and
> point to the current procedures for filing issues and sharing patches.
>
> If we decide to add a CONTRIBUTING.md file, the next question is what the
> content should be. We already have a page intended to summarize the
> information necessary to file bugs and contribute patches:
> https://llvm.org/docs/Contributing.html
>
> We could either
>
> 1. Duplicate the content of llvm/docs/Contributing.rst in the
> CONTRIBUTING.md file (I put up a patch to do that a while ago before the
> transition to the mono-repo, but abandoned it  because the feedback was
> that it was not the right time to do it https://reviews.llvm.org/D59108)
>
> 2. Have CONTRIBUTING.md mention that Github Issues/PRs are not used at the
> moment and link to https://llvm.org/docs/Contributing.html.
>
> 3. Move the contents of llvm/docs/Contributing.rst from the docs to
> CONTRIBUTING.md. Have https://llvm.org/docs/Contributing.html redirect to
> CONTRIBUTING.md on Github.
>
> Personally I think we should either go with 2. or 3.
>
> Please let me know what you think!
>
> Cheers,
> Florian
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191122/33f3a905/attachment.html>

+1 to Reid's comment and the original proposal.

On 11/22/2019 11:33 AM, Reid Kleckner via llvm-dev
wrote:
> I think you could go ahead and do 2 in the interim without waiting for 
> this to reach consensus.
>
> In the long run, I suppose I prefer 3. Our doc update system is down 
> at the moment anyway. Might as well leverage github for now.
>
> On Fri, Nov 22, 2019 at 6:40 AM Florian Hahn via llvm-dev 
> <llvm-dev at lists.llvm.org <mailto:llvm-dev at
lists.llvm.org>> wrote:
>
>     Hi,
>
>     With multiple proposals to improve the situation for newcomers in
>     flight, let me add another brief proposal:
>
>     Let’s add a CONTRIBUTING.md file to the top-level directory of
>     llvm-project.
>
>     I think this would make the information about how to contribute
>     more visible and Github uses CONTRIBUTING.md to display
>     ‘Contributing Guidelines’ at a few places, like when creating new
>     issues or pull requests
>     (https://github.blog/2012-09-17-contributing-guidelines/). This
>     would be a suitable place to mention that we are not using Github
>     issues/PRs and point to the current procedures for filing issues
>     and sharing patches.
>
>     If we decide to add a CONTRIBUTING.md file, the next question is
>     what the content should be. We already have a page intended to
>     summarize the information necessary to file bugs and contribute
>     patches: https://llvm.org/docs/Contributing.html
>
>     We could either
>
>     1. Duplicate the content of llvm/docs/Contributing.rst in the
>     CONTRIBUTING.md file (I put up a patch to do that a while ago
>     before the transition to the mono-repo, but abandoned it  because
>     the feedback was that it was not the right time to do it
>     https://reviews.llvm.org/D59108)
>
>     2. Have CONTRIBUTING.md mention that Github Issues/PRs are not
>     used at the moment and link to
>     https://llvm.org/docs/Contributing.html.
>
>     3. Move the contents of llvm/docs/Contributing.rst from the docs
>     to CONTRIBUTING.md. Have
>     https://llvm.org/docs/Contributing.html redirect to
>     CONTRIBUTING.md on Github.
>
>     Personally I think we should either go with 2. or 3.
>
>     Please let me know what you think!
>
>     Cheers,
>     Florian
>     _______________________________________________
>     LLVM Developers mailing list
>     llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>     https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20191124/a8f64379/attachment.html>