Add initial contributing and code style guides (#131)

These are intended to deal with much of the low-hanging fruit; plenty of
room for improvement exists.

2 files changed, 110 insertions, 0 deletions

diff --git a/CODE_STYLE.md b/CODE_STYLE.md
new file mode 100644
index 0000000..37ee977
--- /dev/null
+++ b/CODE_STYLE.md
@@ -0,0 +1,88 @@
+Code Style
+==========
+
+This document is an incomplete description of the predominant style used in the
+RISC-V Sail model.
+Where something is not specified, please look for existing code similar to what
+is being added and copy the predominant style.
+
+For C and OCaml, the formatting rules should be followed where applicable.
+For other languages, follow the standard style for that language if it exists;
+for example, Python should follow the standard PEP-8 style.
+
+Formatting
+----------
+
+* Block-level indentation uses two spaces
+
+* There should be no trailing spaces on any lines
+
+* All files should end with a newline character
+
+* Unix-style line endings should be used
+
+* Files should be free from leading, trailing and double blank lines
+
+* There should be one space either side of operators such as `=` and `+`
+
+* There should be no spaces before and one space after `,`
+
+* There should be one space after control flow keywords such as `if`, `foreach`
+  and `match`
+
+* There should be no spaces between a function name and its arguments, for both
+  definitions (valspecs, function definitions and function clauses) and calls,
+  nor should there be any spaces immediately within the parentheses
+
+* There should be no spaces between a vector and the opening square bracket for
+  indexing or slicing, nor should there be any spaces immediately within the
+  square brackets
+
+* For large blocks of code with repetitive structure where it improves
+  readability, additional whitespace may be inserted to align corresponding
+  elements horizontally with each other, within reason
+
+* Avoid unnecessary parentheses and curly braces unless doing so seriously
+  hurts readability
+
+* When modifying existing code that does not conform to this style, prefer
+  matching the existing style
+
+Implementation
+--------------
+
+* Since this is the official model intended to be included as part of the
+  RISC-V specifications, readability is paramount, including to those not
+  already familiar with the details of that field of Computer Science (e.g.
+  floating-point or cryptography)
+
+* All instructions should be built as part of both the RV32 and RV64 models so
+  as to provide a path to supporting mutable MXL/SXL/UXL; if necessary,
+  constructs like `assert(sizeof(xlen) == 32)` at the start of the body can be
+  used to suppress any type errors that arise as a result
+
+* Avoid the use of hard-coded constants like 32 even if the instruction is
+  RV32-specific, instead favouring `sizeof(xlen)` or a computed constant to
+  more clearly express the underlying intent
+
+* Local variables should be made immutable whenever possible, but short
+  imperative loops with a small amount of local mutable state are preferred
+  over less-readable functional-style recursive equivalents
+
+* Choose carefully between integer and bitvector types, and avoid multiple
+  round-trips between the two; for example, if counting something, use a `nat`
+  and convert it to an appropriately-sized bitvector at the point it is stored
+  in a register, but keep register source values as bitvectors until they are
+  needed to be interpreted as integers (see the implementation of `MUL` as an
+  example)
+
+* Prefer `bool` over `bits(1)` when a value logically represents true or false
+  rather than being a single bit with a numeric meaning, and vice-versa
+
+* No new compile-time warnings from the Sail compiler should be introduced
+  (this does not include C or OCaml warnings for the code generated by the Sail
+  compiler)
+
+* Do not use the `ext*` types and hooks for standard extensions unless
+  providing a stub implementation; these are reserved for use by out-of-tree
+  extensions that provide their own non-stub implementations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c960ae6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,22 @@
+Contributing
+============
+
+When contributing, please follow the [code style](CODE_STYLE.md) in use.
+
+Pull requests should be a single set of related changes with a clean commit
+history free from merge commits.
+Each commit should be self-contained, provide a meaningful short summary in
+the subject and, if not clear from the subject alone, provide more detail in
+the commit description.
+
+Every commit should build with no new regressions introduced, and large commits
+should be broken up into multiple distinct commits that take incremental steps
+towards the final goal.
+For example, large ratification packages should have one commit per individual
+extension, with possibly an additional initial commit to add necessary
+infrastructure like new types needed for all the subsequent commits.
+
+Unnecessary code churn should be avoided unless as part of a pull request aimed
+at improving code quality, such as fixing repeated code style violations or
+renaming a function whose meaning is unclear.
+Such pull requests should not also introduce significant new functionality.