Add README.contributors

Document contributor requirements.

4 files changed, 155 insertions, 1 deletions

diff --git a/README b/README
index 4654282..0afca55 100644
--- a/README
+++ b/README
@@ -7,7 +7,9 @@ license, at the user’s election, as reflected in the LICENSE file.
 Contributions to this project are accepted, but Contributors have
 to sign an Assignment Agreement, please follow the instructions in
 contributor-agreement.pdf. This is needed so upstreaming code
-to projects that require copyright assignment is possible.
+to projects that require copyright assignment is possible. Further
+contribution requirements are documented in README.contributors of
+the appropriate subdirectory.
 
 Regular quarterly releases are tagged as vYY.MM, the latest
 release is v21.02.
diff --git a/README.contributors b/README.contributors
new file mode 100644
index 0000000..f8fcdde
--- /dev/null
+++ b/README.contributors
@@ -0,0 +1,44 @@
+GENERIC CONTRIBUTION GUIDELINES
+===============================
+
+1. Sub-projects are maintained independently and thus have independent
+   contribution rules. If there exists a README.contributors in the
+   sub-directory to which the contribution is made, it must be followed.
+
+2. Legal:
+   - Contributors who are not employed by Arm must sign an Assignment Agreement.
+     See contributor-agreement.pdf.
+   - All code must be copyright owned by Arm Limited and the appropriate
+     copyright notice and license identifier must be present in every source
+     file.
+
+3. Build:
+   - Build should only depend on GNU make and posix utilities (shell, awk, sed,
+     etc) and on a C toolchain.
+   - Build should pass with the default configuration (see config.mk.dist)
+     and other supported configurations, with both gcc and clang based
+     toolchains. (The build should not depend on a recent toolchain, the use
+     of a new feature should be possible to disable.)
+   - Currently there is no automated configuration, target specific configuration
+     should be done via make variables in config.mk. This is the user interface
+     to the build system, so it should be documented in sufficient detail and
+     kept reasonably stable.
+
+4. Testing:
+   - On aarch64 the tests must pass. If the code may behave differently under
+     some supported configurations (e.g. CFLAGS) those should be tested.
+   - New symbols are expected to have new associated test code and ideally
+     benchmark code too.
+
+4. Commits:
+   - Commit message should be descriptive and should not refer to Arm internal
+     information (such as Jira tickets, or internal discussions). Non-obvious
+     decisions should be recorded or explained in the commit message if they are
+     not explained in source comments.
+   - Ideally tools and scripts used to write the code should be added to the
+     repository or at least mentioned in the commit.
+   - Logically independent changes should not be mixed into the same commit.
+
+5. Style:
+   - Unless otherwise required differently by the sub-project, follow the
+     clang-format tool using the style from the gcc contrib/ directory.
diff --git a/math/README.contributors b/math/README.contributors
new file mode 100644
index 0000000..33e7ba3
--- /dev/null
+++ b/math/README.contributors
@@ -0,0 +1,78 @@
+STYLE REQUIREMENTS
+==================
+
+1. Most code in this sub-directory is expected to be upstreamed into glibc so
+   the GNU Coding Standard and glibc specific conventions should be followed
+   to ease upstreaming.
+
+2. ABI and symbols: the code should be written so it is suitable for inclusion
+   into a libc with minimal changes. This e.g. means that internal symbols
+   should be hidden and in the implementation reserved namespace according to
+   ISO C and POSIX rules. If possible the built shared libraries and static
+   library archives should be usable to override libc symbols at link time (or
+   at runtime via LD_PRELOAD). This requires the symbols to follow the glibc ABI
+   (other than symbol versioning), this cannot be done reliably for static
+   linking so this is a best effort requirement.
+
+3. API: include headers should be suitable for benchmarking and testing code
+   and should not conflict with libc headers.
+
+
+CONTRIBUTION GUIDELINES FOR math SUB-DIRECTORY
+==============================================
+
+1. Math functions have quality and performance requirements.
+
+2. Quality:
+   - Worst-case ULP error should be small in the entire input domain (for most
+     common double precision scalar functions the target is < 0.66 ULP error,
+     and < 1 ULP for single precision, even performance optimized function
+     variant should not have > 5 ULP error if the goal is to be a drop in
+     replacement for a standard math function), this should be tested
+     statistically (or on all inputs if possible in reasonable amount of time).
+     The ulp tool is for this and runulp.sh should be updated for new functions.
+
+   - All standard rounding modes need to be supported but in non-default rounding
+     modes the quality requirement can be relaxed. (Non-nearest rounded
+     computation can be slow and inaccurate but has to be correct for conformance
+     reasons.)
+
+   - Special cases and error handling need to follow ISO C Annex F requirements,
+     POSIX requirements, IEEE 754-2008 requirements and Glibc requiremnts:
+     https://www.gnu.org/software/libc/manual/html_mono/libc.html#Errors-in-Math-Functions
+     this should be tested by direct tests (glibc test system may be used for it).
+
+   - Error handling code should be decoupled from the approximation code as much
+     as possible. (There are helper functions, these take care of errno as well
+     as exception raising.)
+
+   - Vector math code does not need to work in non-nearest rounding mode and error
+     handling side effects need not happen (fenv exceptions and errno), but the
+     result should be correct (within quality requirements, which are lower for
+     vector code than for scalar code).
+
+   - Error bounds of the approximation should be clearly documented.
+
+   - The code should build and pass tests on arm, aarch64 and x86_64 GNU linux
+     systems. (Routines and features can be disabled on specific targets, but
+     the build must complete). On aarch64, both little- and big-endian targets
+     are supported as well as valid combinations of architecture extensions.
+     The configurations that should be tested depend on the contribution.
+
+3. Performance:
+   - Common math code should be benchmarked on modern aarch64 microarchitectures
+     over typical inputs.
+
+   - Performance improvements should be documented (relative numbers can be
+     published; it is enough to use the mathbench microbenchmark tool which should
+     be updated for new functions).
+
+   - Attention should be paid to the compilation flags: for aarch64 fma
+     contraction should be on and math errno turned off so some builtins can be
+     inlined.
+
+   - The code should be reasonably performant on x86_64 too, e.g. some rounding
+     instructions and fma may not be available on x86_64, such builtins turn into
+     libc calls with slow code. Such slowdown is not acceptable, a faster fallback
+     should be present: glibc and bionic use the same code on all targets. (This
+     does not apply to vector math code).
diff --git a/string/README.contributors b/string/README.contributors
new file mode 100644
index 0000000..0b4a51b
--- /dev/null
+++ b/string/README.contributors
@@ -0,0 +1,30 @@
+STYLE REQUIREMENTS
+==================
+
+1. Most code in this sub-directory is expected to be upstreamed into glibc so
+   the GNU Coding Standard and glibc specific conventions should be followed
+   to ease upstreaming.
+
+2. ABI and symbols: the code should be written so it is suitable for inclusion
+   into a libc with minimal changes. This e.g. means that internal symbols
+   should be hidden and in the implementation reserved namespace according to
+   ISO C and POSIX rules. If possible the built shared libraries and static
+   library archives should be usable to override libc symbols at link time (or
+   at runtime via LD_PRELOAD). This requires the symbols to follow the glibc ABI
+   (other than symbol versioning), this cannot be done reliably for static
+   linking so this is a best effort requirement.
+
+3. API: include headers should be suitable for benchmarking and testing code
+   and should not conflict with libc headers.
+
+
+CONTRIBUTION GUIDELINES FOR string SUB-DIRECTORY
+================================================
+1. Code:
+   - The assumptions of the code must be clearly documented.
+
+   - Assembly style should be consistent across different implementations.
+
+
+2. Performance:
+   - Benchmarking is needed on several microarchitectures.