documentation/tools.md

   1 # Tools
   2
   3 This section describes how to install and use the tools needed to:
   4
   5 - Build VimFx from source
   6 - Lint code
   7 - Sync locales
   8 - Prepare releases
   9
  10
  11 ## Installation
  12
  13 1. Install [Node.js].
  14
  15 2. Run `npm install` to download dependencies and development dependencies.
  16
  17 3. Optional: Run `npm install --global gulp` to be able to run [`gulp`][gulp]
  18    from the terminal.
  19
  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`.
  22
  23 [Node.js]: http://nodejs.org/
  24 [gulp]: https://github.com/gulpjs/gulp
  25
  26
  27 ## Getting started
  28
  29 ### How to build and install the latest version from source
  30
  31 1. Follow the installation instructions above.
  32
  33 2. Run `npm run gulp -- xpi`.
  34
  35 3. [Open `build/VimFx.xpi` in Firefox][open-xpi].
  36
  37 Note that the built .xpi file is [unsigned].
  38
  39 [open-xpi]: installation.md#how-to-install-an-xpi-file-in-firefox
  40 [unsigned]: installation.md#what-is-a-signed-add-on
  41
  42 ### Development
  43
  44 1. Create a new [Firefox profile] for development.
  45
  46 2. Install the [Extension Auto-Installer] add-on in your development profile.
  47
  48 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
  49 unit tests.)
  50
  51 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
  52 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
  53
  54
  55 ## Gulp tasks
  56
  57 [gulp] is a task runner, which is used to automate most VimFx tasks.
  58
  59 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
  60 sub-sections.
  61
  62 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
  63 internally by other tasks.)
  64
  65 [gulpfile.coffee]: ../gulpfile.coffee
  66
  67 ### Building
  68
  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.
  72
  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).
  75
  76 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
  77   to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
  78   automatically install it. (No need to restart Firefox.)
  79
  80 - Use the `--test` or `-t` option to include the unit test files into the build.
  81   The output of the tests are `console.log`ed. Use the [browser console], or
  82   start Firefox from the terminal to see it.
  83
  84 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
  85   This is used when adding .xpi files to github releases.
  86
  87 - `gulp clean` removes the `build/` directory.
  88
  89 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  90
  91 ### Management
  92
  93 - `gulp lint` lints all .coffee files. There’s also `npm run addons-linter` to
  94   run [`addons-linter`] on a freshly built VimFx .xpi.
  95
  96 - `gulp sloc` prints comment and source code line counts.
  97
  98 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
  99   section below for more information.
 100
 101 [`addons-linter`]: https://github.com/mozilla/addons-linter/
 102 [sync-locales]: #syncing-locales
 103
 104 ### Helpers
 105
 106 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
 107   lot and wish it ran faster, just tell it and it will! You’ll have to remember
 108   to re-run `gulp faster` whenever `gulpfile.coffee` is updated, though.
 109
 110 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts help dialog into
 111   `help.html`. You can then open up `help.html` in Firefox and style it live
 112   using the Style Editor! You can even press the “Save” button when done to save
 113   your changes!
 114
 115 - `gulp hints.html` is like `gulp help.html` but for styling hint markers.
 116
 117 ### Release
 118
 119 See the [“Making a release”][release] section below for more information.
 120
 121 - `gulp release` tags things with a new version number.
 122
 123 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
 124   stdout.
 125
 126 - `gulp readme` prints `README.md` as HTML to stdout.
 127
 128 Tip: Add `--silent` at the end of the gulp command to suppress gulp’s standard
 129 progress output. This allows to pipe stdout to the clipboard, without getting
 130 unwanted cruft around the output.
 131
 132 [release]: #making-a-release
 133
 134
 135 ## Syncing locales
 136
 137 This is usually not done by translators, but by developers who change, add or
 138 remove features that involves localized text.
 139
 140 If you add, remove or reorder translations in a file, do so in _one_ of the
 141 locales (one that is easy for you to test—but always write new translations in
 142 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
 143 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
 144 That rewrites all other locales so that:
 145
 146 - Old translations are removed.
 147 - New translations are added (in English).
 148 - All translations appear in the same order.
 149
 150 If you modify an existing translation in a file and want to update all other
 151 locales to use the new wording, add `UPDATE_ALL` at the end of it. `gulp
 152 sync-locales` will then use that translation in _all_ locales, replacing what
 153 was there before. It also removes `UPDATE_ALL` for you. However, if possible,
 154 edit all other locales by hand to save as much translated text as possible.
 155
 156 Note that `gulp sync-locales` requires every translation to be in a single line.
 157 In other words, do not line-wrap translations. Also don’t bother adding comments
 158 when translating locale files, since they will be removed by `gulp
 159 sync-locales`.
 160
 161 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
 162 printed telling how complete all other locales are. Add `--sv-SE?` (note the
 163 question mark) to restrict the report to the “sv-SE” locale (you can of course
 164 substitute with any other locale). In that case, every line (including line
 165 number) that don’t differ compared to “en-US” is also be printed.
 166
 167
 168 ## Making a release
 169
 170 Before making a release, it might be wise to:
 171
 172 - Run `npm update` and/or `npm outdated` to see if there are any updates to
 173   dependencies. Investigate what’s new and test!
 174 - Run `gulp sync-locales` to make sure that no translation has been left behind.
 175 - Run `gulp lint` and `npm run addons-linter` to catch potential problems.
 176 - Run `gulp --test` to make sure the tests pass.
 177 - Inspect the `build/` directory to see that nothing strange has been included
 178   or generated by `gulp build`.
 179
 180 Steps:
 181
 182 1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
 183
 184 2. Update the version in `package.json` ([versioning guidelines]), the minimum
 185    Firefox version (if needed) and the maximum Firefox version (ideally to the
 186    latest nightly). See [valid Firefox versions].
 187
 188 3. Run `gulp release`, which does the following for you:
 189
 190   - Adds a heading with the new version number and today’s date at the top of
 191     `CHANGELOG.md`.
 192   - Commits `CHANGELOG.md` and `package.json`.
 193   - Tags the commit.
 194
 195 4. Run `gulp xpi` to rebuild with the new version number.
 196
 197 5. Try the just build version, just to be sure.
 198
 199 6. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
 200    changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
 201    prints the latest two (etc). The latter is useful if publishing a new version
 202    before the last published version had been reviewed; then the new version
 203    should contain both changelog entries.
 204
 205 7. Push to github. Don’t forget to push the tag! (It’s better to do this after
 206    the publish on addons.mozilla.org, because sometimes its validator complains.
 207    This saves some commits.)
 208
 209 8. Make a “release” out of the new tag on github, and attach an .xpi to it:
 210
 211    1. Create the .xpi by running `gulp xpi --unlisted`.
 212    2. Sign it on AMO.
 213    3. Attach to the release.
 214
 215 The idea is to use the contents of `README.md` as the add-on description on
 216 addons.mozilla.org. You can print it as HTML by running `gulp readme`.
 217
 218 [versioning guidelines]: CONTRIBUTING-CODE.md#versioning-and-branches
 219 [valid Firefox versions]: https://addons.mozilla.org/en-US/firefox/pages/appversions/