Merge the CONTRIBUTING.md files

CONTRIBUTING.md

@@ -1,13 +1,12 @@
-# Contributing to Wasmtime
+# Contributing to Wasmtime and/or Cranelift
 
-Wasmtime is a [Bytecode Alliance] project, and follows the Bytecode Alliance's [Code of Conduct] and [Organizational Code of Conduct].
+Wasmtime and Cranelift are [Bytecode Alliance] projects. They follow the
+Bytecode Alliance's [Code of Conduct] and [Organizational Code of Conduct].
 
-Wasmtime follows the same development style as Cranelift, so check out
-[Cranelift's CONTRIBUTING.md]. Of course, for Wasmtime-specific issues, please
-use the [Wasmtime issue tracker].
+For more information about contributing to these projects you can consult the
+[online documentation] which should cover all sorts of topics.
 
 [Bytecode Alliance]: https://bytecodealliance.org/
 [Code of Conduct]: CODE_OF_CONDUCT.md
 [Organizational Code of Conduct]: ORG_CODE_OF_CONDUCT.md
-[Cranelift's CONTRIBUTING.md]: https://github.com/bytecodealliance/cranelift/blob/master/CONTRIBUTING.md
-[Wasmtime issue tracker]: https://github.com/bytecodealliance/wasmtime/issues/new
+[online documentation]: https://bytecodealliance.github.io/wasmtime/contributing.html

docs/SUMMARY.md

@@ -34,6 +34,8 @@
   - [Testing](./contributing-testing.md)
   - [Fuzzing](./contributing-fuzzing.md)
   - [CI](./contributing-ci.md)
+  - [Coding guidelines](./contributing-coding-guidelines.md)
+  - [Development process](./contributing-development-process.md)
   - [Release Process](./contributing-release-process.md)
   - [Governance](./contributing-governance.md)
   - [Code of Conduct](./contributing-coc.md)

docs/contributing-coding-guidelines.md

@@ -0,0 +1,33 @@
+# Coding guidelines
+
+For the most part, Wasmtime and Cranelift follow common Rust conventions and
+[pull request] (PR) workflows, though we do have a few additional things to
+be aware of.
+
+[pull request]: https://help.github.com/articles/about-pull-requests/
+
+### rustfmt
+
+All PRs must be formatted according to rustfmt, and this is checked in the
+continuous integration tests. You can format code locally with:
+
+```sh
+$ cargo fmt
+```
+
+at the root of the repository. You can find [more information about rustfmt
+online](https://github.com/rust-lang/rustfmt) too, such as how to configure
+your editor.
+
+### Rustc version support
+
+Wasmtime supports the current stable version of Rust.
+
+Cranelift supports stable Rust, and follows the [Rust Update Policy for
+Firefox].
+
+Some of the developer scripts depend on nightly Rust, for example to run
+clippy and other tools, however we avoid depending on these for the main
+build.
+
+[Rust Update Policy for Firefox]: https://wiki.mozilla.org/Rust_Update_Policy_for_Firefox#Schedule

docs/contributing-development-process.md

@@ -0,0 +1,66 @@
+# Development Process
+
+We use [issues] for asking questions ([open one here][newissue]!) and tracking
+bugs and unimplemented features, and [pull requests] (PRs) for tracking and
+reviewing code submissions.
+
+### Before submitting a PR
+
+Consider opening an issue to talk about it. PRs without corresponding issues
+are appropriate for fairly narrow technical matters, not for fixes to
+user-facing bugs or for feature implementations, especially when those features
+might have multiple implementation strategies that usefully could be discussed.
+
+Our issue templates might help you through the process.
+
+### When submitting PRs
+
+ - Please fill in the pull request template as appropriate. It is usually
+   helpful, it speeds up the review process and helps understanding the changes
+   brought by the PR.
+
+ - Write clear commit messages that start with a one-line summary of the
+   change (and if it's difficult to summarize in one line, consider
+   splitting the change into multiple PRs), optionally followed by
+   additional context. Good things to mention include which areas of the
+   code are affected, which features are affected, and anything that
+   reviewers might want to pay special attention to.
+
+ - If there is code which needs explanation, prefer to put the explanation in
+   a comment in the code, or in documentation, rather than in the commit
+   message.
+
+ - For pull requests that fix existing issues, use [issue keywords]. Note that
+   not all pull requests need to have accompanying issues.
+
+ - Assign the review to somebody from the [Core Team], either using suggestions
+   in the list proposed by Github, or somebody else if you have a specific
+   person in mind.
+
+ - When updating your pull request, please make sure to re-request review if
+   the request has been cancelled.
+
+### Focused commits or squashing
+
+We generally squash sequences of incremental-development commits together into
+logical commits (though keeping logical commits focused). Developers may do
+this themselves before submitting a PR or during the PR process, or Core Team
+members may do it when merging a PR. Ideally, the continuous-integration tests
+should pass at each logical commit.
+
+### Review and merge
+
+Anyone may submit a pull request, and anyone may comment on or review others'
+pull requests. However, one review from somebody in the [Core Team] is required
+before the Core Team merges it.
+
+Even Core Team members should create PRs for every change, including minor work
+items (version bump, removing warnings, etc.): this is helpful to keep track of
+what has happened on the repository. Very minor changes may be merged without a
+review, although it is always preferred to have one.
+
+[issues]: https://guides.github.com/features/issues/
+[pull requests]: https://help.github.com/articles/about-pull-requests/
+[issue keywords]: https://help.github.com/articles/closing-issues-using-keywords/
+[Core Team]: https://github.com/orgs/bytecodealliance/people/
+[newissue]: https://github.com/bytecodealliance/wasmtime/issues/new

docs/contributing.md

@@ -1,17 +1,31 @@
 # Contributing
 
-We're excited to work on Wasmtime together with you! This guide should help you
-get up and running with Wasmtime development. But first, make sure you've read
-the [Code of Conduct](./contributing-coc.html)!
+We're excited to work on Wasmtime and/or Cranelift together with you! This guide
+should help you get up and running with Wasmtime and Cranelift development. But
+first, make sure you've read the [Code of Conduct](./contributing-coc.html)!
+
+Wasmtime and Cranelift are very ambitious projects with many goals, and while
+we're confident we can achieve some of them, we see many opportunities for
+people to get involved and help us achieve even more.
 
 ## Join Our Chat
 
-We chat about Wasmtime development on Zulip — [join
-us!](https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime)
+We chat about Wasmtime and Cranelift development on Zulip — [join
+us!](https://bytecodealliance.zulipchat.com/). You can also join specific
+streams:
+
+* [#wasmtime](https://bytecodealliance.zulipchat.com/#narrow/stream/217126-wasmtime)
+* [#cranelift](https://bytecodealliance.zulipchat.com/#narrow/stream/217117-cranelift)
+
+If you're having trouble building Wasmtime or Cranelift, aren't sure why a test
+is failing, or have any other questions, feel free to ask on Zulip. Not
+everything we hope to do with these projects is reflected in the code or
+documentation yet, so if you see things that seem missing or that don't make
+sense, or even that just don't work the way you expect them to, we're also
+interested to hear about that!
 
-If you're having trouble building Wasmtime, aren't sure why a test is failing,
-or have any other questions, feel free to ask here. You can also [open an
-issue](https://github.com/bytecodealliance/wasmtime/issues/new)!
+As always, you're more than welcome to [open an
+issue](https://github.com/bytecodealliance/wasmtime/issues/new) too!
 
 ## Finding Something to Hack On
 
@@ -29,3 +43,28 @@ If you're looking for something to do, these are great places to start:
 
 If you're unsure if an issue is a good fit for you or not, feel free to ask in a
 comment on the issue, or in chat.
+
+### Mentoring
+
+We're happy to mentor people, whether you're learning Rust, learning about
+compiler backends, learning about machine code, learning about wasm, learning
+about how Cranelift does things, or all together at once.
+
+We categorize issues in the issue tracker using a tag scheme inspired by
+[Rust's issue tags]. For example, the [E-easy] marks good beginner issues,
+and [E-rust] marks issues which likely require some familiarity with Rust,
+though not necessarily Cranelift-specific or even compiler-specific
+experience. [E-compiler-easy] marks issues good for beginners who have
+some familiarity with compilers, or are interested in gaining some :-).
+
+See also the [full list of labels].
+
+Also, we encourage people to just look around and find things they're
+interested in. This a good time to get involved, as there aren't a lot of
+things set in stone yet.
+
+[Rust's issue tags]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
+[E-easy]: https://github.com/bytecodealliance/cranelift/labels/E-easy
+[E-rust]: https://github.com/bytecodealliance/cranelift/labels/E-rust
+[E-compiler-easy]: https://github.com/bytecodealliance/cranelift/labels/E-compiler-easy
+[full list of labels]: https://github.com/bytecodealliance/cranelift/labels