3 This section describes how to install and use the tools needed to:
5 - Build VimFx from source
15 2. Run `npm install` to download dependencies and development dependencies.
17 3. Optional: Run `npm install --global gulp` to be able to run [`gulp`][gulp]
20 If you prefer not to install `gulp` globally, you can use `npm run gulp`
21 instead. For example, to create an .xpi file: `npm run gulp -- xpi`.
23 [Node.js]: http://nodejs.org/
24 [gulp]: https://github.com/gulpjs/gulp
29 ### How to build and install the latest version from source
31 1. Follow the installation instructions above.
33 2. Run `npm run gulp -- xpi`.
35 3. [Open `build/VimFx.xpi` in Firefox][open-xpi].
37 Note that the built .xpi file is [unsigned].
39 [open-xpi]: installation.md#how-to-install-an-xpi-file-in-firefox
40 [unsigned]: installation.md#what-is-a-signed-add-on
44 You need Firefox version 68 or higher (or a compatible fork) and [LegacyFox].
45 Optionally, create a new [Firefox profile] for development.
47 To test a new verison, open the build directory in the browser and install the
48 XPI from there. Sometimes, you'll have to restart Firefox after
51 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
52 [LegacyFox]: https://git.gir.st/LegacyFox.git
57 [gulp] is a task runner, which is used to automate most VimFx tasks.
59 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
62 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
63 internally by other tasks.)
65 [gulpfile.coffee]: ../gulpfile.coffee
69 - `gulp build` creates the `build/` directory. It is basically a copy of the
70 `extension/` directory, except some of the files have been compiled. For
71 example, the .coffee files are compiled to .js.
73 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
74 `build/VimFx.xpi` (an .xpi file is a renamed .zip file).
76 - Use the `--test` or `-t` option to include the unit test files into the build.
77 The output of the tests are `console.log`ed. Use the [browser console], or
78 start Firefox from the terminal to see it.
80 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
81 This is used when adding .xpi files to github releases.
83 - `gulp clean` removes the `build/` directory.
85 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
89 - `gulp lint` lints all .coffee files. There’s also `npm run addons-linter` to
90 run [`addons-linter`] on a freshly built VimFx .xpi.
92 - `gulp sloc` prints comment and source code line counts.
94 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
95 section below for more information.
97 [`addons-linter`]: https://github.com/mozilla/addons-linter/
98 [sync-locales]: #syncing-locales
102 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
103 lot and wish it ran faster, just tell it and it will! You’ll have to remember
104 to re-run `gulp faster` whenever `gulpfile.coffee` is updated, though.
106 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts help dialog into
107 `help.html`. You can then open up `help.html` in Firefox and style it live
108 using the Style Editor! You can even press the “Save” button when done to save
111 - `gulp hints.html` is like `gulp help.html` but for styling hint markers.
116 This is usually not done by translators, but by developers who change, add or
117 remove features that involves localized text.
119 If you add, remove or reorder translations in a file, do so in _one_ of the
120 locales (one that is easy for you to test—but always write new translations in
121 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
122 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
123 That rewrites all other locales so that:
125 - Old translations are removed.
126 - New translations are added (in English).
127 - All translations appear in the same order.
129 If you modify an existing translation in a file and want to update all other
130 locales to use the new wording, add `UPDATE_ALL` at the end of it. `gulp
131 sync-locales` will then use that translation in _all_ locales, replacing what
132 was there before. It also removes `UPDATE_ALL` for you. However, if possible,
133 edit all other locales by hand to save as much translated text as possible.
135 Note that `gulp sync-locales` requires every translation to be in a single line.
136 In other words, do not line-wrap translations. Also don’t bother adding comments
137 when translating locale files, since they will be removed by `gulp
140 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
141 printed telling how complete all other locales are. Add `--sv-SE?` (note the
142 question mark) to restrict the report to the “sv-SE” locale (you can of course
143 substitute with any other locale). In that case, every line (including line
144 number) that don’t differ compared to “en-US” is also be printed.
149 Before making a release, it might be wise to:
151 - Run `npm update` and/or `npm outdated` to see if there are any updates to
152 dependencies. Investigate what’s new and test!
153 - Run `gulp sync-locales` to make sure that no translation has been left behind.
154 - Run `gulp lint` and `npm run addons-linter` to catch potential problems.
155 - Run `gulp --test` to make sure the tests pass.
156 - Inspect the `build/` directory to see that nothing strange has been included
157 or generated by `gulp build`.
159 Run `./release` with argument `minor` or `patch`, which does the following for you:
161 - Updates the version in `package.json`.
162 - Adds a heading with the new version number and today’s date at the top of
163 `CHANGELOG.md`, and the summary of commits since the last version. Then
164 opens an editor and waits to let you modify the changelog.
165 - Commits `CHANGELOG.md` and `package.json`.
167 - Lints the code and builds an xpi.
168 - Opens the browser to help publish the release on GitHub, and to attach an