Add arm-toolchain CONTRIBUTING.md including downstream patch policy

CONTRIBUTING.md

@@ -1,17 +1,202 @@
-# Contributing to LLVM
+# Contributing to the Arm Toolchain
 
-Thank you for your interest in contributing to LLVM! There are many ways to
-contribute, and we appreciate all contributions.
+The Arm Toolchain repository is a fork of the *llvm-project*, with an
+additional arm-software directory containing build scripts to produce
+Arm Toolchain for Embedded and Arm Toolchain for Linux, as well as
+documentation and samples.
 
-To get started with contributing, please take a look at the
-[Contributing to LLVM](https://llvm.org/docs/Contributing.html) guide. It
-describes how to get involved, raise issues and submit patches.
+Additionally, Arm Toolchain for Embedded can integrate external
+projects such as the *picolibc* C-library or the *newlib* C-library
+via an overlay package.
 
-## Getting in touch
+Contributions are welcome that improve the project in areas including
+but not limited to:
+* Integration of upstream components.
+* Packaging.
+* Testing of the above.
+* Documentation.
 
-Join the [LLVM Discourse forums](https://discourse.llvm.org/), [Discord
-chat](https://discord.gg/xS7Z362), or #llvm IRC channel on
-[OFTC](https://oftc.net/).
+The Arm Toolchain repository is synchronized with the upstream
+*llvm-project* including the main and release branches. Arm Toolchain
+for Embedded aims to stay close to the head of the *picolibc* main
+branch. The *newlib* overlay package aims to track the most recent
+*newlib* release.
 
-The LLVM project has adopted a [code of conduct](https://llvm.org/docs/CodeOfConduct.html) for
-participants to all modes of communication within the project.
+All changes that can be made in the upstream project, must be made in
+the upstream project. Please see the [Downstream Patch Policy](#downstream-patch-policy)
+below for what Arm considers a downstream patch along with the
+additional requirements for such a patch.
+
+For guidance on how to contribute to the upstream projects see:
+* *llvm-project* [Contributing to LLVM](https://llvm.org/docs/Contributing.html).
+* *picolibc* GitHub.
+[Pull requests documentation](https://docs.github.com/en/pull-requests)
+
+## Ways to contribute
+
+### Report an issue
+
+Please make sure that the issue is specific to the *arm-toolchain*
+before reporting. If the issue exists in *llvm-project* or *picolibc*
+then please report the issue in the upstream project.
+
+Please create a GitHub issue in the *arm-toolchain* project
+[Issues](https://github.com/arm/arm-toolchain/issues)
+list.
+
+### Submit a fix
+
+For a small change, please create a Pull Request as described in
+_How to submit a change_ section below.
+
+### Suggest a feature or bigger change
+
+For a bigger change, please create an issue in the
+*arm-toolchain* project
+[Issues](https://github.com/arm/arm-toolchain/issues)
+list and put [RFC] in the subject line (Request for Comments) to initiate the discussion
+first, before submitting a PR for the change.
+
+There is no formal template for an `RFC`, however it would be good to
+explain the purpose of the change and the key design options, proposed
+decisions.
+
+## How to submit a change
+
+Contributions are accepted under the
+[Apache License 2.0 with LLVM Exceptions](https://github.com/arm/arm-toolchain/blob/arm-software/LICENSE.TXT).
+Only submit contributions where you have authored all of the code.
+
+### Pull request
+
+This project follows the conventional
+[GitHub pull request](https://docs.github.com/en/pull-requests) flow.
+
+### Testing
+
+Please ensure your change doesn't break tests. (The project doesn't yet have
+GitHub actions to do this). Except for documentation changes, please check that
+this passes:
+
+```
+ninja check-llvm-toolchain
+```
+
+### Coding style
+
+Use the following commands to check the scripts before submitting a pull
+request:
+
+```
+$ ./setup.sh
+$ ./run-precommit-checks.sh
+```
+
+## Downstream Patch Policy
+
+### What is considered a downstream patch?
+
+A patch is considered a downstream patch if:
+
+* It adds, modifies or removes, any file in the *arm-toolchain*
+  repository outside of the *arm-software* directory.
+
+* It is a patch file to be applied to an external project used by a
+  toolchain built from the fork. For example *picolibc* or *newlib*.
+
+All contributions that can be made in an upstream project, must be
+made in the upstream project.
+
+### Suitable categories for downstream patches
+
+#### Toolchain integration
+
+Patches that are specific to integrating components of the Arm
+Toolchain or the projects that it depends on, may be implemented
+downstream if there's insufficient benefit to the upstream
+project. For example upstream may not be willing to accept a patch
+that only affects Arm Toolchain, but they may be willing to accept a
+patch that improves integration with another open-source project in
+the general case.
+
+#### Guarded Optimizations for key benchmarks
+
+Some optimizations that are important for benchmarks that are
+important to Arm are not acceptable upstream. Patches that implement
+these optimizations are permitted when the following conditions hold:
+
+* All attempts at upstreaming the optimization have failed.
+
+* The optimization is required for a benchmark that Arm promotes for
+  its CPUs.
+
+* The changes are guarded behind an opt-in command-line
+  option. Code-generation must not be affected when the command-line
+  option is not used.
+
+#### Changes critical to Arm that are in upstream review
+
+When a feature or bug fix that is both important and urgent for Arm,
+is likely to face a long period of upstream review then it may be
+carried as a downstream patch. Downstream patches in upstream review
+must have experimental status and will be replaced with the upstream
+implementation once that has landed.
+
+#### Backports critical to Arm for a numbered release
+
+When a feature or bug fix in the main branch of upstream
+*llvm-project* has missed the cut off for the upstream numbered
+release, Arm may choose to backport the change to the Arm Toolchain
+numbered release. An attempt must have been made to use the upstream
+backport process first.
+
+## Requirements for a downstream patch
+
+The following requirements for downstream patches are to assist in
+auditing and tracking. All downstream patches must satisfy all the
+requirements below:
+
+* The pull request description or comment must contain a justification
+  of why the patch isn't being made upstream. This should include
+  links to any previous attempts to upstream.
+
+* The commit message for a new downstream patch must include
+  Downstream issue:#<issue number> where #<issue number> is an issue
+  that contains the reason for the downstream patch.
+
+* The source change should be annotated with a comment including the
+  #<issue number>, if there are multiple lines changed a single
+  comment for the block can be used.
+
+* The commit message that removes an existing downstream patch, such
+  as when the upstream equivalent lands, must include Removes
+  downstream issue:#<issue number>.
+
+* New files in the *arm-toolchain* repository must include the LLVM
+  license, with the standard header comment and SPDX identifier.
+
+* New files added to an external project like *picolibc* or *newlib*
+  must follow the licensing and copyright of the external project.
+
+* Any patch that causes the Arm Toolchain to deviate from upstream
+  behavior, such as a new command-line option, must have user
+  documentation. See [Downstream Feature
+  Documentation](downstream-feature-documentation) for the location
+  and required contents.
+
+### Downstream Feature Documentation
+
+There are three files that contain the user facing documentation for downstream features.
+
+* `arm-software/docs/arm-toolchain-features.md` for features common to
+  both Arm Toolchain for Embedded and Arm Toolchain for Linux.
+
+* `arm-software/docs/arm-toolchain-for-embedded-features.md` for
+  features specific to Arm Toolchain for Embedded.
+
+* `arm-software/docs/arm-toolchain-for-linux-features.md` for
+  features specific to Arm Toolchain for Linux.
+
+The documentation for a feature must state if it is
+experimental. Experimental features may change or be removed at any
+point in the future.

arm-software/docs/README.md

@@ -0,0 +1,9 @@
+# Scope of this directory
+
+This directory contains documentation that is common to both Arm
+Toolchain for Embedded and Arm Toolchain for Linux.
+
+Documentation that is specific to a toolchain should be placed in the
+toolchain specific subdirectory. For example documentation for Arm
+Toolchain for Embedded should go into the `arm-software/embedded/docs`
+directory.

arm-software/docs/arm-toolchain-features.md

@@ -0,0 +1,22 @@
+# Additional features available in all Arm Toolchains
+
+Arm Toolchain for Linux and Arm Toolchain for Embedded may have
+additional features not available in a toolchain built from the
+upstream repositories. This file contains documentation for the
+additional features that are available in both Arm Toolchain for Linux
+and Arm Toolchain for Embedded.
+
+Additional features specific to a toolchain can be found in:
+* `arm-toolchain-for-embedded-features.md`
+* `arm-toolchain-for-linux-features.md`
+
+# Experimental Features
+
+The following features are experimental. Experimental features may
+change or be removed at any point in the future.
+
+There are no experimental features implemented.
+
+# Features
+
+There are no additional features implemented.

arm-software/docs/arm-toolchain-for-embedded-features.md

@@ -0,0 +1,20 @@
+# Additional features available in Arm Toolchain for Embedded
+
+Arm Toolchain for Embedded may have additional features not available
+in a toolchain built from the upstream repositories. This file
+contains documentation for the additional features that are available
+in Arm Toolchain for Embedded.
+
+Additional features common to Arm Toolchain for Embedded and Arm
+Toolchain for Linux can be found in `arm-toolchain-features.md`.
+
+# Experimental Features
+
+The following features are experimental. Experimental features may
+change or be removed at any point in the future.
+
+There are no experimental features implemented.
+
+# Features
+
+There are no additional features implemented.

arm-software/docs/arm-toolchain-for-linux-features.md

@@ -0,0 +1,20 @@
+# Additional features available in Arm Toolchain for Linux
+
+Arm Toolchain for Linux may have additional features not available
+in a toolchain built from the upstream repositories. This file
+contains documentation for the additional features that are available
+in Arm Toolchain for Linux.
+
+Additional features common to Arm Toolchain for Linux and Arm
+Toolchain for Embedded can be found in `arm-toolchain-features.md`.
+
+# Experimental Features
+
+The following features are experimental. Experimental features may
+change or be removed at any point in the future.
+
+There are no experimental features implemented.
+
+# Features
+
+There are no additional features implemented.