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 First off, you need a Firefox version old enough to support _legacy_ extensions.
45 See [README.md] for more information.
47 1. Create a new [Firefox profile] for development.
49 2. Install the [Extension Auto-Installer] add-on in your development profile.
51 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
54 [README.md]: ../README.md
55 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
56 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
61 [gulp] is a task runner, which is used to automate most VimFx tasks.
63 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
66 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
67 internally by other tasks.)
69 [gulpfile.coffee]: ../gulpfile.coffee
73 - `gulp build` creates the `build/` directory. It is basically a copy of the
74 `extension/` directory, except some of the files have been compiled. For
75 example, the .coffee files are compiled to .js.
77 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
78 `build/VimFx.xpi` (an .xpi file is a renamed .zip file).
80 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
81 to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
82 automatically install it. (No need to restart Firefox.)
84 - Use the `--test` or `-t` option to include the unit test files into the build.
85 The output of the tests are `console.log`ed. Use the [browser console], or
86 start Firefox from the terminal to see it.
88 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
89 This is used when adding .xpi files to github releases.
91 - `gulp clean` removes the `build/` directory.
93 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
97 - `gulp lint` lints all .coffee files. There’s also `npm run addons-linter` to
98 run [`addons-linter`] on a freshly built VimFx .xpi.
100 - `gulp sloc` prints comment and source code line counts.
102 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
103 section below for more information.
105 [`addons-linter`]: https://github.com/mozilla/addons-linter/
106 [sync-locales]: #syncing-locales
110 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
111 lot and wish it ran faster, just tell it and it will! You’ll have to remember
112 to re-run `gulp faster` whenever `gulpfile.coffee` is updated, though.
114 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts help dialog into
115 `help.html`. You can then open up `help.html` in Firefox and style it live
116 using the Style Editor! You can even press the “Save” button when done to save
119 - `gulp hints.html` is like `gulp help.html` but for styling hint markers.
123 See the [“Making a release”][release] section below for more information.
125 - `gulp release` tags things with a new version number.
127 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
130 - `gulp readme` prints `README.md` as HTML to stdout.
132 Tip: Add `--silent` at the end of the gulp command to suppress gulp’s standard
133 progress output. This allows to pipe stdout to the clipboard, without getting
134 unwanted cruft around the output.
136 [release]: #making-a-release
141 This is usually not done by translators, but by developers who change, add or
142 remove features that involves localized text.
144 If you add, remove or reorder translations in a file, do so in _one_ of the
145 locales (one that is easy for you to test—but always write new translations in
146 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
147 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
148 That rewrites all other locales so that:
150 - Old translations are removed.
151 - New translations are added (in English).
152 - All translations appear in the same order.
154 If you modify an existing translation in a file and want to update all other
155 locales to use the new wording, add `UPDATE_ALL` at the end of it. `gulp
156 sync-locales` will then use that translation in _all_ locales, replacing what
157 was there before. It also removes `UPDATE_ALL` for you. However, if possible,
158 edit all other locales by hand to save as much translated text as possible.
160 Note that `gulp sync-locales` requires every translation to be in a single line.
161 In other words, do not line-wrap translations. Also don’t bother adding comments
162 when translating locale files, since they will be removed by `gulp
165 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
166 printed telling how complete all other locales are. Add `--sv-SE?` (note the
167 question mark) to restrict the report to the “sv-SE” locale (you can of course
168 substitute with any other locale). In that case, every line (including line
169 number) that don’t differ compared to “en-US” is also be printed.
174 Before making a release, it might be wise to:
176 - Run `npm update` and/or `npm outdated` to see if there are any updates to
177 dependencies. Investigate what’s new and test!
178 - Run `gulp sync-locales` to make sure that no translation has been left behind.
179 - Run `gulp lint` and `npm run addons-linter` to catch potential problems.
180 - Run `gulp --test` to make sure the tests pass.
181 - Inspect the `build/` directory to see that nothing strange has been included
182 or generated by `gulp build`.
186 1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
188 2. Update the version in `package.json` and the minimum Firefox version (if
191 3. Run `gulp release`, which does the following for you:
193 - Adds a heading with the new version number and today’s date at the top of
195 - Commits `CHANGELOG.md` and `package.json`.
198 4. Run `gulp xpi` to rebuild with the new version number.
200 5. Try the just build version, just to be sure.
202 6. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
203 changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
204 prints the latest two (etc). The latter is useful if publishing a new version
205 before the last published version had been reviewed; then the new version
206 should contain both changelog entries.
208 7. Push to github. Don’t forget to push the tag! (It’s better to do this after
209 the publish on addons.mozilla.org, because sometimes its validator complains.
210 This saves some commits.)
212 8. Make a “release” out of the new tag on github, and attach an .xpi to it:
214 1. Create the .xpi by running `gulp xpi --unlisted`.
216 3. Attach to the release.
218 The idea is to use the contents of `README.md` as the add-on description on
219 addons.mozilla.org. You can print it as HTML by running `gulp readme`.