Refactor extension to webpack
This change is the biggest in the history of the project. The entire
project has been refactored so it is built with webpack.
This involves:
- Creating webpack and npm config files.
- Fixing some bugs in the code due to the fact that webpack uses strict
mode.
- Merging some pieces of code which were shared throughout the codebase
(not exhaustive, more work should be done in this direction).
- Splitting the console_inject.js file into separate files (it had 1000+
lines).
- Adapting all the build-related files (Makefile, bash scripts, etc.)
- Changing the docs to explain the new build process.
- Changing the Zuul playbook/roles to adapt to the new build process.
Change-Id: I16476d47825461c3a318b3f1a1eddb06b2df2e89
diff --git a/docs/developers/add_feature.md b/docs/developers/add_feature.md
index 15053e4..12ec328 100644
--- a/docs/developers/add_feature.md
+++ b/docs/developers/add_feature.md
@@ -9,22 +9,21 @@
### How to add the feature switch option
1. First of all, think of a short codename for the feature.
-2. Modify the `//src/common/common.js` file by adding an entry in the
-`optionsPrototype` object.
+2. Modify the `//src/common/optionsPrototype.json5` file by adding an entry.
- All features should have the `false` value set as a default, so existing
users have to explicitly enable the option after they receive the extension
update. Otherwise, it might cause confusion, because users wouldn't know if
the feature was added by the extension or Google.
-3. Now, modify the `//src/options/options.html` file by appending the following
-HTML code in the corresponding section:
+3. Now, modify the `//src/static/options/options.html` file by appending the
+following HTML code in the corresponding section:
```
<div class="option"><input type="checkbox" id="{{codename}}"> <label for="{{codename}}" data-i18n="{{codename}}"></label> <span class="experimental-label" data-i18n="experimental_label"></span></div>
```
where you should substitute `{{codename}}` with the codename you've chosen.
The _experimental_ label is optional and should only be used with features which
are unreliable (or could be at some point in the future) due to their nature.
-4. Finally, add the option string at `//src/_locales/en/manifest.json`, by
-adding the string under the `options_{{codename}}` key.
+4. Finally, add the option string at `//src/static/_locales/en/manifest.json`,
+by adding the string under the `options_{{codename}}` key.
### How to add additional options for the feature
Apart from the feature switch option, additional options can be defined in order
@@ -58,30 +57,33 @@
1. Think of a codename for the additional option. It should be the feature
codename appended by an underscore and a suffix
(`{{feature_codename}}_{{suffix}}`).
-2. Modify the `//src/common/common.js` file by doing the following things:
- 1. Add an entry for the option in the `optionsPrototype` object.
- 2. Append the option's codename to the `specialOptions` object. This is so
- the option can be handled in a specific way when showing/saving it in the
- options page, or so it is handled outside of the options page.
+2. Modify the following files:
+ 1. Add an entry for the option in the `//src/common/optionsPrototype.json5`
+ file.
+ 2. Append the option's codename to the `//src/common/specialOptions.json5`
+ file. This is so the option can be handled in a specific way when
+ showing/saving it in the options page, or so it is handled outside of the
+ options page.
3. If you want to handle the option from the options page, follow these steps:
- 1. Modify the `//src/options/options.html` file to add the appropriate code
- which implements the option (usually in the same `.option` div as the
- feature switch).
+ 1. Modify the `//src/static/options/options.html` file to add the
+ appropriate code which implements the option (usually in the same `.option`
+ div as the feature switch).
- Don't include text, only the HTML structure. If you add a `data-i18n`
attribute to an HTML element, its contents will be replaced with the
corresponding i18n string (for instance,
`<span data-i18n="test"></span>` will be rendered as
`<span data-i18n="test">Test</span>` if `Test` was the string defined
with the key `options_test`).
- 2. Modify the `//src/options/options.js` file to add the following things:
+ 2. Modify the `//src/optionsCommon.js` file to add the following things:
1. In the switch statement inside the save function, add a case to
handle saving your additional option.
2. In the switch statement inside the load event listener, add another
case so your option is correctly set in the options page with the saved
value.
- 3. Add the corresponding i18n strings at `//src/_locales/en/manifest.json`.
+ 3. Add the corresponding i18n strings at
+ `//src/static/_locales/en/manifest.json`.
4. If you want to handle the option outside of the options page, include an
-empty case in both switches at `//src/options/options.js`, so the option is not
+empty case in both switches at `//src/optionsCommon.js`, so the option is not
handled there.
## Develop the feature
diff --git a/docs/developers/build.md b/docs/developers/build.md
index 76a1175..9fe8e75 100644
--- a/docs/developers/build.md
+++ b/docs/developers/build.md
@@ -1,41 +1,38 @@
# Build the extension
A zip file with the contents of the extension, which can be uploaded to the
-Chrome Web Store and addons.mozilla.org, can be created with any of the
-following procedures (make sure to [install Go](https://golang.org) before
-building the extension, as it is needed during the build):
+Chrome Web Store and addons.mozilla.org, can be created by following these
+instructions. (make sure to [install Go](https://golang.org) before building the
+extension, as it is needed during the build).
-## Using the release.bash script
-Run `bash release.bash -h` in order to learn how to use this command. To
-summarize, the command accepts the `--channel` and `--browser` flags (or their
-short versions `-c` and `-b`).
+The last section explains how to build the extension automatically when you
+change the source code.
-As an example, if you wanted to create a ZIP file of the beta-branded extension
-targeted for Firefox, you would run `bash release.bash -c beta -b gecko`.
-
-## Using make
-You can also use _make_ to build the extension. This is just a wrapper for the
-`release.bash` command.
-
-Run `make all` to build the extension for all the available channels and
+## Build the extension as a zip file
+Run `make release` to build the extension for all the available channels and
browsers. You can also run `make {target}` where `{target}` is one of the
-following: `chromium-stable`, `chromium-beta`, `chromium-mv3-beta`,
-`gecko-stable`.
+following: `release_chromium_stable`, `release_chromium_beta`,
+`release_gecko_stable`.
-Run `make clean` to clean all the release files (this removes the `out` folder,
-which is where the release files are saved).
+Run `make clean_releases` to clean all the release files (this removes the `out`
+folder, which is where the release files are saved).
-## Load the extension "without" building it
+Take a look at `Makefile`, you'll find other targets for _make_ which do other
+interesting things (like `clean`, for instance).
+
+## Build the extension continously with webpack development mode
If you're developing the extension, you might want to load it into your browser
-without having to constantly build it after each change. In order to do that,
-you'll only have to manually generate the manifest each time you change the
-`template/manifest.gjson` file (or only once if you don't change it, and once
-every time you pull new changes to your git clone).
+without having to constantly build it manually after each change. In order to do
+that, you can run `make serve_chromium`, `make serve_chromium_mv3` or
+`make serve_gecko` depending on the type of continuous build you want.
-In order to do that, run `go run generateManifest.go {browser}`, where
-`{browser}` is `CHROMIUM`, `GECKO` or `CHROMIUM_MV3`, and this will generate the
-`manifest.json` file for the specified browser in the `src` directory. Now, you
-can load the `src` folder directly in the browser in order to import the
-extension.
+This will run webpack with watch mode and continuously serve a fresh version of
+the compiled extension at `dist/{BROWSER}`, where `{BROWSER}` depends on the
+target you selected for _make_. You can load this folder in Chrome by going to
+`chrome://extensions` and selecting "Load unpacked".
+
+Keep in mind that while the extension is continuously built, it is not
+automatically being loaded into Chrome. You'll have to reload the extension
+manually in Chrome (but at least you won't have to both build and reload it).
## About the _Chromium MV3_ target
Chromium is working in a
diff --git a/docs/developers/set_up.md b/docs/developers/set_up.md
index 650ce31..8106933 100644
--- a/docs/developers/set_up.md
+++ b/docs/developers/set_up.md
@@ -6,7 +6,8 @@
with [Homebrew](https://brew.sh/) by running `brew install go`.
- This is because the build script uses a Go program to generate the
manifest.
-2. That's it! If you're using a Mac, you're out of luck, because you must
+1. [Install NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).
+1. That's it! If you're using a Mac, you're out of luck, because you must
perform some more steps.
## Mac-specific configuration