CONTRIBUTING.md

   1 # Contributing
   2
   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.
   5
   6 ## Reporting issues
   7
   8 First off, write in English!
   9
  10 Secondly, search both open and closed issues, to avoid duplicates.
  11
  12 Include this in bug reports:
  13
  14 - VimFx version, Firefox version, keyboard layout and operating system.
  15 - Steps to reproduce.
  16 - Whether the bug is a regression or not (if you know). Bonus points for
  17   telling since when the bug appeared.
  18
  19 If you’re suggesting a new feature always state your use case. Try to do it
  20 both in general and with a really specific example.
  21
  22 Lastly, don’t hesitate to open issues!
  23
  24
  25 ## Localizing
  26
  27 Contribute your localization! Copy the extension/locale/en-US directory and go
  28 wild!
  29
  30
  31 ## Developing
  32
  33 ### Versioning and branches
  34
  35 VimFx uses three numbers to describe its version: x.y.z, or major.minor.patch.
  36 However, in reality it is more like 0.y.z. The first number (major) won’t
  37 change until we feel that we don’t have any major changes coming. So until then
  38 it is only worth describing the two other numbers.
  39
  40 The middle number (minor) is incremented when a release contains new features,
  41 major refactors or changes to defaults. The idea is that when a user installs a
  42 new minor release, they should expect changes that they need to get familiar
  43 with.
  44
  45 The last number (patch) is incremented when a release contains only (simple)
  46 bugfixes, new localizations and updates to localizations. If a user installs a
  47 new patch release they shouldn’t have to get familiar with anything. Things
  48 should be like they were before, just a little better.
  49
  50 VimFx uses two branches: **master** and **develop**. master is the latest
  51 stable version plus trivial bugfixes. develop is the next minor version. master
  52 is merged into develop when needed, and develop is merged into master before it
  53 is going to be released.
  54
  55 In short, “backwards-incomptaible” changes and new features go into the develop
  56 branch, while most other things go into the master branch.
  57
  58 ### Pull requests
  59
  60 Create a new topic branch, based on either master or develop. See above.
  61
  62     git checkout -b myTopicBranch master
  63     # or
  64     git checkout -b myTopicBranch develop
  65
  66 Code! Try to follow the following simple rules:
  67
  68 - Always use parenthesis when calling functions.
  69 - Always use explicit `return`s, unless the function is a one-liner.
  70 - Always use single quotes, unless you use interpolation.
  71 - Prefer interpolation over concatenation, both in strings and in regexes.
  72 - Always use the following forms (not any aliases):
  73   - `true` and `false`
  74   - `==` and `!=`
  75   - `and` and `or`
  76   - `not`
  77 - Put spaces inside `[]` and `{}` when destructuring and interpolating, but not
  78   in array and object literals.
  79 - Comment when necessary. Comments should be full sentences.
  80 - Try to keep lines at most 80 characters long.
  81 - Indent using two spaces.
  82
  83 Please lint your code. See below.
  84
  85 Run the tests and make sure that all pass. See below. Add tests if possible.
  86
  87 Break up your pull request in several commits if necessary. The first line of
  88 commit messages should be a short summary. Add a blank line and then a nicely
  89 formatted markdown description after it if needed.
  90
  91 Finally send a pull request to same branch as you based your topic branch on
  92 (master or develop).
  93
  94 ### Building VimFx
  95
  96 1. Install [Node.js].
  97 2. Run `npm install` to download dependencies and development dependencies.
  98 3. Run `npm install -g gulp` to be able to run [`gulp`][gulp] commands.
  99    (Alternatively, you may use `./node_modules/.bin/gulp`.)
 100 4. Create a new Firefox profile for development.
 101 5. Install the [Extension Auto-Installer] add-on in your development profile.
 102
 103 - `gulp build` creates the `build/` directory. It is basically a copy of the
 104   `extension/` directory, with the .coffee files compiled to .js.
 105 - `gulp xpi` zips up the `build/` directory into `build/VimFx.xpi`.
 106 - `gulp push` (or just `gulp`) pushes `build/VimFx.xpi` to
 107   `http://localhost:8888`, which causes the Extension Auto-Installer to
 108   automatically install it. (No need to restart Firefox.)
 109 - `gulp clean` removes the `build/` directory.
 110 - `gulp lint` lints your code.
 111 - Use the `--test` or `-t` option to include the unit test files. The output of
 112   the tests are `console.log`ed. See the browser console, or start Firefox from
 113   the command line to see it.
 114
 115 An easy workflow is code, `gulp`, test, repeat. (Use `gulp -t` to also run the
 116 unit tests.)
 117
 118 [Node.js]: http://nodejs.org/
 119 [gulp]: https://github.com/gulpjs/gulp
 120 [Extension Auto-Installer]: https://addons.mozilla.org/firefox/addon/autoinstaller
 121
 122 ### Making a release
 123
 124 1. Add a list of changes since the last version at the top of CHANGELOG.md.
 125 2. Update the version in package.json (see above about versioning), and, if
 126    needed, the min and max Firefox versions.
 127 3. Run `gulp release`, which does the following for you:
 128   - Adds a heading with the new version number and today’s date at the top of
 129     CHANGELOG.md.
 130   - Commits CHANGELOG.md and package.json.
 131   - Tags the commit.
 132 4. Run `gulp xpi` to rebuild with the new version number.
 133 5. Push to github. Don’t forget to push the tag!
 134 6. Make a “release” out of the new tag on github, and attach VimFx.xpi to it.
 135 7. Publish on addons.mozilla.org. Add the release notes list as HTML.