2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015, 2016.
4 See the file README.md for copying conditions.
9 This section describes how to install and use the tools needed to:
11 - Build VimFx from source
21 2. Run `npm install` to download dependencies and development dependencies.
23 3. Optional: Run `npm install -g gulp` to be able to run [`gulp`][gulp] tasks.
25 If you prefer not to install gulp globally, you can use `npm run gulp`
26 instead. For example, to create an .xpi file: `npm run gulp -- xpi`. (Note
27 that you might need to update `npm` for this to run; try `npm update -g
30 [Node.js]: http://nodejs.org/
31 [gulp]: https://github.com/gulpjs/gulp
36 ### How to build and install the latest version from source
38 1. Follow the installation instructions above.
40 2. Run `npm run gulp -- xpi`.
42 3. [Open `build/VimFx.xpi` in Firefox][open-xpi].
44 Note that the built .xpi file is [unsigned].
46 [open-xpi]: installation.md#how-to-install-an-xpi-file-in-firefox
47 [unsigned]: installation.md#what-is-a-signed-add-on
51 1. Create a new [Firefox profile] for development.
53 2. Install the [Extension Auto-Installer] add-on in your development profile.
55 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
58 If you’re having problems, don’t forget to try `npm update`. Your problem might
59 be in a dependency and already have been fixed.
61 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
62 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
67 [gulp] is the task runner used to automate most of the common VimFx tasks.
69 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
72 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
73 internally by other tasks.)
75 [gulpfile.coffee]: ../gulpfile.coffee
79 - `gulp build` creates the `build/` directory. It is basically a copy of the
80 `extension/` directory, with some of the files being compiled. For example,
81 the `.coffee` files compiled to `.js`.
83 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
86 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
87 to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
88 automatically install it. (No need to restart Firefox.)
90 - Use the `--test` or `-t` option to include the unit test files. The output of
91 the tests are `console.log`ed. See the [browser console], or start Firefox
92 from the command line to see it.
94 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
95 This is used when adding .xpi files to github releases.
97 - `gulp clean` removes the `build/` directory.
99 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
103 - `gulp lint` lints all `.coffee` files. There’s also `npm run addons-linter` to
104 run [`addons-linter`] on a freshly built VimFx .xpi.
106 - `gulp sloc` prints comment and source code line counts.
108 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
109 section below for more information.
111 [`addons-linter`]: https://github.com/mozilla/addons-linter/
112 [sync-locales]: #syncing-locales
116 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
117 lot and wish it ran faster, just tell it and it will! You’ll have to remember
118 to re-run it whenever gulpfile.coffee is updated, though.
120 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts help dialog into
121 `help.html`. You can then open up `help.html` in Firefox and style it live
122 using the Style Editor! You can even press the “Save” button when done to save
127 See the [“Making a release”][release] section below for more information.
129 - `gulp release` tags things with a new version number.
131 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
134 - `gulp readme` prints `README.md` as HTML to stdout.
136 Tip: Add `--silent` at the end of the gulp command to suppress gulp’s standard
137 progress output, allowing to pipe stdout to the clipboard.
139 [release]: #making-a-release
144 This is usually not done by translators, but by developers who change, add or
145 remove features that involves localized text.
147 If you add, remove or reorder translations in a file, do so in _one_ of the
148 locales (one that is easy for you to test—but always write new translations in
149 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
150 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
151 That rewrites all other locales so that:
153 - Old translations are removed.
154 - New translations are added (in English).
155 - All translations appear in the same order.
157 If you modify an existing translation in a file and want to update all other
158 locales to use the new wording:
160 - If possible, edit all other locales by hand to save as much translated text as
165 1. Before modifying existing translations, copy the file in question and add
166 the extension `.old` to the filename. For example, copy a
167 `vimfx.properties` file to `vimfx.properties.old`.
168 2. Make your modifications (in for example `vimfx.properties`, leaving
169 `vimfx.properties.old` intact).
170 3. Run `gulp sync-locales`. It does the same thing as before, except that if a
171 translation has changed compared to an `.old`-file, the newly changed
172 translation is used in all locales, replacing what was there before.
173 4. Remove the `.old`-file.
175 Note that `gulp sync-locales` requires every translation to be in a single line.
176 In other words, do not line-wrap translations. Also don’t bother adding comments
177 when translating locale files, since they’ll likely be removed by `gulp
180 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
181 printed telling how complete all other locales are. Add `--sv-SE?` (note the
182 question mark) to restrict the report to the “sv-SE” locale (you can of course
183 substitute with any other locale). In that case, every line (including line
184 number) that don’t differ compared to “en-US” is also be printed.
189 Before making a release, it might be wise to:
191 - Run `npm update` and/or `npm outdated` to see if there are any updates to
192 dependencies. Investigate what’s new and test!
193 - Run `gulp sync-locales` to make sure that no translation has been left behind.
194 - Inspect the `build/` directory to see that nothing strange has been included
195 or generated by `gulp build`.
199 1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
201 2. Update the version in `package.json` ([versioning guidelines]), the minimum
202 Firefox version (if needed) and the maximum Firefox version (ideally to the
203 latest nightly). See [valid Firefox versions].
205 3. Run `gulp release`, which does the following for you:
207 - Adds a heading with the new version number and today’s date at the top of
209 - Commits CHANGELOG.md and package.json.
212 4. Run `gulp xpi` to rebuild with the new version number.
214 5. Try the just build version, just to be sure.
216 6. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
217 changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
218 prints the latest two (etc). The latter is useful if publishing a new version
219 before the last published version had been reviewed; then the new version
220 should contain both changelog entries.
222 7. Push to github. Don’t forget to push the tag! (It’s better to do this after
223 the publish on addons.mozilla.org, because sometimes its validator complains.
224 This saves some commits.)
226 8. Make a “release” out of the new tag on github, and attach an .xpi to it:
228 1. Create the .xpi by running `gulp xpi --unlisted`.
230 3. Attach to the release.
232 The idea is to use the contents of `README.md` as the add-on description on
233 addons.mozilla.org. You can print it as HTML by running `gulp readme`.
235 [versioning guidelines]: CONTRIBUTING_CODE.md#versioning-and-branches
236 [valid Firefox versions]: https://addons.mozilla.org/en-US/firefox/pages/appversions/