Contributions are always welcome. We accept bug fixes, proposals and new ideas, or simply editorial improvements.
By submitting a pull request you are implicitly adhering to the contribution agreement.
You can report a bug by creating an issue. You can also fix it yourself with a pull request.
We are open to any proposal that will improve either the content or the presentation of the ABI.
Arm recommends that you present them in a pull request, along with the following details:
- A rationale in support of the changes.
- A design document to keep track of the reasoning that made the proposal reach its current state.
Please note that this extra information is not a requirement for submitting new content. Contributors are trusted to use their judgment to decide whether or not the proposal needs this information. Arm recommends that you add this information so that it is easier for new ideas to be discussed and possibly accepted, especially for changes of great impact.
Instead of a pull request, you can also create an issue, in which you describe your proposed change. However beware that opening an issue will have less chance to make it into the ABI, as someone will need to do the leg-work to make actual changes.
If you want to make ABI changes that for some reason can't be discussed in public, you can send an email to [email protected].
While the majority of new proposals can be added to existing documents. Proposals that extend the ABI, but are not yet stable are placed in an extension document. An example of an extension document is the PAuth Extension to ELF for Arm 64-bit Architecture. Extension documents have the following requirements:
- The document status must be Alpha.
- The document has an owner recorded in the table below. The owner need not be from Arm.
- The document must not clash with other ABI extension documents, or both extensions must be marked as being incompatible.
The Arm approval process for accepting the extension is as follows:
- At least one person within Arm has reviewed and accepted the pull request.
- There is a consensus within Arm that the extension can be added to the ABI.
Extension documents can move into the main ABI when the following conditions hold:
- The information in the document is stable.
- There is an implementation of the extension.
- The boundaries of when the extension applies are clear.
An extension document that moves into the main ABI will add the necessary information to the main documents. In addition any design and rationale in the extension document will be moved to a new document in the design-documents folder.
When the extension has either moved into the main ABI or has been withdrawn it will be moved to an archive folder.
To check the outcome of your changes, run the tools/rst2pdf/generate-pdfs.sh
script. To install the (python) prerequisites for the script, run the
tools/rst2pdf/install.sh script.
You can also check the rst syntax of the documents you changed with the
tools/common/check-rst-syntax.sh script.
These scripts have only been tested on Linux.
Whenever you create a pull request, these syntax checking and PDF generating
scripts will be executed by Github Actions.
You can download the PDFs in the Checks tab of any pull request (in the
Checks tab click on the CI summary page above the highlighted Build
sub-tab).
The CI bot will also check the rst syntax of the documents. You can check the
output in the Checks tab in the check .rst document syntax build log
dropdown.
-
Make pull request
First you will have to make the actual pull request, which contains the proposed changes. If you are unfamiliar with Github pull requests, you can read up on them here.
New development (bug-fixes, proposals, extensions, and so on) is committed on the
maindevelopment branch. Therefore, please submit your PR against the branchmain.If your change is substansive, please add a short entry to the
Change historysection of the changed documents that makes clear what you changed.Design documents are placed in the
<root>/design-documentsdirectory. -
Review of pull request
Your pull request needs to be reviewed. Anyone can review, but at least one of the reviewers needs to be someone from Arm. Good candidate to review your change would be the various so-called document owners who look after the quality of the individual documents. Not every document has an owner, but the most used and important ones do. See the table below:
-
Merging the change
Once the change has been reviewed properly it can be merged, which can only be done by a member of the abi-aa admin group. If your change hasn't been merged for more than a week after it has been accepted, leave a comment on the pull request. Merging of changes should use the rebase and merge strategy. Other merge options should be disabled.
- We favor simple language over complicated language.
- If in doubt, we'll consult the Chicago Manual of Style as it is a de facto standard.
- We should use Sentence case rather than Title Case for section headings. So capitalization only of the first word.
Contributions to this project are licensed under an inbound=outbound model such that any such contributions are licensed by the contributor under the same terms as those in the LICENSE file.
We do not require copyright assignment. The original contributor will retain the copyright.
When adding content for the first time to an existing ABI specification or when creating a new one, you should add the copyright owner (presumably either yourself or your organization) to the list of copyright owners in the copyright notices section at the top of the document. Add a copyright notice in the same style as the other copyright notices already present.