documentation/tools.md

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