diff --git a/devtools/docs/backend/backward-compatibility.md b/devtools/docs/backend/backward-compatibility.md index 264356231e67..ebb61323458a 100644 --- a/devtools/docs/backend/backward-compatibility.md +++ b/devtools/docs/backend/backward-compatibility.md @@ -26,6 +26,17 @@ The harder part of this currently is that there is no automated testing to ensur The easiest way to test this is to check your work against a Firefox for Android device on release channel to ensure existing features in the area you are changing continue to function. That doesn't cover every case, but it's a great start. +Alternatively, you can connect to a Firefox release server. This can be done in multiple steps: + +1. Start Firefox release from the command line, specifying the `--start-debugger-server` with an available port (e.g. `/Applications/Firefox.app/Contents/MacOS/firefox --start-debugger-server 6081`) +2. Navigate to a page where you can check that the part of DevTools which is impacted by the patch still works. +3. Build and run Firefox locally with the patch you want to check +4. In this build, open an `about:debugging` tab +5. On the `Network Location` section, fill in the host with localhost and the debugger server port you started the Firefox release instance with (e.g. `localhost:6081`) and hit Enter (or the `Add` button) +6. A new item will appear in the sidebar, click on its `Connect` button. +7. Accept the `Incoming connection` popup that appears +8. Click on the on sidebar item again. You will now see a list of the tabs and workers running in the Firefox release instance. Click on the `Inspect` button next to them to open a toolbox that is connected to the older server. + ## Feature Detection Starting with Firefox 36 (thanks to [bug 1069673](https://bugzilla.mozilla.org/show_bug.cgi?id=1069673)), you can use actor feature detection to determine which actors exist. @@ -47,10 +58,12 @@ Expose traits on an Actor in order to flag certain features as available or not. Traits need to be forwarded to the client, and stored or used by the corresponding Front. There is no unique way of exposing traits, but there are still a few typical patterns found in the codebase. For Actors using a "form()" method, for which the Front is automatically created by protocol.js, the usual pattern is to add a "traits" property to the form, that contains all the traits for the actor. The Front can then read the traits in its corresponding "form()" method. Example: + - [NodeActor form method](https://searchfox.org/mozilla-central/rev/e75e8e5b980ef18f4596a783fbc8a36621de7d1e/devtools/server/actors/inspector/node.js#209) - [NodeFront form method](https://searchfox.org/mozilla-central/rev/e75e8e5b980ef18f4596a783fbc8a36621de7d1e/devtools/client/fronts/node.js#145) For other Actors, there are two options. First option is to define the trait on the Root actor. Those traits will be available both via TargetMixin::getTrait(), and on DevToolsClient.traits. The second option is to implement a "getTraits()" method on the Actor, which will return the traits for the Actor. Example: + - [CompatibilityActor getTraits method](https://searchfox.org/mozilla-central/rev/e75e8e5b980ef18f4596a783fbc8a36621de7d1e/devtools/shared/specs/compatibility.js#40) - [CompatibilitySpec getTraits definition](https://searchfox.org/mozilla-central/rev/e75e8e5b980ef18f4596a783fbc8a36621de7d1e/devtools/shared/specs/compatibility.js#40-43) - [CompatibilityFront getTraits method](https://searchfox.org/mozilla-central/rev/e75e8e5b980ef18f4596a783fbc8a36621de7d1e/devtools/client/fronts/compatibility.js#41-47) @@ -59,10 +72,19 @@ Ironically, "getTraits" needs to be handled with backwards compatibility. But th Whenever traits are added, make sure to add a relevant backward compatibility comment so that we know when the trait can be removed. -## Removing old backward compatibility code +## Maintaining backward compatibility code -We used to support old Firefox OS servers (back to Gecko 28), we don't anymore. Does this mean we can remove compatibility traits for it? +When introducing backward compatibility code, a comment should be added for extra information. +In order to simplify future code cleanups, the comment should follow the following syntax: +`// @backward-compat { added in XX } Detailed comment`, where `XX` is the Firefox version this code was added in. -Maybe. Keep in mind that we still want to support Firefox for Android back to release channel, so we still want to keep traits in general. That's a much smaller time window than we supported for Firefox OS, so it should allow for some simplification. +Below is a made-up example of what it should look like: -The type of compatibility that could now be removed are things where the protocol semantics changed in some Gecko older than release channel and the trait is not useful for saying "I don't support feature X". +```js +// @backward-compat { added in 85 } For older server which don't have the AwesomeActor, +// we have to do this another way. +if (!toolbox.target.hasActor("awesome")) { +``` + +Backward compatibility code can be safely removed when the revision it was added in reaches the release channel. +So if something landed in Firefox Nightly 85, it can be removed when Firefox 85 is released, i.e. when Firefox Nightly is 87. Search for the corresponding `@backward-compat` entries to retrieve all the code that can be removed.