documentation/tools.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015.
   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`: `npm run gulp -- xpi`. (Note that
  27    you might need to update `npm` for this to run; try `npm update -g npm`.)
  28
  29 [Node.js]: http://nodejs.org/
  30 [gulp]: https://github.com/gulpjs/gulp
  31
  32 ## Getting started
  33
  34 ### How to build and install the latest version from source
  35
  36 1. Follow the installation instructions above.
  37
  38 2. Run `npm run gulp -- xpi`.
  39
  40 3. Install `build/VimFx.xpi` in Firefox by doing one of the following:
  41
  42    - Dragging and dropping it.
  43    - Pressing ctrl+o and choosing it.
  44    - Using “Install from file…” in the top-right menu in the Add-ons Manager.
  45
  46 **Note:** Since Mozilla added [extension signing] things have gotten a bit more
  47 complicated.
  48
  49 [extension signing]: https://wiki.mozilla.org/Addons/Extension_Signing
  50
  51 ### Development
  52
  53 1. Create a new [Firefox profile] for development.
  54
  55 2. Install the [Extension Auto-Installer] add-on in your development profile.
  56
  57 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
  58 unit tests.)
  59
  60 If you’re having problems, don’t forget to try `npm update`. Your problem might
  61 be in a dependency and already have been fixed.
  62
  63 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
  64 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
  65
  66
  67 ## Gulp tasks
  68
  69 [gulp] is the task runner used to automate most of the common VimFx tasks.
  70
  71 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
  72 sub-sections.
  73
  74 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
  75 internally by other tasks.)
  76
  77 [gulpfile.coffee]: ../gulpfile.coffee
  78
  79 ### Building
  80
  81 - `gulp build` creates the `build/` directory. It is basically a copy of the
  82   `extension/` directory, with some of the files being compiled. For example,
  83   the `.coffee` files compiled to `.js`.
  84
  85 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
  86   `build/VimFx.xpi`.
  87
  88 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
  89   to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
  90   automatically install it. (No need to restart Firefox.)
  91
  92 - Use the `--test` or `-t` option to include the unit test files. The output of
  93   the tests are `console.log`ed. See the browser console, or start Firefox from
  94   the command line to see it.
  95
  96 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
  97   This is used when adding .xpi files to github releases.
  98
  99 - `gulp clean` removes the `build/` directory.
 100
 101 ### Management
 102
 103 - `gulp lint` lints all `.coffee` files.
 104
 105 - `gulp sloc` prints comment and source code line counts.
 106
 107 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
 108   section below for more information.
 109
 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 dialog into `help.html`. You
 119   can then open up `help.html` in Firefox and style it live using the Style
 120   Editor! You can even press the “Save” button when done to save your changes!
 121
 122 ### Release
 123
 124 See the [“Making a release”][release] section below for more information.
 125
 126 - `gulp release` tags things with a new version number.
 127
 128 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
 129   stdout.
 130
 131 - `gulp readme` prints `README.md` as HTML to stdout.
 132
 133 Tip: Add `--silent` at the end of the gulp command to suppress gulp’s standard
 134 progress output, allowing to pipe stdout to the clipboard.
 135
 136 [release]: #making-a-release
 137
 138
 139 ## Syncing locales
 140
 141 This is usually not done by translators, but by developers who change, add or
 142 remove features that involves localized text.
 143
 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:
 149
 150 - Old translations are removed.
 151 - New translations are added (in English).
 152 - All translations appear in the same order.
 153
 154 If you modify an existing translation in a file and want to update all other
 155 locales to use the new wording:
 156
 157 - If possible, edit all other locales by hand to save as much translated text as
 158   possible.
 159
 160 - Otherwise:
 161
 162   1. Before modifying existing translations, copy the file in question and add
 163      the extension `.old` to the filename. For example, copy a
 164      `vimfx.properties` file to `vimfx.properties.old`.
 165   2. Make your modifications (in for example `vimfx.properties`, leaving
 166      `vimfx.properties.old` intact).
 167   3. Run `gulp sync-locales`. It does the same thing as before, except that if a
 168      translation has changed compared to an `.old`-file, the newly changed
 169      translation is used in all locales, replacing what was there before.
 170   4. Remove the `.old`-file.
 171
 172 Note that `gulp sync-locales` requires every translation to be in a single line.
 173 In other words, do not line-wrap translations. Also don’t bother adding comments
 174 when translating locale files, since they’ll likely be removed by `gulp
 175 sync-locales`.
 176
 177 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
 178 printed telling how complete all other locales are. Add `--sv-SE?` (note the
 179 question mark) to restrict the report to the “sv-SE” locale (you can of course
 180 substitute with any other locale). In that case, every line (including line
 181 number) that don’t differ compared to “en-US” is also be printed.
 182
 183
 184 ## Making a release
 185
 186 Before making a release, it might be wise to:
 187
 188 - Run `npm update` and/or `npm outdated` to see if there are any updates to
 189   dependencies. Investigate what’s new and test!
 190 - Run `gulp sync-locales` to make sure that no translation has been left behind.
 191 - Inspect the `build/` directory to see that nothing strange has been included
 192   or generated by `gulp build`.
 193
 194 Steps:
 195
 196 1. Add a list of changes since the last version at the top of `CHANGELOG.md`.
 197
 198 2. Update the version in `package.json` (see `CONTRIBUTING-CODE.md` about
 199    versioning), the minimum Firefox version (if needed) and the maximum Firefox
 200    version (ideally to the latest nightly). See [valid Firefox versions].
 201
 202 3. Run `gulp release`, which does the following for you:
 203
 204   - Adds a heading with the new version number and today’s date at the top of
 205     CHANGELOG.md.
 206   - Commits CHANGELOG.md and package.json.
 207   - Tags the commit.
 208
 209 4. Run `gulp xpi` to rebuild with the new version number.
 210
 211 5. Try the just build version, just to be sure.
 212
 213 6. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
 214    changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
 215    prints the latest two (etc). The latter is useful if publishing a new version
 216    before the last published version had been reviewed; then the new version
 217    should contain both changelog entries.
 218
 219 7. Push to github. Don’t forget to push the tag! (It’s better to do this after
 220    the publish on addons.mozilla.org, because sometimes its validator complains.
 221    This saves some commits.)
 222
 223 8. Make a “release” out of the new tag on github, and attach an .xpi to it:
 224
 225    1. Create the .xpi by running `gulp xpi --unlisted`.
 226    2. Sign it on AMO.
 227    3. Attach to the release.
 228
 229 The idea is to use the contents of `README.md` as the add-on description on
 230 addons.mozilla.org. You can print it as HTML by running `gulp readme`.
 231
 232 [valid Firefox versions]: https://addons.mozilla.org/en-US/firefox/pages/appversions/