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