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 ### Development
  47
  48 1. Create a new [Firefox profile] for development.
  49
  50 2. Install the [Extension Auto-Installer] add-on in your development profile.
  51
  52 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
  53 unit tests.)
  54
  55 If you’re having problems, don’t forget to try `npm update`. Your problem might
  56 be in a dependency and already have been fixed.
  57
  58 [Firefox Profile]: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles
  59 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
  60
  61
  62 ## Gulp tasks
  63
  64 [gulp] is the task runner used to automate most of the common VimFx tasks.
  65
  66 The tasks are defined in [gulpfile.coffee]. They are summarized in the follwing
  67 sub-sections.
  68
  69 (There are a few more tasks defined in [gulpfile.coffee], but they are only used
  70 internally by other tasks.)
  71
  72 [gulpfile.coffee]: ../gulpfile.coffee
  73
  74 ### Building
  75
  76 - `gulp build` creates the `build/` directory. It is basically a copy of the
  77   `extension/` directory, with some of the files being compiled. For example,
  78   the `.coffee` files compiled to `.js`.
  79
  80 - `gulp xpi` runs `gulp build` and then zips the `build/` directory into
  81   `build/VimFx.xpi`.
  82
  83 - `gulp push` (or just `gulp`) runs `gulp xpi` and then pushes `build/VimFx.xpi`
  84   to `http://localhost:8888`, which causes the [Extension Auto-Installer] to
  85   automatically install it. (No need to restart Firefox.)
  86
  87 - Use the `--test` or `-t` option to include the unit test files. The output of
  88   the tests are `console.log`ed. See the browser console, or start Firefox from
  89   the command line to see it.
  90
  91 - `gulp clean` removes the `build/` directory.
  92
  93 ### Management
  94
  95 - `gulp lint` lints all `.coffee` files.
  96
  97 - `gulp sloc` prints comment and source code line counts.
  98
  99 - `gulp sync-locales` syncs locales. See the [“Syncing locales”][sync-locales]
 100   section below for more information.
 101
 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 it whenever gulpfile.coffee is updated, though.
 109
 110 - `gulp help.html` dumps VimFx’s Keyboard Shortcuts dialog into `help.html`. You
 111   can then open up `help.html` in Firefox and style it live using the Style
 112   Editor! You can even press the “Save” button when done to save your changes!
 113
 114 ### Release
 115
 116 See the [“Making a release”][release] section below for more information.
 117
 118 - `gulp release` tags things with a new version number.
 119
 120 - `gulp changelog` prints changelog entries from `CHANGELOG.md` as HTML to
 121   stdout.
 122
 123 - `gulp readme` prints `README.md` as HTML to stdout.
 124
 125 Tip: Add `--silent` add the end of the gulp command to suppress gulp’s standard
 126 progress output, allowing to pipe stdout to the clipboard.
 127
 128 [release]: #making-a-release
 129
 130
 131 ## Syncing locales
 132
 133 This is usually not done by translators, but by developers who change, add or
 134 remove features that involves localized text.
 135
 136 If you add, remove or reorder translations in a file, do so in _one_ of the
 137 locales (one that is easy for you to test—but always write new translations in
 138 English!). If you modified the en-US locale, run `gulp sync-locales --en-US` (or
 139 just `gulp sync-locales`). Substitute “en-US” with a locale of choice if needed.
 140 That rewrites all other locales so that:
 141
 142 - Old translations are removed.
 143 - New translations are added (in English).
 144 - All translations appear in the same order.
 145
 146 If you modify an existing translation in a file and want to update all other
 147 locales to use the new wording:
 148
 149 - If possible, edit all other locales by hand to save as much translated text as
 150   possible.
 151
 152 - Otherwise:
 153
 154   1. Before modifying existing translations, copy the file in question and add
 155      the extension `.old` to the filename. For example, copy a
 156      `vimfx.properties` file to `vimfx.properties.old`.
 157   2. Make your modifications (in for example `vimfx.properties`, leaving
 158      `vimfx.properties.old` intact).
 159   3. Run `gulp sync-locales`. It does the same thing as before, except that if a
 160      translation has changed compared to an `.old`-file, the newly changed
 161      translation is used in all locales, replacing what was there before.
 162   4. Remove the `.old`-file.
 163
 164 Note that `gulp sync-locales` requires every translation to be in a single line.
 165 In other words, do not line-wrap translations. Also don’t bother adding comments
 166 when translating locale files, since they’ll likely be removed by `gulp
 167 sync-locales`.
 168
 169
 170 ## Making a release
 171
 172 Before making a release, it might be wise to:
 173
 174 - Run `npm update` and/or `npm outdated` to see if there are any updates to
 175   dependencies. Investigate what’s new and test!
 176 - Run `gulp sync-locales` to make sure that no translation has been left behind.
 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` (see `CONTRIBUTING-CODE.md` about
 185    versioning), the minimum Firefox version (if needed) and the maximum Firefox
 186    version (ideally to the 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. Push to github. Don’t forget to push the tag!
 198
 199 6. Make a “release” out of the new tag on github, and attach VimFx.xpi to it.
 200
 201 7. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
 202    changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
 203    prints the latest two (etc). The latter is useful if publishing a new version
 204    before the last published version had been reviewed; then the new version
 205    should contain both changelog entries.
 206
 207 The idea is to use the contents of `README.md` as the add-on descripton on
 208 addons.mozilla.org. You can print it as HTML by runnning `gulp readme`.
 209
 210 [valid Firefox versions]: https://addons.mozilla.org/en-US/firefox/pages/appversions/