Skip to content

Commit cd080dc

Browse files
committed
Add intro, api report ex, other fixes
1 parent eb5ffe5 commit cd080dc

File tree

1 file changed

+48
-26
lines changed

1 file changed

+48
-26
lines changed

CONTRIBUTING.md

+48-26
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,24 @@
11
Guide to Contributing
22
=====================
33

4+
Thanks for contributing to scala-js-dom!
5+
We primarily accept PRs for:
6+
* Adding facades for APIs documented in the spec
7+
* Enhancing/fixing existing facades to match the spec
8+
* Adding non-facade Scala utilities to complement specific facades
9+
* Any other bug fixes etc.
10+
11+
If you would like to make PR that doesn't fall under those categories,
12+
please raise an issue first for discussion so we can give you the go-ahead!
13+
14+
We look forward to your PRs!
15+
416
Contents:
517

618
* Packages
719
* Files
820
* Facades
921
* Non-Facades
10-
* Partially-Supported DOM API
1122
* Binary Compatibility
1223
* Submitting a PR
1324

@@ -35,19 +46,15 @@ Files
3546
Facades
3647
=======
3748

38-
If a feature has many types that don't share a common unambiguous prefix (like `crypto`),
39-
* firstly, please raise an issue to discuss so that you don't do work only to be asked to undo it
40-
during PR review
41-
* create a feature package
42-
* put all of its types in its package
43-
44-
If a feature has only a few types that don't share a common unambiguous prefix (like `DOMParser`),
45-
* create a facade for the main feature
46-
* create a companion object for the facade
47-
* put all of its types in the companion object
49+
We accept facades for any non-deprecated API documented in the spec, including experimental APIs or APIs not supported on all browsers.
50+
* MDN: https://developer.mozilla.org/en-US/docs/Web/API
51+
* WHATWG: https://spec.whatwg.org/
4852

49-
If a feature has types that all share a common unambiguous prefix (like `Gamepad*`),
50-
* put it all in `dom`
53+
Please:
54+
* Use `def` for read-only properties unless there is a compelling reason it should be a `val`
55+
(i.e., the spec definitively states it is constant)
56+
* Use `Double` for integer-values that can fall outside the range of `Int`
57+
* Add scaladocs via copy-paste from MDN
5158

5259

5360
Non-Facades
@@ -63,13 +70,6 @@ Non-Facades
6370
or shouldn't be universally available (subjective judgement here).
6471
If you believe you've got a compelling use case please raise an issue first to discuss.
6572

66-
67-
Partially-Supported DOM API
68-
===========================
69-
70-
TODO: Pending discussion in #514
71-
72-
7373
Binary Compatibility
7474
====================
7575

@@ -80,7 +80,7 @@ Don't:
8080
* Remove a trait / class / object
8181
* Change a class into a trait or vice versa
8282

83-
Here is a non-exhaustive list of changes that would be binary incompatible for Scala classes, but
83+
Here is a non-exhaustive list of changes that would be binary-incompatible for Scala classes, but
8484
are compatible for JS facade types:
8585

8686
You can:
@@ -89,6 +89,32 @@ You can:
8989
* Add a field in a trait
9090
* Add an abstract member in a trait
9191

92+
To help us enforce binary compatibility, we use API reports.
93+
They are auto-generated by running `prePR` in sbt and provide a concise summary of the entire API.
94+
Note: We might automate binary compatibility checking in the future (see #503) but for now,
95+
it's just a helpful tool for reviewing PRs.
96+
97+
Here is an example of a binary _compatible_ change in #491 as it appears in the API report diff.
98+
Note that `[JC]` stands for **J**avascript **C**lass, indicating that `HTMLAudioElement` is a facade type and thus this is a compatible change.
99+
```diff
100+
-raw/HTMLAudioElement[JC] def play(): Unit
101+
+raw/HTMLAudioElement[JC] def play(): js.UndefOr[js.Promise[Unit]]
102+
```
103+
104+
Here is an example of a binary _incompatible_ change in #458 as it appears in the API report diff.
105+
Even though the `Fetch` object is a facade (a **J**avascript **O**bject), moving it out of the `experimental` package is not binary compatible.
106+
(In this particular case, the change was accepted along with many binary-breaking changes going into 2.0.0.)
107+
```diff
108+
-experimental/Fetch[JO] def fetch(info: RequestInfo, init: RequestInit = null): js.Promise[Response]
109+
+Fetch[JO] def fetch(info: RequestInfo, init: RequestInit = null): js.Promise[Response]
110+
```
111+
112+
Anything annotated `[SC]`, `[ST]`, or `[SO]` in an API report is an ordinary Scala class/trait/object,
113+
for which standard binary compatibility rules apply.
114+
115+
If the above doesn't make sense to you, don't worry!
116+
The majority of useful changes to scala-js-dom are indeed binary compatible.
117+
92118

93119
Submitting a PR
94120
===============
@@ -98,11 +124,7 @@ Once you're done making your changes...
98124
1. Run `sbt prePR`
99125

100126
2. Run `git diff api-reports` and ensure that you aren't breaking backwards-binary-compatibility
101-
(see above). The api reports are auto-generated by `prePR` and provide a concise summary of the
102-
entire API. Make sure to look at the top of the file for a description of format.
103-
104-
Note: We might automate binary-compatibility checking in the future (See #503) but for now,
105-
it's just a helpful tool for reviewing PRs.
127+
(see above).
106128

107129
3. Check in and commit the changes to `api-reports`
108130

0 commit comments

Comments
 (0)