CONTRIBUTING-CODE.md

   1 # Contributing code
   2
   3 ## Localizing
   4
   5 Contribute your localization! Copy the `extension/locale/en-US` directory and go
   6 wild!
   7
   8
   9 ## Developing
  10
  11 ### Versioning and branches
  12
  13 Currently, no more updates are planned for 0.5.x = master branch. **Please only
  14 contribute to the develop branch for now.** It contains quite a bit of backwards
  15 incomptaible improvements, and will be released as 0.6.0 as soon as it is ready.
  16 That will be the last “big” release. Then we’ll switch to a more rapid release
  17 cycle, detailed below.
  18
  19 #### Vision ####
  20
  21 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
  22 However, in reality it is more like 0.y.z. The first number (major) won’t
  23 change until we feel that we don’t have any major changes coming. So until then
  24 it is only worth describing the two other numbers.
  25
  26 The middle number (minor) is incremented when a release contains new features,
  27 major refactors or changes to defaults. The idea is that when a user installs a
  28 new minor release, they should expect changes that they need to get familiar
  29 with.
  30
  31 The last number (patch) is incremented when a release contains only (simple)
  32 bugfixes, new localizations and updates to localizations. If a user installs a
  33 new patch release they shouldn’t have to get familiar with anything. Things
  34 should be like they were before, just a little better.
  35
  36 VimFx uses two branches: **master** and **develop**. master is the latest
  37 stable version plus trivial bugfixes. develop is the next minor version. master
  38 is merged into develop when needed, and develop is merged into master before it
  39 is going to be released.
  40
  41 In short, “backwards-incomptaible” changes and new features go into the develop
  42 branch, while most other things go into the master branch.
  43
  44 ### Pull requests
  45
  46 Create a new topic branch, based on either master or develop. **Note:** For now,
  47 _always_ base it on **develop**.
  48
  49     git checkout -b myTopicBranch master
  50     # or
  51     git checkout -b myTopicBranch develop
  52
  53 Code! Try to follow the following simple rules:
  54
  55 - Always use parenthesis when calling functions.
  56 - Always use explicit `return`s, unless the function is a one-liner.
  57 - Always use single quotes, unless you use interpolation.
  58 - Prefer interpolation over concatenation, both in strings and in regexes.
  59 - Always use the following forms (not any aliases):
  60   - `true` and `false`
  61   - `==` and `!=`
  62   - `and` and `or`
  63   - `not`
  64 - Put spaces inside `[]` and `{}` when destructuring and interpolating, but not
  65   in array and object literals.
  66 - Comment when necessary. Comments should be full sentences.
  67 - Try to keep lines at most 80 characters long.
  68 - Indent using two spaces.
  69
  70 Please lint your code. See below.
  71
  72 Run the tests and make sure that all pass. See below. Add tests if possible.
  73
  74 Break up your pull request in several commits if necessary. The first line of
  75 commit messages should be a short summary. Add a blank line and then a nicely
  76 formatted markdown description after it if needed.
  77
  78 Finally send a pull request to same branch as you based your topic branch on
  79 (master or develop).
  80
  81 ### Building VimFx
  82
  83 1. Install [Node.js] or [io.js].
  84 2. Run `npm install` to download dependencies and development dependencies.
  85 3. Run `npm install -g gulp` to be able to run [`gulp`][gulp] commands.
  86    If you prefer not to install gulp globally, you can use `npm run gulp`
  87    instead. For example, to create an .xpi: `npm run gulp -- xpi`. (Note that
  88    you might need to update `npm` for this to run; try `npm update -g npm`.)
  89 4. Create a new Firefox profile for development.
  90 5. Install the [Extension Auto-Installer] add-on in your development profile.
  91
  92 - `gulp build` creates the `build/` directory. It is basically a copy of the
  93   `extension/` directory, with the .coffee files compiled to .js.
  94 - `gulp xpi` zips up the `build/` directory into `build/VimFx.xpi`.
  95 - `gulp push` (or just `gulp`) pushes `build/VimFx.xpi` to
  96   `http://localhost:8888`, which causes the Extension Auto-Installer to
  97   automatically install it. (No need to restart Firefox.)
  98 - `gulp clean` removes the `build/` directory.
  99 - `gulp lint` lints your code.
 100 - `gulp faster` compiles `gulpfile.coffee` to `gulpfile.js`. If you run `gulp` a
 101   lot and wish it ran faster, just tell it and it will! You’ll have to remember
 102   to re-run it whenever gulpfile.coffee is updated, though.
 103 - `gulp sync-locales` syncs all locales against the en-US locale. To sync against
 104   for example the sv-SE locale instead, pass `--sv-SE` as an option. See also
 105   the “Syncing locales” section below.
 106 - Use the `--test` or `-t` option to include the unit test files. The output of
 107   the tests are `console.log`ed. See the browser console, or start Firefox from
 108   the command line to see it.
 109
 110 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
 111 unit tests.)
 112
 113 If you’re having problems, don’t forget to try `npm update`. Your problem might
 114 be in a dependency and already have been fixed.
 115
 116 [Node.js]: http://nodejs.org/
 117 [io.js]: https://iojs.org/
 118 [gulp]: https://github.com/gulpjs/gulp
 119 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
 120
 121 ### Syncing locales
 122
 123 This is usually not done by translators, but by developers who change, add or
 124 remove features that involves localized text.
 125
 126 If you add, remove or reorder translations in a file, do so in _one_ of the
 127 locales (one that is easy for you to test—but always write new translations in
 128 English!). If you modified the en-US locale, run `gulp sync-locales` (or `gulp
 129 sync-locales --en-US`—substitute “en-US” with a locale of choice if needed).
 130 That rewrites all other locales so that:
 131
 132 - Old translations are removed.
 133 - New translations are added (in English).
 134 - All translations appear in the same order.
 135
 136 If you modify an existing translation in a file and want to update all other
 137 locales to use the new wording:
 138
 139 - If possible, edit all other locales by hand to save as much translated text as
 140   possible.
 141 - Otherwise:
 142   1. Before modifying existing translations, copy the file in question and add
 143      the extension “.old” to the filename. For example, copy a
 144      “vimfx.properties” file to “vimfx.properties.old”.
 145   2. Make your modifications (in for example “vimfx.properties”, leaving
 146      “vimfx.properties.old” intact).
 147   3. Run `gulp sync-locales`. It does the same thing as before, except that if a
 148      translation has changed compared to an “.old”-file, the newly changed
 149      translation is used in all locales, replacing what was there before.
 150   4. Remove the “.old”-file.
 151
 152 Note that `gulp sync-locales` requires every translation to be in a single line.
 153 In other words, do not line-wrap translations. Also don’t bother adding comments
 154 when translating locale files, since they’ll likely be removed by `gulp
 155 sync-locales`.
 156
 157
 158 ### Making a release
 159
 160 Before making a release, it might be wise to:
 161
 162 - Run `npm update` and/or `npm outdated` to see if there are any updates to
 163   dependencies. Investigate what’s new and test!
 164 - Run `gulp sync-locales` to make sure that no translation has been left behind.
 165 - Inspect the build/ directory to see that nothing strange has been included or
 166   generated by `gulp build`.
 167
 168 1. Add a list of changes since the last version at the top of CHANGELOG.md.
 169 2. Update the version in package.json (see above about versioning), and, if
 170    needed, the min and max Firefox versions.
 171 3. Run `gulp release`, which does the following for you:
 172   - Adds a heading with the new version number and today’s date at the top of
 173     CHANGELOG.md.
 174   - Commits CHANGELOG.md and package.json.
 175   - Tags the commit.
 176 4. Run `gulp xpi` to rebuild with the new version number.
 177 5. Push to github. Don’t forget to push the tag!
 178 6. Make a “release” out of the new tag on github, and attach VimFx.xpi to it.
 179 7. Publish on addons.mozilla.org. Add the release notes list as HTML. `gulp
 180    changelog` prints the latest changelog entry as HTML. `gulp changelog -2`
 181    prints the latest two (etc). The latter is useful if publishing a new version
 182    before the last published version has been reviewed; then the new version
 183    should contain both changelog entries.
 184
 185 The idea is to use the contents of the README as the add-on descripton on
 186 addons.mozilla.org. You can print it as HTML by runnning `gulp readme`.