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


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!


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.


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.

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

Thanks everyone for taking a look! I’ve put up a draft patch at https://reviews.llvm.org/D70743

It would be great if you could take a look and let me know if you have any suggestions on how to make the wording more welcoming!