From 419f598caa0c2f211078945efe5415441c0c98b1 Mon Sep 17 00:00:00 2001
From: girst <girst@users.noreply.github.com>
Date: Sun, 20 Sep 2020 14:27:20 +0200
Subject: [PATCH] update installation, known bugs and development documentation

- remove AMO installation method
- change LegacyFox links
- realign development docs with reality
- less jargon on known-bugs.
---
 documentation/CONTRIBUTING-CODE.md     |  8 ---
 documentation/installation.md          | 47 +++-------------
 documentation/known-bugs.md            | 18 +++----
 documentation/questions-and-answers.md |  9 ++--
 documentation/tools.md                 | 75 ++++----------------------
 5 files changed, 29 insertions(+), 128 deletions(-)

diff --git a/documentation/CONTRIBUTING-CODE.md b/documentation/CONTRIBUTING-CODE.md
index 2466d56..99d51d2 100644
--- a/documentation/CONTRIBUTING-CODE.md
+++ b/documentation/CONTRIBUTING-CODE.md
@@ -1,13 +1,5 @@
 # Contributing code
 
-Feel free to contribute stuff that you think might help people, but please
-remember that VimFx is a dead project so there’s a risk that your pull request
-won’t be merged.
-
-See [README.md] for more information.
-
-[README.md]: ../README.md
-
 
 ## Localizations
 
diff --git a/documentation/installation.md b/documentation/installation.md
index cfd9ab2..0e00b2f 100644
--- a/documentation/installation.md
+++ b/documentation/installation.md
@@ -1,50 +1,28 @@
 # Installation
 
-First off, you need Firefox version 68+ (or a compatible fork) and the
-[LegacyFox] shim.
-See [README.md] for more information.
+Independently from the installation method chosen, you need Firefox version 68+
+(or a compatible fork) and the [LegacyFox] shim. Both options are unsigned and
+don't offer automatic updates. You may want to *watch releases* on GitHub.
 
-[README.md]: ../README.md
-[LegacyFox]: https://github.com/girst/LegacyFox
+[LegacyFox]: https://git.gir.st/LegacyFox.git
 
 
-## ⚠️ NO LONGER AVAILABLE ⚠️<br>Option 1: [addons.mozilla.org] \(AMO)
-
-**<https://addons.mozilla.org/firefox/addon/VimFx>**
-
-You used to be able to follow the above link and hit the green “Install” button
-and then be ready to go, but Mozilla has removed all legacy extensions from
-their site.
-
-- [Signed][signed] and reviewed by Mozilla.
-- Hosted on AMO.
-- Automatic updates.
-
-[addons.mozilla.org]: https://addons.mozilla.org/
-
-
-## Option 2: [GitHub releases][releases]
+## Option 1: [GitHub releases][releases]
 
 Go to VimFx’s [releases] page and click the link to “VimFx.xpi” for the version
 you’re interested in (most likely the latest). Firefox should then ask you about
 allowing the installation. (If not, download the .xpi file and [open it in
 Firefox][open-xpi].)
 
-- [Signed][signed] by Mozilla (but not reviewed).
-- Available as a backup alternative, and in case of slow reviews on AMO.
-- No automatic updates.
-
 [releases]: https://github.com/akhodakivskiy/VimFx/releases
 
 
-## Option 3: Build from source
+## Option 2: Build from source
 
 [Build VimFx] and then [open the produced `build/VimFx.xpi` file][open-xpi].
 
-- [Unsigned][signed].
 - Bleeding edge.
 - Allows you to fiddle with the code.
-- No automatic updates.
 
 [Build VimFx]: tools.md#how-to-build-and-install-the-latest-version-from-source
 
@@ -59,17 +37,4 @@ installing them:
 - Use “Install from file…” in the top-right menu in the Add-ons Manager.
 
 
-## What is a signed add-on?
-
-By default it is not possible to install add-ons which haven’t been signed by
-Mozilla. In order for an add-on to be signed it must pass some code checks. The
-idea is to protect users from malware.
-
-If you’re interested in installing an unsigned add-on (such as if you’ve built
-a VimFx .xpi from source yourself), read all about extension signing here:
-
-<https://wiki.mozilla.org/Addons/Extension_Signing>
-
-
 [open-xpi]: #how-to-install-an-xpi-file-in-firefox
-[signed]: #what-is-a-signed-add-on
diff --git a/documentation/known-bugs.md b/documentation/known-bugs.md
index 40560d3..ff6c8d7 100644
--- a/documentation/known-bugs.md
+++ b/documentation/known-bugs.md
@@ -5,23 +5,23 @@ are some things that VimFx doesn't play along with well. This page lists
 problems that affect VimFx when run on versions of Firefox we support
 (latest *Release* and *ESR* versions).
 
-## In-Content Responsive Design Mode
+## Responsive Design Mode
 
+**Affected**: Firefox <= 78
 **Workaround**: `devtools.responsive.browserUI.enabled;true`
 
-Launching the (`<iframe mozbrowser>` based) Responsive Design Mode breaks VimFx
-for this tab. The only way to recover is to copy-paste the URL into a new tab.
+Launching the (old) Responsive Design Mode breaks VimFx for this tab. The only
+way to recover is to copy-paste the URL into a new tab.
 
-The [next generation RDM] does not have this bug; it can be enabled by switching
+The [new RDM] does not have this bug; it can be enabled by switching
 `devtools.responsive.browserUI.enabled` to `true` in `about:config` in Firefox
-76 or above. There is no workaround for Firefox 68 ESR.
-<!-- Note: the pref exists since about fx71, but was only considered good enough
-for Nightly 76. -->
+78 ESR. There is no workaround for Firefox 68 ESR.
 
-[next generation RDM]: https://mail.mozilla.org/pipermail/firefox-dev/2020-March/007397.html
+[new RDM]: https://mail.mozilla.org/pipermail/firefox-dev/2020-March/007397.html
 
 ## Fission
 
+**Affected**: (future versions)
 **Workaround**: `fission.autostart;false`
 
 With [Fission] enabled, VimFx can't inspect out-of-process iframes.
@@ -36,4 +36,4 @@ VimFx handles element discovery and interaction, we'd need cross-process-DOM
 APIs that just don't exist right now. -->
 
 [Fission]: https://wiki.mozilla.org/Project_Fission
-[patch is in the works]: https://github.com/girst/VimFx/tree/fission-v2
+[patch is in the works]: https://git.gir.st/VimFx.git/shortlog/refs/heads/fission-v2
diff --git a/documentation/questions-and-answers.md b/documentation/questions-and-answers.md
index 9b36600..48dac51 100644
--- a/documentation/questions-and-answers.md
+++ b/documentation/questions-and-answers.md
@@ -2,13 +2,10 @@
 
 ## I can’t install VimFx!
 
-That’s probably because VimFx is a _legacy_ Firefox extension, which is **not**
-[compatible with Firefox 57+][firefox-57+].
+That’s probably because VimFx is a _legacy_ Firefox extension, which requires
+[LegacyFox] for installation.
 
-See [README.md] for more information.
-
-[firefox-57+]: https://support.mozilla.org/en-US/kb/firefox-add-technology-modernizing
-[README.md]: ../README.md
+[LegacyFox]: https://git.gir.st/LegacyFox.git
 
 ## How do I disable VimFx?
 
diff --git a/documentation/tools.md b/documentation/tools.md
index 10522d4..971d812 100644
--- a/documentation/tools.md
+++ b/documentation/tools.md
@@ -41,21 +41,15 @@ Note that the built .xpi file is [unsigned].
 
 ### Development
 
-First off, you need Firefox version 68 (or a compatible fork) and [LegacyFox].
+You need Firefox version 68 or higher (or a compatible fork) and [LegacyFox].
+Optionally, create a new [Firefox profile] for development.
 
-1. Create a new [Firefox profile] for development.
+To test a new verison, open the build directory in the browser and install the
+XPI from there. Sometimes, you'll have to restart Firefox after
+installation/upgrade.
 
-2. Install the [Extension Auto-Installer] add-on in your development profile.
-
-An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
-unit tests.)
-
-Note that loading VimFx as temporary extension does not work in Firefox Quantum.
-
-[README.md]: ../README.md
 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
-[Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
-[LegacyFox]: https://github.com/girst/LegacyFox
+[LegacyFox]: https://git.gir.st/LegacyFox.git
 
 
 ## Gulp tasks
@@ -79,10 +73,6 @@ internally by other tasks.)
 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
   `build/VimFx.xpi` (an .xpi file is a renamed .zip file).
 
-- `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
-  to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
-  automatically install it. (No need to restart Firefox.)
-
 - Use the `--test` or `-t` option to include the unit test files into the build.
   The output of the tests are `console.log`ed. Use the [browser console], or
   start Firefox from the terminal to see it.
@@ -120,23 +110,6 @@ internally by other tasks.)
 
 - `gulp hints.html` is like `gulp help.html` but for styling hint markers.
 
-### Release
-
-See the [“Making a release”][release] section below for more information.
-
-- `gulp release` tags things with a new version number.
-
-- `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
-  stdout.
-
-- `gulp readme` prints `README.md` as HTML to stdout.
-
-Tip: Add `--silent` at the end of the gulp command to suppress gulp’s standard
-progress output. This allows to pipe stdout to the clipboard, without getting
-unwanted cruft around the output.
-
-[release]: #making-a-release
-
 
 ## Syncing locales
 
@@ -183,39 +156,13 @@ Before making a release, it might be wise to:
 - Inspect the `build/` directory to see that nothing strange has been included
   or generated by `gulp build`.
 
-Steps:
-
-1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
-
-2. Update the version in `package.json` and the minimum Firefox version (if
-   needed).
-
-3. Run `gulp release`, which does the following for you:
+Run `./release` with argument `minor` or `patch`, which does the following for you:
 
+  - Updates the version in `package.json`.
   - Adds a heading with the new version number and today’s date at the top of
     `CHANGELOG.md`.
   - Commits `CHANGELOG.md` and `package.json`.
   - Tags the commit.
-
-4. Run `gulp xpi` to rebuild with the new version number.
-
-5. Try the just build version, just to be sure.
-
-6. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
-   changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
-   prints the latest two (etc). The latter is useful if publishing a new version
-   before the last published version had been reviewed; then the new version
-   should contain both changelog entries.
-
-7. Push to github. Don’t forget to push the tag! (It’s better to do this after
-   the publish on addons.mozilla.org, because sometimes its validator complains.
-   This saves some commits.)
-
-8. Make a “release” out of the new tag on github, and attach an .xpi to it:
-
-   1. Create the .xpi by running `gulp xpi --unlisted`.
-   2. Sign it on AMO.
-   3. Attach to the release.
-
-The idea is to use the contents of `README.md` as the add-on description on
-addons.mozilla.org. You can print it as HTML by running `gulp readme`.
+  - Lints the code and builds an xpi.
+  - Opens the browser to help publish the release on GitHub, and to attach an
+    .xpi to it.
-- 
2.39.3