geordi 3.2.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e775f88b224275cf01077937ba959b27666c1ae7ac18b58548a62bfa31161a12
-  data.tar.gz: 4e0efdb89bbf65b69a9753e8e05978b094915b613b1ded6ef1c1ea4716be0ea7
+  metadata.gz: 7c5a8befcc3bb1f14b4bd0803491b56ccb7db92daf47aa45eb73f359988ab768
+  data.tar.gz: 244b132d249d3e0d0d851ad79bae5890736e52f202a7bb2bf0c80b3a6d821195
 SHA512:
-  metadata.gz: 56146e32a18966efbe63a58074d158b888410cf19520150d175f3220be709820b7b05ed6f95df5f80993ed163ba9b59232f1d1f67c3bd43d2055e9b2d66cd812
-  data.tar.gz: e8e41bb61713a5f32dd4039cadee5b11a9f08bac20cad738e61975ea741bfd76cdf5e2d64a166579e701eda472f95f4f8ce15da27181fa0a8b11b748f5d222d3
+  metadata.gz: 3f57ac5bb0f1e804e2d53ab30e0b5c3742835eabfd5d58755dd4a06b55d5065bc0f3fa7b4d00bca9b4f72ae2329042339203ced4336830c534585e684241570c
+  data.tar.gz: 52c77c467efc9ecf3fc8f26dc713b38d26e79977a55604921ffe62b1f2808562e9f770d0c11ba59045f595df54d07c3a91b8b926361ae00e0330625bc3418c75

data/.ruby-version

@@ -1 +1 @@
-2.0.0
+2.5

data/.travis.yml

@@ -8,12 +8,17 @@ rvm:
   - '2.4.10'
   - '2.5.8'
   - '2.6.6'
+  - '2.7.1'
 
 gemfile:
   - 'Gemfile'
 
 dist: trusty
 
+before_install:
+  - sudo apt-get install -y vnc4server
+  # Fake required password for vncserver
+  - mkdir ~/.vnc && touch ~/.vnc/passwd && chmod 700 ~/.vnc/passwd
 install:
   - gem install bundler:1.17.3
   # Replace default Travis CI bundler script with a version that doesn't

data/CHANGELOG.md

@@ -4,13 +4,81 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-
 ## Unreleased
 
 ### Compatible changes
 ### Breaking changes
 
 
+## 4.2.0 2020-10-02
+
+### Compatible changes
+* Add `auto_update_chromedriver` as global setting option to automatically update chromedriver before cucumber 
+  tests, if Chrome and chromedriver versions don't match.
+* Dump command: Add support for multiple databases (#103 by @kajatiger)
+* Add Ruby 2.7 to list of supported Ruby versions
+* Fix #115: `geordi cucumber --modified` command, that corrupted filenames like:
+  ```
+  No such file or directory tures/pages.feature
+  ```
+* Avoid writing an instance of HighLine::String to Geordi config files (closes #114)
+
+
+## 4.1.1 2020-08-28
+### Compatible changes
+
+* Fixed: System calls are not executed properly if no bin stub is present. This resulted in errors like:
+
+  ```
+  % geordi rspec
+
+  # Running specs
+  > All specs at once (using parallel_tests)
+
+  x Specs failed.
+  ```
+
+  or
+
+  ```
+  % geordi migrate
+
+  # Migrating
+  > Development and parallel test databases
+
+  x Something went wrong.
+  ```
+
+
+## 4.1.0 2020-08-18
+
+### Compatible changes
+
+- Added dumple option `--compress` to compress after dumping
+
+## 4.0.1 2020-08-11
+
+### Compatible changes
+
+- Fix `geordi migrate` command, that fails with:
+
+```
+Don't know how to build task 'db:migrate parallel:prepare'
+```
+
+
+## 4.0.0 2020-07-30
+
+### Compatible changes
+- Improved documentation; README now includes command options.
+- Fix #90: `geordi console`, `geordi deploy`, `geordi rake` and `geordi shell` now work correctly if the project hasn't been bundled before
+
+### Breaking changes
+- Removed deprecated executables
+- Removed `eurest` command
+- Respect binstubs if available, otherwise fallback to geordi's previous behaviour. Note that this might cause failures, when your binstubs are not working. Please have a look at #109 for how a failure might look like and how you can fix it.
+
+
 ## 3.2.0 2020-07-15
 
 ### Compatible changes

data/Gemfile

@@ -3,7 +3,8 @@ source 'http://rubygems.org'
 # Specify your gem's dependencies in geordi.gemspec
 gemspec
 
-gem 'aruba'
+gem 'aruba', '< 1' # Drops support for Ruby 2.2-
+gem 'rake', '< 13' # Drops support for Ruby 2.1
 gem 'rspec-mocks'
 gem 'highline'
 gem 'parallel_tests'

data/Gemfile.lock

@@ -1,76 +1,93 @@
 PATH
   remote: .
   specs:
-    geordi (3.2.0)
+    geordi (4.1.1)
       thor (~> 1)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.3.8)
-    aruba (0.6.2)
-      childprocess (>= 0.3.6)
-      cucumber (>= 1.1.1)
-      rspec-expectations (>= 2.7.0)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    aruba (0.14.14)
+      childprocess (>= 0.6.3, < 4.0.0)
+      contracts (~> 0.9)
+      cucumber (>= 1.3.19)
+      ffi (~> 1.9)
+      rspec-expectations (>= 2.99)
+      thor (>= 0.19, < 2.0)
     axiom-types (0.1.1)
       descendants_tracker (~> 0.0.4)
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
-    builder (3.2.3)
+    backports (3.18.2)
+    builder (3.2.4)
     childprocess (1.0.1)
       rake (< 13.0)
-    coderay (1.1.2)
+    coderay (1.1.3)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    cucumber (1.3.20)
+    contracts (0.16.0)
+    cucumber (3.0.0)
       builder (>= 2.1.2)
-      diff-lcs (>= 1.1.3)
-      gherkin (~> 2.12)
+      cucumber-core (~> 3.0.0)
+      cucumber-expressions (~> 4.0.3)
+      cucumber-wire (~> 0.0.1)
+      diff-lcs (~> 1.3)
+      gherkin (~> 4.0)
       multi_json (>= 1.7.5, < 2.0)
       multi_test (>= 0.1.2)
+    cucumber-core (3.0.0)
+      backports (>= 3.8.0)
+      cucumber-tag_expressions (>= 1.0.1)
+      gherkin (>= 4.1.3)
+    cucumber-expressions (4.0.4)
+    cucumber-tag_expressions (2.0.2)
+    cucumber-wire (0.0.1)
     declarative (0.0.10)
     declarative-option (0.1.0)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
-    diff-lcs (1.2.5)
+    diff-lcs (1.4.4)
     equalizer (0.0.11)
-    excon (0.73.0)
+    excon (0.76.0)
     faraday (0.17.3)
       multipart-post (>= 1.2, < 3)
     faraday_middleware (0.14.0)
       faraday (>= 0.7.4, < 1.0)
-    gherkin (2.12.2)
-      multi_json (~> 1.3)
-    highline (1.6.21)
+    ffi (1.12.2)
+    gherkin (4.1.3)
+    highline (2.0.3)
     ice_nine (0.11.2)
     launchy (2.4.3)
       addressable (~> 2.3)
     method_source (1.0.0)
-    mimemagic (0.3.4)
-    multi_json (1.13.1)
+    mimemagic (0.3.5)
+    multi_json (1.15.0)
     multi_test (0.1.2)
     multipart-post (2.1.1)
-    parallel (0.5.16)
-    parallel_tests (0.6.18)
+    parallel (1.13.0)
+    parallel_tests (2.23.0)
       parallel
     pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rake (10.5.0)
+    public_suffix (2.0.5)
+    rake (12.3.3)
     representable (3.0.4)
       declarative (< 0.1.0)
       declarative-option (< 0.2.0)
       uber (< 0.2.0)
-    rspec-expectations (3.4.0)
+    rspec-expectations (3.9.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.4.0)
-    rspec-mocks (3.4.1)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.4.0)
-    rspec-support (3.4.1)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
     thor (1.0.1)
     thread_safe (0.3.6)
-    tracker_api (1.10.0)
+    tracker_api (1.11.0)
       addressable
       equalizer
       excon
@@ -91,12 +108,13 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  aruba
+  aruba (< 1)
   geordi!
   highline
   launchy
   parallel_tests
   pry
+  rake (< 13)
   rspec-mocks
   tracker_api
 

data/README.md

@@ -19,96 +19,96 @@ You may abbreviate commands by typing only their first letters, e.g. `geordi
 con` will boot a development console, `geordi set -t` will setup a project and
 run tests afterwards.
 
-For details on commands, e.g. supported options, you may always run
-`geordi help <command>`.
+You can always run `geordi help <command>` to quickly look up command help.
 
 ### `geordi apache-site VIRTUAL_HOST`
-
 Enable the given virtual host, disabling all others.
 
 
 ### `geordi capistrano COMMAND`
-
 Run a capistrano command on all deploy targets.
 
 Example: `geordi capistrano deploy`
 
 
 ### `geordi chromedriver-update`
-
 Update the chromedriver.
 
 Example: `geordi chromedriver_update`
 
-This command will find and install the matching chromedriver for the currently installed Chrome.
+This command will find and install the matching chromedriver for the currently
+installed Chrome.
 
+Setting `auto_update_chromedriver` to `true` in your global Geordi config file 
+(`~/.config/geordi/global.yml`), will automatically update chromedriver before 
+cucumber tests, in case Chrome and chromedriver versions don't match
 
-### `geordi clean`
+**Options**
+- `[--quiet-if-matching], [--no-quiet-if-matching]`: Suppress notification if chromedriver and chrome versions match
 
+
+### `geordi clean`
 Remove unneeded files from the current directory.
 
 
 ### `geordi commit`
-
 Commit using a story title from Pivotal Tracker.
 
 Example: `geordi commit`
 
 Any extra arguments are forwarded to `git commit -m <message>`.
 
-If there are no staged changes, prints a warning but will continue to create
-an empty commit.
-
 On the first execution we ask for your Pivotal Tracker API token. It will be
 stored in `~/.config/geordi/global.yml`.
 
 
 ### `geordi console [TARGET]`
-
 Open a Rails console locally or on a Capistrano deploy target.
 
-Open a local Rails console: `geordi console`
-
-Open a Rails console on `staging`: `geordi console staging`
-
-Lets you select the server to connect to from a menu when called with `--select-server` or the alias `-s`:
+Local (development): `geordi console`
 
-    geordi console staging -s
+Remote: `geordi console staging`
 
-If you already know the number of the server you want to connect to, just pass it along:
+Selecting the server: `geordi console staging -s` shows a menu with all available
+servers. When passed a number, directly connects to the selected server.
 
-    geordi console staging -s2
+**Options**
+- `-s, [--select-server=[SERVER_NUMBER]]`: Select a server to connect to
 
 
 ### `geordi cucumber [FILES and OPTIONS]`
-
 Run Cucumber features.
 
 Example: `geordi cucumber features/authentication_feature:3`
 
-Runs Cucumber as you want: with `bundle exec`, using parallel tests, with
-a VNC session holding Selenium test browsers, support for using a dedicated
-testing firefox and beta support for rerunning failed scenarios.
+Runs Cucumber with `bundle exec`, using parallel tests, with a VNC session
+holding Selenium test browsers, support for using a dedicated testing browser
+and beta support for re-running failed scenarios.
 
 - *@solo:* Generally, features are run in parallel. However, scenarios tagged
-with @solo are excluded and will be run sequentially, _after_ the parallel run.
+with @solo are excluded from the parallel run and executed sequentially instead.
 
-- *Debugging:* Sometimes, the dot-printing Cucumber formatter does not show
-errors. In case a feature fails without a message, try running it with `--debug`
-or `-d`.
+- *Debugging:* In some cases, the dot-printing Cucumber formatter swallows
+errors. In case a feature fails without an error message, try running it with
+`--debug` or `-d`.
 
 - *Options:* Any unknown option will be passed through to Cucumber,
-e.g. `--format pretty`.
+e.g. `--format=pretty`. Make sure to connect option and value with an equals
+sign, i.e. have each option a contiguous string.
 
 - *VNC:* By default, test browsers will run in a VNC session. When using a
-headless test browser anyway, you can disable VNC by putting the following
-config into `.geordi.yml` in the project root:
+headless test browser anyway, you can disable VNC by setting `use_vnc: false`
+in `.geordi.yml` in the project root.
 
-    use_vnc: false
+**Options**
+- `-m, [--modified], [--no-modified]`: Run all modified features
+- `-c, [--containing=STRING]`: Run all features that contain STRING
+- `-v, [--verbose], [--no-verbose]`: Show the test run command
+- `-d, [--debug], [--no-debug]`: Run Cucumber with `-f pretty -b`, which helps hunting down bugs
+- `-r, [--rerun=N]`: Rerun features up to N times while failing
 
 
 ### `geordi delete-dumps [DIRECTORY]`
-
 Delete database dump files (*.dump).
 
 Example: `geordi delete_dumps` or `geordi delete_dumps ~/tmp/dumps`
@@ -121,7 +121,6 @@ Geordi will ask for confirmation before actually deleting files.
 
 
 ### `geordi deploy [STAGE]`
-
 Guided deployment across branches.
 
 Example: `geordi deploy` or `geordi deploy p[roduction]` or `geordi deploy --current-branch`
@@ -129,18 +128,18 @@ Example: `geordi deploy` or `geordi deploy p[roduction]` or `geordi deploy --cur
 Merge, push and deploy with a single command! **It always tells what it will do
 before it does it.** There are different scenarios where this command is handy:
 
-1) *Production deploy:* From the master branch, run `geordi deploy production`.
-   This will merge `master` to `production`, push and deploy to production.
+- *Production deploy:* From the master branch, run `geordi deploy production`.
+  This will merge `master` to `production`, push and deploy to production.
 
-2) *Feature branch deploy:* From a feature branch, run `geordi deploy staging`.
-   This will merge the feature branch to `master`, push and deploy to staging.
+- *Feature branch deploy:* From a feature branch, run `geordi deploy staging`.
+  This will merge the feature branch to `master`, push and deploy to staging.
 
-   To deploy a feature branch directly without merging, run
-   `geordi deploy --current-branch`. This feature depends on the environment
-   variable `DEPLOY_BRANCH` to be picked up in the respective deploy file.
+  To deploy a feature branch directly without merging, run
+  `geordi deploy --current-branch`. This feature depends on the environment
+  variable `DEPLOY_BRANCH` to be picked up in the respective deploy file.
 
-3) *Simple deploy:* If the source branch matches the target branch, merging will
-   be skipped.
+- *Simple deploy:* If the source branch matches the target branch, merging will
+  be skipped.
 
 Calling the command without arguments will infer the target stage from the
 current branch and fall back to master/staging.
@@ -153,9 +152,12 @@ When your project is running Capistrano 3, deployment will use `cap deploy`
 instead of `cap deploy:migrations`. You can force using `deploy` by passing the
 -M option: `geordi deploy -M staging`.
 
+**Options**
+- `-M, [--no-migrations], [--no-no-migrations]`: Run cap deploy instead of cap deploy:migrations
+- `-c, [--current-branch], [--no-current-branch]`: Set DEPLOY_BRANCH to the current branch during deploy
 
-### `geordi drop-databases`
 
+### `geordi drop-databases`
 Interactively delete local databases.
 
 Example: `geordi drop_databases`
@@ -165,61 +167,60 @@ and offer to delete them. Excluded are databases that are whitelisted. This come
 in handy when you're keeping your currently active projects in the whitelist files
 and perform regular housekeeping with Geordi.
 
-When called with `-P` or `-M` options, only handles Postgres resp. MySQL/MariaDB.
-
-When called with `--postgres <port or local socket>` or `--mysql <port or local socket>`,
-will instruct the underlying management commands to use those connection methods
-instead of the defaults. This is useful when running multiple installations.
-
 Geordi will ask for confirmation before actually dropping databases and will
 offer to edit the whitelist instead.
 
+**Options**
+- `-P, [--postgres-only], [--no-postgres-only]`: Only clean Postgres
+- `-M, [--mysql-only], [--no-mysql-only]`: Only clean MySQL/MariaDB
+- `[--postgres=PORT_OR_SOCKET]`: Use Postgres port or socket
+- `[--mysql=PORT_OR_SOCKET]`: Use MySQL/MariaDB port or socket
 
 ### `geordi dump [TARGET]`
+Handle (remote) database dumps.
 
-Handle dumps (see `geordi help dump` for details).
+If you are using multiple databases per environment, pass the database name like this:
 
-When called without arguments, dumps the development database with `dumple`.
+    geordi dump -d primary
 
-    geordi dump
+Loading a dump into one of multiple local databases is not supported yet.
 
 When called with the `--load` option, sources the specified dump into the
 development database.
 
-    geordi dump -l tmp/staging.dump
+`geordi dump` (without arguments) dumps the development database with `dumple`.
 
-When called with a capistrano deploy target (e.g. `staging`), remotely dumps
-the specified target's database and downloads it to `tmp/`.
+`geordi dump -l tmp/staging.dump` (with the `--load` option) sources the
+specified dump file into the development database.
 
-    geordi dump staging
+`geordi dump staging` (with a Capistrano deploy target) remotely dumps the
+specified target's database and downloads it to `tmp/`.
 
-When called with a capistrano deploy target and the `--load` option, sources the
-dump into the development database after downloading it.
+`geordi dump staging -l` (with a Capistrano deploy target and the `--load`
+option) sources the dump into the development database after downloading it.
 
-    geordi dump staging -l
+**Options**
+- `-l, [--load=[DUMP_FILE]]`: Load a dump
 
 
 ### `geordi firefox COMMAND`
-
 Run a command with VNC and test browser set up (alias: chrome).
 
 Example: `geordi firefox b cucumber` or `geordi firefox --setup 24.0`
 
 Useful when you need Firefox for Selenium or the VNC set up, but can't use the
-`geordi cucumber` command.
-
-*Install* a special Firefox by calling with `--setup <version>`.
+`geordi cucumber` command. This command is aliased `chrome` for users running
+Selenium in Chrome.
 
-This command is aliased `chrome` for users running Selenium in Chrome.
+**Options**
+- `[--setup=FIREFOX_VERSION]`: Install a special test runner Firefox with the given version
 
 
 ### `geordi help [COMMAND]`
-
 Describe available commands or one specific command.
 
 
 ### `geordi migrate`
-
 Migrate all databases.
 
 Example: `geordi migrate`
@@ -230,7 +231,6 @@ with `db:migrate`.
 
 
 ### `geordi png-optimize PATH`
-
 Optimize .png files.
 
 Example: `geordi png-optimize some/directory`
@@ -241,7 +241,6 @@ Example: `geordi png-optimize some/directory`
 
 
 ### `geordi rake TASK`
-
 Run a rake task in several Rails environments.
 
 Example: `geordi rake db:migrate`
@@ -254,59 +253,56 @@ Example: `geordi rake db:migrate`
 
 
 ### `geordi remove-executable-flags`
-
 Remove executable-flags from files that should not be executable.
 
 
 ### `geordi rspec [FILES]`
-
 Run RSpec.
 
 Example: `geordi rspec spec/models/user_spec.rb:13`
 
-Runs RSpec as you want: with RSpec 1/2 detection, `bundle exec`, rspec_spinner
-detection, etc.
+Runs RSpec with RSpec 1/2 support, parallel_tests detection and `bundle exec`.
 
 
 ### `geordi security-update [STEP]`
-
 Support for performing security updates.
 
-Preparation for security update: `geordi security-update`
-
-Checks out production and pulls.
+Preparation for security update: `geordi security-update`. Checks out production
+and pulls.
 
-After performing the update: `geordi security-update finish`
+After performing the update: `geordi security-update finish`. Switches branches,
+pulls, pushes and deploys as required by our workflow.
 
-Switches branches, pulls, pushes and deploys as required by our workflow. Tells
-what it will do before it does it. In detail:
+This command tells what it will do before it does it. In detail:
 
-1. Asks user, if tests are green
+1. Ask user if tests are green
 
-2. Pushes production
+2. Push production
 
-3. Checks out master and pulls
+3. Check out master and pull
 
-4. Merges production and pushes in master
+4. Merge production and push in master
 
-5. Deploys staging first, if there is a staging environment
+5. Deploy staging, if there is a staging environment
 
-6. Asks user, if deployment log is okay and application is still running on staging
+6. Ask user if deployment log is okay and staging application is still running
 
-7. Deploys other stages
+7. Deploy other stages
 
-8. Asks user, if deployment log is okay and application is still running on all other stages
+8. Ask user if deployment log is okay and application is still running on all stages
 
-9. Informs user about the next steps
+9. Inform user about the next (manual) steps
 
 
 ### `geordi server [PORT]`
-
 Start a development server.
 
+**Options**
+- `-p, [--port=PORT]`: Choose a port
+- `-P, [--public], [--no-public]`: Make the server accessible from the local network
 
-### `geordi setup`
 
+### `geordi setup`
 Setup a project for the first time.
 
 Example: `geordi setup`
@@ -315,71 +311,51 @@ Check out a repository and cd into its directory. Then let `setup` do the tiring
 work: run `bundle install`, create `database.yml`, create databases, migrate
 (all if applicable).
 
-If a local bin/setup file is found, Geordi skips these steps runs bin/setup
-for setup instead.
-
-After setting up, loads a remote database dump into the development db when
-called with the `--dump` option:
+If a local bin/setup file is found, Geordi skips its routine and runs bin/setup
+instead.
 
-    geordi setup -d staging
-
-After setting up, runs all tests when called with the `--test` option:
-
-    geordi setup -t
+**Options**
+- `-d, [--dump=TARGET]`: After setup, dump the TARGET db and source it into the development db
+- `-t, [--test], [--no-test]`: After setup, run tests
 
 
 ### `geordi shell TARGET`
-
 Open a shell on a Capistrano deploy target.
 
 Example: `geordi shell production`
 
-Lets you select the server to connect to from a menu when called with `--select-server` or the alias `-s`:
+Selecting the server: `geordi shell staging -s` shows a menu with all available
+servers. When passed a number, directly connects to the selected server.
 
-    geordi shell production -s
-
-If you already know the number of the server you want to connect to, just pass it along:
-
-    geordi shell production -s2
+**Options**
+- `-s, [--select-server=[SERVER_NUMBER]]`: Select a server to connect to
 
 
 ### `geordi tests`
-
 Run all employed tests.
 
 
 ### `geordi unit`
-
 Run Test::Unit.
 
 
 ### `geordi update`
-
 Bring a project up to date.
 
 Example: `geordi update`
 
 Performs: `git pull`, `bundle install` (if necessary) and migrates (if applicable).
 
-After updating, loads a dump into the development db when called with the
-`--dump` option:
-
-    geordi update -d staging
-
-After updating, runs all tests when called with the `--test` option:
-
-    geordi update -t
-
-See `geordi help update` for details.
+**Options**
+- `-d, [--dump=TARGET]`: After updating, dump the TARGET db and source it into the development db
+- `-t, [--test], [--no-test]`: After updating, run tests
 
 
 ### `geordi version`
-
 Print the current version of geordi.
 
 
 ### `geordi vnc`
-
 Show the hidden VNC window.
 
 Example: `geordi vnc` or `geordi vnc --setup`
@@ -387,8 +363,8 @@ Example: `geordi vnc` or `geordi vnc --setup`
 Launch a VNC session to the hidden screen where `geordi cucumber` runs Selenium
 tests.
 
-When called with `--setup`, will guide through the setup of VNC.
-
+**Options**
+- `[--setup], [--no-setup]`: Guide through the setup of VNC
 
 b
 ---
@@ -398,7 +374,7 @@ working directory. If no `Gemfile` is present just runs the given command:
 
     b spec spec/models
 
-More information at http://makandracards.com/makandra/684-automatically-run-bundle-exec-if-required
+See http://makandracards.com/makandra/684-automatically-run-bundle-exec-if-required
 
 
 dumple
@@ -408,7 +384,7 @@ Stores a timestamped database dump for the given Rails environment in `~/dumps`:
 
     dumple development
 
-More information at http://makandracards.com/makandra/1008-dump-your-database-with-dumple
+See http://makandracards.com/makandra/1008-dump-your-database-with-dumple
 
 
 launchy_browser
@@ -421,21 +397,37 @@ browser, as opposed to opening it within the VNC window.
 Contributing
 ============
 
-* Run the tests for the oldest supported ruby version with `bundle exec rake`. Ensure that all other ruby versions in the `travis.yml` pass as well after pushing your feature branch and triggering the travis build.
-* Update this `README`. The whole `geordi` section is auto-generated
-  by `rake readme`.
-* Document your changes in the `CHANGELOG.md` file.
+When making changes to Geordi, please make sure your code is tested. Not all,
+but most features of Geordi can be tested. See other tests for inspiration.
+
+Once you have completed your modifications, please update CHANGELOG and README
+as needed. Use `rake readme` to regenerate the Geordi section of the README from
+the command documentations.
+
+Make sure tests are green in the default Ruby *plus* in the oldest Ruby > 1.8
+that you have installed on your system (1.8.7 support has been dropped).
+
+Before releasing your changes, wait for the Travis results to see that tests
+passed in all Ruby versions.
+
 
 Adding a new command
 ---------------
 
 Copy `lib/geordi/COMMAND_TEMPLATE` to `lib/geordi/commands/your_command` and
-edit it to do what you need it to do. Usually, it is hard to automatedly test
-Geordi commands, so make sure you've manually tested it. You can do so by
-calling your local geordi like so (adjust paths to your needs):
-
-    # @option -I: add directory to load path
-    ruby -I ../geordi/lib ../geordi/bin/geordi <command>
-    
-    # with debugger
-    ruby -r byebug -I ../geordi/lib ../geordi/bin/geordi <command>
+edit it to do what you need it to do. Please add a feature test for the new
+command; see features/ for inspiration.
+
+To try Geordi locally, call it like this:
+
+    # -I means "add the following directory to load path"
+    ruby -Ilib exe/geordi
+
+    # From another directory
+    ruby -I ../geordi/lib ../geordi/exe/geordi
+
+    # With debugger
+    ruby -r byebug -I ../geordi/lib ../geordi/exe/geordi
+
+You can also *install* Geordi locally from its project directory with
+`rake install`. Make sure to switch to the expected Ruby version before.