3 **Just upgraded to version 0.6.0?** Be sure to checkout the
4 [changelog](CHANGELOG.md) to see what’s new, and what has changed.
8 _Please_ read the following four lines!
11 - Search for **duplicates**—also closed issues.
12 - Bugs: Include **VimFx version**, Firefox version, OS and keyboard layout.
13 Also, **did it use to work before?**
14 - Feature requests: Include a specific detailed **use case** example.
22 Contribute your localization! Copy the extension/locale/en-US directory and go
28 ### Versioning and branches
30 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
31 However, in reality it is more like 0.y.z. The first number (major) won’t
32 change until we feel that we don’t have any major changes coming. So until then
33 it is only worth describing the two other numbers.
35 The middle number (minor) is incremented when a release contains new features,
36 major refactors or changes to defaults. The idea is that when a user installs a
37 new minor release, they should expect changes that they need to get familiar
40 The last number (patch) is incremented when a release contains only (simple)
41 bugfixes, new localizations and updates to localizations. If a user installs a
42 new patch release they shouldn’t have to get familiar with anything. Things
43 should be like they were before, just a little better.
45 VimFx uses two branches: **master** and **develop**. master is the latest
46 stable version plus trivial bugfixes. develop is the next minor version. master
47 is merged into develop when needed, and develop is merged into master before it
48 is going to be released.
50 In short, “backwards-incomptaible” changes and new features go into the develop
51 branch, while most other things go into the master branch.
55 Create a new topic branch, based on either master or develop. See above.
57 git checkout -b myTopicBranch master
59 git checkout -b myTopicBranch develop
61 Code! Try to follow the following simple rules:
63 - Always use parenthesis when calling functions.
64 - Always use explicit `return`s, unless the function is a one-liner.
65 - Always use single quotes, unless you use interpolation.
66 - Prefer interpolation over concatenation, both in strings and in regexes.
67 - Always use the following forms (not any aliases):
72 - Put spaces inside `[]` and `{}` when destructuring and interpolating, but not
73 in array and object literals.
74 - Comment when necessary. Comments should be full sentences.
75 - Try to keep lines at most 80 characters long.
76 - Indent using two spaces.
78 Please lint your code. See below.
80 Run the tests and make sure that all pass. See below. Add tests if possible.
82 Break up your pull request in several commits if necessary. The first line of
83 commit messages should be a short summary. Add a blank line and then a nicely
84 formatted markdown description after it if needed.
86 Finally send a pull request to same branch as you based your topic branch on
92 2. Run `npm install` to download dependencies and development dependencies.
93 3. Run `npm install -g gulp` to be able to run [`gulp`][gulp] commands.
94 (Alternatively, you may use `./node_modules/.bin/gulp`.)
95 4. Create a new Firefox profile for development.
96 5. Install the [Extension Auto-Installer] add-on in your development profile.
98 - `gulp build` creates the `build/` directory. It is basically a copy of the
99 `extension/` directory, with the .coffee files compiled to .js.
100 - `gulp xpi` zips up the `build/` directory into `build/VimFx.xpi`.
101 - `gulp push` (or just `gulp`) pushes `build/VimFx.xpi` to
102 `http://localhost:8888`, which causes the Extension Auto-Installer to
103 automatically install it. (No need to restart Firefox.)
104 - `gulp clean` removes the `build/` directory.
105 - `gulp lint` lints your code.
106 - `gulp sync-locale` syncs all locales against the en-US locale. To sync against
107 for example the sv-SE locale instead, pass `--sv-SE` as an option. See also
108 the “Syncing locales” section below.
109 - Use the `--test` or `-t` option to include the unit test files. The output of
110 the tests are `console.log`ed. See the browser console, or start Firefox from
111 the command line to see it.
113 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
116 [Node.js]: http://nodejs.org/
117 [gulp]: https://github.com/gulpjs/gulp
118 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
122 This is usually not done by translators, but by developers who change, add or
123 remove features that involves localized text.
125 If you add, remove or reorder translations in a file, do so in _one_ of the
126 locales (one that is easy for you to test—but always write new translations in
127 English!). If you modified the en-US locale, run `gulp sync-locales` (or `gulp
128 sync-locales --en-US`—substitute “en-US” with a locale of choice if needed).
129 That rewrites all other locales so that:
131 - Old translations are removed.
132 - New translations are added (in English).
133 - All translations appear in the same order.
135 If you modify an existing translation in a file and want to update all other
136 locales to use the new wording:
138 - If possible, edit all other locales by hand to save as much translated text as
141 1. Before modifying existing translations, copy the file in question and add
142 the extension “.old” to the filename. For example, copy a
143 “vimfx.properties” file to “vimfx.properties.old”.
144 2. Make your modifications (in for example “vimfx.properties”, leaving
145 “vimfx.properties.old” intact).
146 3. Run `gulp sync-locales`. It does the same thing as before, except that if a
147 translation has changed compared to an “.old”-file, the newly changed
148 translation is used in all locales, replacing what was there before.
149 4. Remove the “.old”-file.
151 Note that `gulp sync-locales` requires every translation to be in a single line.
152 In other words, do not line-wrap translations. Also don’t bother adding comments
153 when translating locale files, since they’ll likely be removed by `gulp
159 1. Add a list of changes since the last version at the top of CHANGELOG.md.
160 2. Update the version in package.json (see above about versioning), and, if
161 needed, the min and max Firefox versions.
162 3. Run `gulp release`, which does the following for you:
163 - Adds a heading with the new version number and today’s date at the top of
165 - Commits CHANGELOG.md and package.json.
167 4. Run `gulp xpi` to rebuild with the new version number.
168 5. Push to github. Don’t forget to push the tag!
169 6. Make a “release” out of the new tag on github, and attach VimFx.xpi to it.
170 7. Publish on addons.mozilla.org. Add the release notes list as HTML.