[Docs] Add Contributing page.

[fhahn]

Summary

This new page acts as an entry point for (new) contributors to LLVM and
provides information about

• What to contribute
• How to submit a patch
• Where to start to learn more about LLVM's architecture and internals.

This version of the page duplicates some information from the
DeveloperPolicy and Phabricator pages. Subsequent changes should work
towards moving information for new developers to this page, where it
makes sense.

[fhahn]

Contributing.html8 KBDownload

Add rendered version of the page (CSS & co missing)

[JonasToth]

docs/Contributing.rst

69 ↗

(On Diff #128414)

at then looks incorrect to me. Only the?

[asb]

This is a great initiative Florian - many thanks for kicking this off.

I wonder if it would be helpful to try to change include changes to docs/DeveloperPolicy.rst and docs/Phabricator.rst in this patch. I can see the argument for trying to keep it self-contained, but you could also see this patch as being a partial "refactoring" of the current guidance for contributors, which is split across multiple files. e.g. here and guidance on picking reviewers here.

I think the way the document is currently structured works and has some advantages, but it might be worth considering an alternative. The way I see it, there are two likely readers of this documentation:

1. People new to LLVM who are interested in getting involved in both compiler development and upstream LLVM
2. People with some experience hacking LLVM or other compilers but are looking for information on how to work with the upstream LLVM community (or do you disagree, and think this case is adequately covered by DeveloperPolicy and the Phabricator code review docs?)

With that in mind, perhaps it makes sense to split the document in to one section covering how to find something to work on and a second section which details the practicalities of preparing your changes for submission? I don't feel particularly strongly about this, but figured I'd share the thought.

[fhahn]

In D41665#965809, @asb wrote:

This is a great initiative Florian - many thanks for kicking this off.

I wonder if it would be helpful to try to change include changes to docs/DeveloperPolicy.rst and docs/Phabricator.rst in this patch. I can see the argument for trying to keep it self-contained, but you could also see this patch as being a partial "refactoring" of the current guidance for contributors, which is split across multiple files. e.g. here and guidance on picking reviewers here.

I am all in favor of partially refactoring the docs on that topic. But I am afraid I am not sure I understand entirely what you suggest here. Do you mean moving important info from the developer policy to docs/Contributing.rst? Or the other way around?

IMO, I think there is value in a self contained contributing document. For example, I think Rust's Contributing info is quite good: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
Although putting too much in a single document would be counterproductive as well.

I think the way the document is currently structured works and has some advantages, but it might be worth considering an alternative. The way I see it, there are two likely readers of this documentation:

1. People new to LLVM who are interested in getting involved in both compiler development and upstream LLVM
2. People with some experience hacking LLVM or other compilers but are looking for information on how to work with the upstream LLVM community (or do you disagree, and think this case is adequately covered by DeveloperPolicy and the Phabricator code review docs?)

With that in mind, perhaps it makes sense to split the document in to one section covering how to find something to work on and a second section which details the practicalities of preparing your changes for submission? I don't feel particularly strongly about this, but figured I'd share the thought.

Thanks Alex. Yes I think it makes sense to split that up!

[nemanjai]

I think it's really cool that you've started on this and I think this is a great start. Thanks.

However, what I commonly see coming through the dev list in terms of questions from beginners are questions about how to familiarize oneself with the LLVM code base and infrastructure. I think a beginners page should include all this info you added here about what to work on and how to contribute, but also where to learn. I think this information is kind of strewn all over the place and a nice summary would be useful. I think "User Guides", "Programming Documentation" and "Subsystem Documentation" sections contain a wealth of useful information, but I think it can be overwhelming to a new contributor.
What do I need to read to fix this beginner bug? Which of these are generally useful and which are useful to some specific subset of developers? etc...
Perhaps this page can be a general entry point for new contributors. It can include the information you included here and then it can include a section on "Familiarizing Yourself With LLVM" where we would initially link documents that are useful for new Front-End/Back-End/Middle-End developers. Then I think new contributors should be encouraged to contribute to this page and improve it with their experience.

I wonder if we can start with something kind of small and limited that will grow into a useful, comprehensive, easy-to-navigate entry point for new contributors.

docs/Contributing.rst

7 ↗

(On Diff #128414)

This sentence seems a bit weird. It sounds like "we appreciate the different ways of contributing" rather than "we appreciate all contributions".

[asb]

In D41665#965824, @fhahn wrote:

In D41665#965809, @asb wrote:

This is a great initiative Florian - many thanks for kicking this off.

I wonder if it would be helpful to try to change include changes to docs/DeveloperPolicy.rst and docs/Phabricator.rst in this patch. I can see the argument for trying to keep it self-contained, but you could also see this patch as being a partial "refactoring" of the current guidance for contributors, which is split across multiple files. e.g. here and guidance on picking reviewers here.

I am all in favor of partially refactoring the docs on that topic. But I am afraid I am not sure I understand entirely what you suggest here. Do you mean moving important info from the developer policy to docs/Contributing.rst? Or the other way around?

IMO, I think there is value in a self contained contributing document. For example, I think Rust's Contributing info is quite good: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
Although putting too much in a single document would be counterproductive as well.

I meant the first. Right now we have info about contributing spread across several places. This patch consolidates that information (great!) but ends up adding a little more duplication because it doesn't replace the existing info with references to docs/Contributing.rst. It could make sense to get docs/Contributing.rst committed then consider whether other docs can be updated to reference it, or instead to try to incorporate those changes in this patch. I don't feel particularly strongly either way.

[fhahn]

In D41665#965831, @nemanjai wrote:

I think it's really cool that you've started on this and I think this is a great start. Thanks.

However, what I commonly see coming through the dev list in terms of questions from beginners are questions about how to familiarize oneself with the LLVM code base and infrastructure. I think a beginners page should include all this info you added here about what to work on and how to contribute, but also where to learn. I think this information is kind of strewn all over the place and a nice summary would be useful. I think "User Guides", "Programming Documentation" and "Subsystem Documentation" sections contain a wealth of useful information, but I think it can be overwhelming to a new contributor.
What do I need to read to fix this beginner bug? Which of these are generally useful and which are useful to some specific subset of developers? etc...
Perhaps this page can be a general entry point for new contributors. It can include the information you included here and then it can include a section on "Familiarizing Yourself With LLVM" where we would initially link documents that are useful for new Front-End/Back-End/Middle-End developers. Then I think new contributors should be encouraged to contribute to this page and improve it with their experience.

Thanks! The "Familiarizing Yourself With LLVM" is an excellent suggestion and should be part of this document.

I wonder if we can start with something kind of small and limited that will grow into a useful, comprehensive, easy-to-navigate entry point for new contributors.

That was my hope. I think a sensible way to go about this would be to add a first version of the document and go from there. And hopefully it will get better with feedback from new contributors.

[fhahn]

In D41665#965834, @asb wrote:

I meant the first. Right now we have info about contributing spread across several places. This patch consolidates that information (great!) but ends up adding a little more duplication because it doesn't replace the existing info with references to docs/Contributing.rst. It could make sense to get docs/Contributing.rst committed then consider whether other docs can be updated to reference it, or instead to try to incorporate those changes in this patch. I don't feel particularly strongly either way.

Ok great! I agree that in the end, we should get rid of the duplication and I am slightly worried about the additional duplication added by this patch. If people are happy with consolidating some documentation under the Contributing page, I am happy to link to the Contributing page DeveloperPolicy & co.

I hope this patch can get things started, we can agree on what the end goal should be and start to gradually move some documentation over to the Contributing page, if it makes sense. I expect this to be an incremental process, as we hopefully get some helpful feedback from new contributors. Also, I am not confident enough in my writing skills to single-handedly take on a substantial rework of the docs in a single big patch ;)

[sdardis]

Thanks for doing this, @fhahn.

A few small comments.

docs/Contributing.rst

29 ↗

(On Diff #128414)

"assign it to you" -> "assign it to yourself"

39 ↗

(On Diff #128414)

Colon after should.

55 ↗

(On Diff #128414)

I suggest adding a short paragraph stating that reviewers may request changes, and that if you are uncertain on how provide test cases/documentation to ask for guidance.

The previous and following paragraphs IMHO jump from "how to submit" to "when you patch is accepted". A brief description of our process of having patches go through a cycle of changes required / repost with fixes should be included.

57 ↗

(On Diff #128414)

"In case you do not yet have commit access" -> "If you do not have commit access"

This matches the Phabricator documentation we have, and I think it's a little more straight forward.

62 ↗

(On Diff #128414)

"In that case you can ping the patch. The common courtesy ping rate is one week."

->

"If you have received no comments on your patch for a week, you can request a review by 'ping'ing a patch by responding to the email thread containing the patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate is once a week."

My suggestion here is based off new contributors not necessarily knowing the fairly common terminology.

63 ↗

(On Diff #128414)

"Remember" -> "Please remember"

[fhahn]

Thanks for all the feedback. I've included the wording improvements. I also restructured the document in 3 main sections

• Ways to Contribute
• How to Submit a Patch
• Helpful Information About LLVM

The last section contains a couple of links to pages giving an overview of LLVM's structure and internals.

[nemanjai]

I think this is a great start. Thanks Florian.

[fhahn]

Contributing.html11 KBDownload

Rendered version with latest changes

[silvas]

This is awesome, thanks for doing this Florian!

I agree with others that we have various newbie information spread across various pages, but refactoring that is a bigger task and this is a great start (besides being an awesome independent improvement by itself).

docs/Contributing.rst

64 ↗

(On Diff #128522)

Can you somehow mention that adding a reviewer for an email patch means adding them to the CC of the email and that for Phab that means to fill in the field in the web UI?

[fhahn]

Add info about how to add reviewers in phabricator & email reviews. Also updated the description.

llvm/trunk/docs/Contributing.rst

+==================================
+Contributing to LLVM
+==================================
+
+
+Thank you for your interest in contributing to LLVM! There are multiple ways to
+contribute, and we appreciate all contributions. In case you
+have questions, you can either use the `Developer's List (llvm-dev)`_
+or the #llvm channel on `irc.oftc.net`_.
+
+If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`.
+
+.. contents::
+  :local:
+
+
+Ways to Contribute
+==================
+
+Bug Reports
+-----------
+If you are working with LLVM and run into a bug, we definitely want to know
+about it. Please let us know and follow the instructions in
+:doc:`HowToSubmitABug`  to create a bug report.
+
+Bug Fixes
+---------
+If you are interested in contributing code to LLVM, bugs labeled with the
+`beginner keyword`_ in the `bug tracker`_ are a good way to get familiar with
+the code base. If you are interested in fixing a bug, please create an account
+for the bug tracker and assign it to yourself, to let people know you are working on
+it.
+
+Then try to reproduce and fix the bug with upstream LLVM. Start by building
+LLVM from source as described in :doc:`GettingStarted` and
+and use the built binaries to reproduce the failure described in the bug. Use
+a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
+(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
+
+Bigger Pieces of Work
+---------------------
+In case you are interested in taking on a bigger piece of work, a list of
+interesting projects is maintained at the `LLVM's Open Projects page`_. In case
+you are interested in working on any of these projects, please send a mail to
+the `LLVM Developer's mailing list`_, so that we know the project is being
+worked on.
+
+
+How to Submit a Patch
+=====================
+Once you have a patch ready, it is time to submit it. The patch should:
+
+* include a small unit test
+* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
+* not contain any unrelated changes
+* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
+
+To get a patch accepted, it has to be reviewed by the LLVM community. This can
+be done using `LLVM's Phabricator`_ or the llvm-commits mailing list.
+Please  follow :ref:`Phabricator#requesting-a-review-via-the-web-interface <phabricator-request-review-web>`
+to request a review using Phabricator.
+
+To make sure the right people see your patch, please select suitable reviewers
+and add them to your patch when requesting a review. Suitable reviewers are the
+code owner (see CODE_OWNERS.txt) and other people doing work in the area your
+patch touches. If you are using Phabricator, add them to the `Reviewers` field
+when creating a review and if you are using `llvm-commits`, add them to the CC of
+your email.
+
+A reviewer may request changes or ask questions during the review. If you are
+uncertain on how to provide test cases, documentation, etc., feel free to ask
+for guidance during the review. Please address the feedback and re-post an
+updated version of your patch. This cycle continues until all requests and comments
+have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
+Once that is done the change can be committed. If you do not have commit
+access, please let people know during the review and someone should commit it
+on your behalf.
+
+If you have received no comments on your patch for a week, you can request a
+review by 'ping'ing a patch by responding to the email thread containing the
+patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate
+is once a week. Please remember that you are asking for valuable time from other
+professional developers.
+
+
+Helpful Information About LLVM
+==============================
+:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
+well as various user guides. The pages listed below should provide a good overview
+of LLVM's high-level design, as well as its internals:
+
+`Intro to LLVM`__
+  Book chapter providing a compiler hacker's introduction to LLVM.
+
+  .. __: http://www.aosabook.org/en/llvm.html
+
+:doc:`GettingStarted`
+   Discusses how to get up and running quickly with the LLVM infrastructure.
+   Everything from unpacking and compilation of the distribution to execution
+   of some tools.
+
+:doc:`LangRef`
+  Defines the LLVM intermediate representation.
+
+:doc:`ProgrammersManual`
+  Introduction to the general layout of the LLVM sourcebase, important classes
+  and APIs, and some tips & tricks.
+
+:ref:`index-subsystem-docs`
+  A collection of pages documenting various subsystems of LLVM.
+
+
+
+.. _Developer's List (llvm-dev): http://lists.llvm.org/mailman/listinfo/llvm-dev
+.. _irc.oftc.net: irc://irc.oftc.net/llvm
+.. _beginner keyword: https://bugs.llvm.org/buglist.cgi?bug_status=NEW&bug_status=REOPENED&keywords=beginner%2C%20&keywords_type=allwords&list_id=130748&query_format=advanced&resolution=---
+.. _bug tracker: https://bugs.llvm.org
+.. _clang-format-diff.py: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/clang-format-diff.py
+.. _git-clang-format: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/git-clang-format
+.. _LLVM's Phabricator: https://reviews.llvm.org/
+.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
+.. _LLVM Developer's mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev

llvm/trunk/docs/Phabricator.rst

 
 Phabricator has a tool called *Arcanist* to upload patches from
 the command line. To get you set up, follow the
 `Arcanist Quick Start`_ instructions.
 
 You can learn more about how to use arc to interact with
 Phabricator in the `Arcanist User Guide`_.
 
+.. _phabricator-request-review-web:
+
 Requesting a review via the web interface
 -----------------------------------------
 
 The tool to create and review patches in Phabricator is called
 *Differential*.
 
 Note that you can upload patches created through various diff tools,
 including git and svn. To make reviews easier, please always include

llvm/trunk/docs/index.rst

:doc:`FuzzingLLVM`
   Information on writing and using Fuzzers to find bugs in LLVM.
 
 :doc:`ScudoHardenedAllocator`
   A library that implements a security-hardened `malloc()`.
 
 :doc:`OptBisect`
   A command line option for debugging optimization-induced failures.
 
+.. _index-subsystem-docs:
+
 Subsystem Documentation
 =======================
 
 For API clients and LLVM developers.
 
 .. toctree::
    :hidden:
 

 Development Process Documentation
 =================================
 
 Information about LLVM's development process.
 
 .. toctree::
    :hidden:
 
+   Contributing
    DeveloperPolicy
    Projects
    LLVMBuild
    HowToReleaseLLVM
    Packaging
    ReleaseProcess
    Phabricator
 
+:doc:`Contributing`
+   An overview on how to contribute to LLVM.
+
 :doc:`DeveloperPolicy`
    The LLVM project's policy towards developers and their contributions.
 
 :doc:`Projects`
   How-to guide and templates for new projects that *use* the LLVM
   infrastructure.  The templates (directory organization, Makefiles, and test
   tree) allow the project code to be located outside (or inside) the ``llvm/``
   tree, while using LLVM header files and libraries.