Add arm-toolchain CONTRIBUTING.md including downstream patch policy

[smithp35]

This is based on the "LLVM Embedded Toolchain for Arm" contributing.md with adaptations for the arm-toolchain.

The largest change is the introduction of the downstream patch policy. Arm wants the arm-toolchain to be as close to the upstream open-source projects as possible, we impose some additional requirements on downstream patches so that we can summarize all the patches and know why they were made.

Replace llvm-project's CONTRIBUTING.md rather than using another location like .github as we expect many developers to read the file from the terminal.

[vhscampos]

I suggest we stick to a consistent formatting of project names. In some places they are emphasized with stars, in others they aren't. For instance in this line, newlib does not have emphasis.

[smithp35]

ACK. I thought I'd caught those. Will fix.

[vhscampos]

Github -> GitHub

[smithp35]

ACK

[vhscampos]

We ought to check that external contributors have permissions to add labels. That is not the case for example in the ABI and the ACLE repositories.

[smithp35]

Looks like our base role is Read and Triage is needed to add labels. I've taken out the requirement to add labels, I'm not sure that was happening in practice anyway.

I've suggested putting [RFC] in the title. I expect one of us with sufficient privilege will need to add the labels.

[vhscampos]

Same remark about permissions to add labels

[smithp35]

ACK. I've suggested [RFC] in the subject instead.

[vhscampos]

"the the"

[smithp35]

ACK

[vhscampos]

Capitalise arm toolchain

[smithp35]

ACK

[vhscampos]

Put the filepath between ticks

[smithp35]

ACK

[smithp35]

Thanks for the review. I'll upload a fixup patch.

[smithp35]

ACK. I thought I'd caught those. Will fix.

[smithp35]

ACK

[smithp35]

Looks like our base role is Read and Triage is needed to add labels. I've taken out the requirement to add labels, I'm not sure that was happening in practice anyway.

I've suggested putting [RFC] in the title. I expect one of us with sufficient privilege will need to add the labels.

[smithp35]

ACK. I've suggested [RFC] in the subject instead.

[smithp35]

ACK

[smithp35]

ACK

[smithp35]

ACK

[voltur01]

Do we need to mention llvm-libc separately as well? It is part of llvm-project so implicitly is there, however we seem to go into much more details in regard to the other two libraries.

Taking into account that we want to use llvm-libc more, we may want to mention is explicitly.

[smithp35]

The distinction I was trying to make was in-tree llvm-project, which includes llvm-libc, and out-of-tree picolibc and newlib. LLVM libc

I've updated the wording to hopefully make it clearer.

[voltur01]

rfc was probably a label previously, so may be clearer as RFC now with the new recommendation.

[smithp35]

ACK

[voltur01]

Should this be arm-toolchain repository? Or maybe more complicated statement like llvm-project files inside arm-toolchin repo?

[smithp35]

I've used the arm-toolchain repository and tweaked the language a bit.

[voltur01]

Same as above: llvm-prooject files inside arm-toolchain repo?

[smithp35]

ACK

[voltur01]

Should we add the placeholder file now as well?
Maybe it should have sections for common and embedded/linux specific features?

[smithp35]

Yes, I was in two minds over whether to do that here or in a follow up patch.

[smithp35]

There's an interesting design decision here. The current directory structure is:

arm-software
|-- ci
|-- embedded
|-----docs
|-- linux

With the docs directory for embedded being part of the installed package.

I think we would want the documentation of downstream features to be available in the installed package for LLVM embedded at least. Not sure about what is supposed to happen in linux.

One way of doing this is to put the downstream feature documentation in embedded/docs/features.md and linux/docs/features.md with duplication for common changes. In theory all changes are common to both, but I suspect that the users for each toolchain will care about different downstream features. For example ATfA won't care about M-profile code-generation changes.

An alternative is to add a new doc directory to arm-software for common docs for both embedded and linux. The tool installation could then copy the features.md file into the installation.

My instinct is that ATfE will have more of the downstream features, and that these won't be that useful to ATfA, so I think each toolchain can have its own features.md file.

[smithp35]

I'll start with a patch for embedded/docs/features.md

[voltur01]

Yes, this is a tricky one. On one hand, most of the LLVM changes will technically impact both, so would be easier to document in one place, but then you are right it is not obvious how to nicely include into the distribution.

I think I prefer to have a shared folder to document the changes in one place, then an extra CMake rule to copy contents into the distribution.

We may have 3 feature files: common to copy to both, embedded and linux for very clearly specific things to be copied to respective distributions.

[smithp35]

I've uploaded a new patch with the common docs folder and some skeleton feature pages.

I've also removed the embedded/contributing.md as this replaces it.

[voltur01]

Thank you, LGTM!