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 First off, you need Firefox version 68 (or a compatible fork) and [LegacyFox].
  45 Optionally, create a new [Firefox profile] for development.
  46
  47 Sometimes Firefox needs a restart after installing/upgrading the extension,
  48 otherwise it is possible to load the extension unpacked in `about:debugging`.
  49 This makes reloading fast and easy. An easy workflow is code, `gulp`, reload,
  50 test, repeat. (Use `gulp -t` to also run the unit tests.)
  51
  52 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
  53 [LegacyFox]: https://git.gir.st/LegacyFox.git
  54
  55
  56 ## Gulp tasks
  57
  58 [gulp] is a task runner, which is used to automate most VimFx tasks.
  59
  60 The tasks are defined in [gulpfile.coffee]. They are summarized in the following
  61 sub-sections.
  62
  63 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
  64 internally by other tasks.)
  65
  66 [gulpfile.coffee]: ../gulpfile.coffee
  67
  68 ### Building
  69
  70 - `gulp build` creates the `build/` directory. It is basically a copy of the
  71   `extension/` directory, except some of the files have been compiled. For
  72   example, the .coffee files are compiled to .js.
  73
  74 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
  75   `build/VimFx.xpi` (an .xpi file is a renamed .zip file).
  76
  77 - Use the `--test` or `-t` option to include the unit test files into the build.
  78   The output of the tests are `console.log`ed. Use the [browser console], or
  79   start Firefox from the terminal to see it.
  80
  81 - Use the `--unlisted` or `-u` option to append `-unlisted` to the extension ID.
  82   This is used when adding .xpi files to github releases.
  83
  84 - `gulp clean` removes the `build/` directory.
  85
  86 [browser console]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Console
  87
  88 ### Management
  89
  90 - `gulp lint` lints all .coffee files. There’s also `npm run addons-linter` to
  91   run [`addons-linter`] on a freshly built VimFx .xpi.
  92
  93 - `gulp sloc` prints comment and source code line counts.
  94
  95 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
  96   section below for more information.
  97
  98 [`addons-linter`]: https://github.com/mozilla/addons-linter/
  99 [sync-locales]: #syncing-locales
 100
 101 ### Helpers
 102
 103 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
 104   lot and wish it ran faster, just tell it and it will! You’ll have to remember
 105   to re-run `gulp faster` whenever `gulpfile.coffee` is updated, though.
 106
 107 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts help dialog into
 108   `help.html`. You can then open up `help.html` in Firefox and style it live
 109   using the Style Editor! You can even press the “Save” button when done to save
 110   your changes!
 111
 112 - `gulp hints.html` is like `gulp help.html` but for styling hint markers.
 113
 114
 115 ## Syncing locales
 116
 117 This is usually not done by translators, but by developers who change, add or
 118 remove features that involves localized text.
 119
 120 If you add, remove or reorder translations in a file, do so in _one_ of the
 121 locales (one that is easy for you to test—but always write new translations in
 122 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
 123 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
 124 That rewrites all other locales so that:
 125
 126 - Old translations are removed.
 127 - New translations are added (in English).
 128 - All translations appear in the same order.
 129
 130 If you modify an existing translation in a file and want to update all other
 131 locales to use the new wording, add `UPDATE_ALL` at the end of it. `gulp
 132 sync-locales` will then use that translation in _all_ locales, replacing what
 133 was there before. It also removes `UPDATE_ALL` for you. However, if possible,
 134 edit all other locales by hand to save as much translated text as possible.
 135
 136 Note that `gulp sync-locales` requires every translation to be in a single line.
 137 In other words, do not line-wrap translations. Also don’t bother adding comments
 138 when translating locale files, since they will be removed by `gulp
 139 sync-locales`.
 140
 141 If you run `gulp sync-locales` with “en-US” as the base locale, a report is
 142 printed telling how complete all other locales are. Add `--sv-SE?` (note the
 143 question mark) to restrict the report to the “sv-SE” locale (you can of course
 144 substitute with any other locale). In that case, every line (including line
 145 number) that don’t differ compared to “en-US” is also be printed.
 146
 147
 148 ## Making a release
 149
 150 Before making a release, it might be wise to:
 151
 152 - Run `npm update` and/or `npm outdated` to see if there are any updates to
 153   dependencies. Investigate what’s new and test!
 154 - Run `gulp sync-locales` to make sure that no translation has been left behind.
 155 - Run `gulp lint` and `npm run addons-linter` to catch potential problems.
 156 - Run `gulp --test` to make sure the tests pass.
 157 - Inspect the `build/` directory to see that nothing strange has been included
 158   or generated by `gulp build`.
 159
 160 Run `./release` with argument `minor` or `patch`, which does the following for you:
 161
 162   - Updates the version in `package.json`.
 163   - Adds a heading with the new version number and today’s date at the top of
 164     `CHANGELOG.md`.
 165   - Commits `CHANGELOG.md` and `package.json`.
 166   - Tags the commit.
 167   - Lints the code and builds an xpi.
 168   - Opens the browser to help make a “release” out of the new tag on github,
 169     and attach an .xpi to it.