2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015.
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
19 1. Install [Node.js] or [io.js].
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`: `npm run gulp -- xpi`. (Note that
27 you might need to update `npm` for this to run; try `npm update -g npm`.)
29 [Node.js]: http://nodejs.org/
30 [io.js]: https://iojs.org/
31 [gulp]: https://github.com/gulpjs/gulp
35 ### How to build and install the latest version from source
37 1. Follow the installation instructions above.
39 2. Run `npm run gulp -- xpi`.
41 3. Install `build/VimFx.xpi` in Firefox by doing one of the following:
43 - Dragging and dropping it.
44 - Pressing ctrl+o and choosing it.
45 - Using “Install from file…” in the top-right menu in the Add-ons Manager.
49 1. Create a new [Firefox profile] for development.
51 2. Install the [Extension Auto-Installer] add-on in your development profile.
53 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
56 If you’re having problems, don’t forget to try `npm update`. Your problem might
57 be in a dependency and already have been fixed.
59 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
60 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
65 [gulp] is the task runner used to automate most of the common VimFx tasks.
67 The tasks are defined in [gulpfile.coffee]. They are summarized in the follwing
70 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
71 internally by other tasks.)
73 [gulpfile.coffee]: ../gulpfile.coffee
77 - `gulp build` creates the `build/` directory. It is basically a copy of the
78 `extension/` directory, with some of the files being compiled. For example,
79 the `.coffee` files compiled to `.js`.
81 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
84 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
85 to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
86 automatically install it. (No need to restart Firefox.)
88 - Use the `--test` or `-t` option to include the unit test files. The output of
89 the tests are `console.log`ed. See the browser console, or start Firefox from
90 the command line to see it.
92 - `gulp clean` removes the `build/` directory.
96 - `gulp lint` lints all `.coffee` files.
98 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
99 section below for more information.
101 [sync-locales]: #syncing-locales
105 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
106 lot and wish it ran faster, just tell it and it will! You’ll have to remember
107 to re-run it whenever gulpfile.coffee is updated, though.
109 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts dialog into `help.html`. You
110 can then open up `help.html` in Firefox and style it live using the Style
111 Editor! You can even press the “Save” button when done to save your changes!
115 See the [“Making a release”][release] section below for more information.
117 - `gulp release` tags things with a new version number.
119 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
122 - `gulp readme` prints `README.md` as HTML to stdout.
124 [release]: #making-a-release
129 This is usually not done by translators, but by developers who change, add or
130 remove features that involves localized text.
132 If you add, remove or reorder translations in a file, do so in _one_ of the
133 locales (one that is easy for you to test—but always write new translations in
134 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
135 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
136 That rewrites all other locales so that:
138 - Old translations are removed.
139 - New translations are added (in English).
140 - All translations appear in the same order.
142 If you modify an existing translation in a file and want to update all other
143 locales to use the new wording:
145 - If possible, edit all other locales by hand to save as much translated text as
150 1. Before modifying existing translations, copy the file in question and add
151 the extension `.old` to the filename. For example, copy a
152 `vimfx.properties` file to `vimfx.properties.old`.
153 2. Make your modifications (in for example `vimfx.properties`, leaving
154 `vimfx.properties.old` intact).
155 3. Run `gulp sync-locales`. It does the same thing as before, except that if a
156 translation has changed compared to an `.old`-file, the newly changed
157 translation is used in all locales, replacing what was there before.
158 4. Remove the `.old`-file.
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’ll likely be removed by `gulp
168 Before making a release, it might be wise to:
170 - Run `npm update` and/or `npm outdated` to see if there are any updates to
171 dependencies. Investigate what’s new and test!
172 - Run `gulp sync-locales` to make sure that no translation has been left behind.
173 - Inspect the `build/` directory to see that nothing strange has been included
174 or generated by `gulp build`.
178 1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
180 2. Update the version in `package.json` (see `CONTRIBUTING-CODE.md` about
181 versioning), and, if needed, the minimum Firefox version.
183 3. Run `gulp release`, which does the following for you:
185 - Adds a heading with the new version number and today’s date at the top of
187 - Commits CHANGELOG.md and package.json.
190 4. Run `gulp xpi` to rebuild with the new version number.
192 5. Push to github. Don’t forget to push the tag!
194 6. Make a “release” out of the new tag on github, and attach VimFx.xpi to it.
196 7. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
197 changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
198 prints the latest two (etc). The latter is useful if publishing a new version
199 before the last published version had been reviewed; then the new version
200 should contain both changelog entries.
202 The idea is to use the contents of `README.md` as the add-on descripton on
203 addons.mozilla.org. You can print it as HTML by runnning `gulp readme`.