1
1
Guide to Contributing
2
2
=====================
3
3
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
+
4
16
Contents:
5
17
6
18
* Packages
7
19
* Files
8
20
* Facades
9
21
* Non-Facades
10
- * Partially-Supported DOM API
11
22
* Binary Compatibility
12
23
* Submitting a PR
13
24
@@ -35,19 +46,15 @@ Files
35
46
Facades
36
47
=======
37
48
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/
48
52
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
51
58
52
59
53
60
Non-Facades
@@ -63,13 +70,6 @@ Non-Facades
63
70
or shouldn't be universally available (subjective judgement here).
64
71
If you believe you've got a compelling use case please raise an issue first to discuss.
65
72
66
-
67
- Partially-Supported DOM API
68
- ===========================
69
-
70
- TODO: Pending discussion in #514
71
-
72
-
73
73
Binary Compatibility
74
74
====================
75
75
80
80
* Remove a trait / class / object
81
81
* Change a class into a trait or vice versa
82
82
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
84
84
are compatible for JS facade types:
85
85
86
86
You can:
@@ -89,6 +89,32 @@ You can:
89
89
* Add a field in a trait
90
90
* Add an abstract member in a trait
91
91
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
+
92
118
93
119
Submitting a PR
94
120
===============
@@ -98,11 +124,7 @@ Once you're done making your changes...
98
124
1 . Run ` sbt prePR `
99
125
100
126
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).
106
128
107
129
3 . Check in and commit the changes to ` api-reports `
108
130
0 commit comments