Document coding standards and conventions

CONTRIBUTING.md

@@ -0,0 +1,111 @@
+Guide to Contributing
+=====================
+
+Contents:
+
+* Packages
+* Files
+* Facades
+* Non-Facades
+* Partially-Supported DOM API
+* Binary Compatibility
+* Submitting a PR
+
+
+Packages
+========
+
+In v1.x, there used to be sub-packages grouping some parts of the DOM API by major feature.
+In v2.x, we've decided to put everything in `org.scalajs.dom` and get rid of sub-packages.
+
+The reason for this change is that the real DOM API isn't namespaced in anyway, and the decision
+whether to group in a package or not, was subjective and inconsistent.
+
+
+Files
+=====
+
+* Use `package.scala` for a package object and nothing else.
+  Also don't include traits/classes/objects.
+
+* Match the filename to the trait/class/object in it; don't add multiple top-level types.
+  This is effectively Java-style.
+
+
+Facades
+=======
+
+If a feature has many types that don't share a common unambiguous prefix (like `crypto`),
+  * firstly, please raise an issue to discuss so that you don't do work only to be asked to undo it
+    during PR review
+  * create a feature package
+  * put all of its types in its package
+
+If a feature has only a few types that don't share a common unambiguous prefix (like `DOMParser`),
+  * create a facade for the main feature
+  * create a companion object for the facade
+  * put all of its types in the companion object
+
+If a feature has types that all share a common unambiguous prefix (like `Gamepad*`),
+  * put it all in `dom`
+
+
+Non-Facades
+===========
+
+* Implicit conversions should go in companion objects so that they are always in scope without the
+  need for imports. There's no need to group by feature, the types already specify the feature.
+
+* Add Scala-only utilities that pertain to a specific facade, in the facades companion object
+  Eg: helper constructors, legal facade values.
+
+* We currently don't see the need for Scala-only utilities that don't pertain to a specific facade,
+  or shouldn't be universally available (subjective judgement here).
+  If you believe you've got a compelling use case please raise an issue first to discuss.
+
+
+Partially-Supported DOM API
+===========================
+
+TODO: Pending discussion in #514
+
+
+Binary Compatibility
+====================
+
+Binary compatibility for Scala.js facades is different than standard Scala.
+The following are changes that are indeed incompatible in both formats:
+
+Don't:
+  * Remove a trait / class / object
+  * Change a class into a trait or vice versa
+
+Here is a non-exhaustive list of changes that would be binary incompatible for Scala classes, but
+are compatible for JS facade types:
+
+You can:
+  * Remove a member
+  * Change the type or signature of a member
+  * Add a field in a trait
+  * Add an abstract member in a trait
+
+
+Submitting a PR
+===============
+
+Once you're done making your changes...
+
+1. Run `sbt prePR`
+
+2. Run `git diff api-reports` and ensure that you aren't breaking backwards-binary-compatibility
+   (see above). The api reports are auto-generated by `prePR` and provide a concise summary of the
+   entire API. Make sure to look at the top of the file for a description of format.
+
+   Note: We might automate binary-compatibility checking in the future (See #503) but for now,
+   it's just a helpful tool for reviewing PRs.
+
+3. Check in and commit the changes to `api-reports`
+
+4. Submit your PR
+
+5. Know that your contribution is appreciated, thank you!