README.md in gemika-0.3.4 vs README.md in gemika-0.4.0
- old
+ new
@@ -41,18 +41,18 @@
## Example directory structure
Below you can see the directory of a gem with a completed Gemika testing setup. The next section describes how to get there:
```shell
-gemfiles/Gemfile.set1 # First dependency set. Should include development dependencies and gemika.
-gemfiles/Gemfile.set1.lock # Generated by `rake matrix:install`
-gemfiles/Gemfile.set2 # Second dependency set. Should include development dependencies and gemika.
-gemfiles/Gemfile.set2.lock # Generated by `rake matrix:install`
-gemfiles/Gemfile.set3 # Third dependency set. Should include development dependencies and gemika.
-gemfiles/Gemfile.set3.lock # Generated by `rake matrix:install`
-Gemfile -> gemfiles/Gemfile.set2 # Symlink to default Gemfile for development
-Gemfile.lock -> gemfiles/Gemfile.set2.lock # Symlink to default Gemfile.lock for development
+Gemfile.set1 # First dependency set. Should include development dependencies and gemika.
+Gemfile.set1.lock # Generated by `rake matrix:install`
+Gemfile.set2 # Second dependency set. Should include development dependencies and gemika.
+Gemfile.set2.lock # Generated by `rake matrix:install`
+Gemfile.set3 # Third dependency set. Should include development dependencies and gemika.
+Gemfile.set3.lock # Generated by `rake matrix:install`
+Gemfile -> Gemfile.set2 # Symlink to default Gemfile for development
+Gemfile.lock -> Gemfile.set2.lock # Symlink to default Gemfile.lock for development
.ruby-version # Default Ruby version for development
.gitignore # Should ignore spec/support/database.yml
.travis.yml # Configures all tested Ruby / gemfile combinations, for both local development and Travis CI
my_gem.gemspec # Specification for your gem
Rakefile # Should require 'gemika/tasks'
@@ -134,26 +134,21 @@
```
### Define multiple dependency sets
We are now creating one `Gemfile` for each set of gems and database type you'd like to test again.
+Your gemfiles should be placed directly in your project's root directory.
-First, create a directory for the gemfiles:
+For each dependency set, create a `Gemfile` in the project root directory that contains:
-```shell
-mkdir gemfiles
-```
-
-For each dependency set, create a `Gemfile` in the `gemfiles` directory that contains:
-
1. The runtime dependencies you'd like to test against (e.g. Rails 5)
-2. The development dependencies for that set (e.g. `rspec`) in a version that is compatible with these runtime gependencies.
+2. The development dependencies for that set (e.g. `rspec`) in a version that is compatible with these runtime dependencies.
3. The `gemika` gem
-4. Your own gem from path `..`
-
-For instance, if one dependency set is Rails 3.2 with a MySQL database, we would create `gemfiles/Gemfile.4.2.mysql2` with these contents:
+4. Your own gem from path `.`
+For instance, if one dependency set is Rails 3.2 with a MySQL database, we would create `./Gemfile.4.2.mysql2` with these contents:
+
```ruby
source 'https://rubygems.org'
# Runtime dependencies
gem 'rails', '~>3.2.22'
@@ -164,14 +159,14 @@
gem 'rake'
gem 'byebug'
gem 'gemika'
# Gem under test
-gem 'my_gem', :path => '..'
+gem 'my_gem', :path => '.'
```
-If a second dependency is Rails 5.0 with a PostgreSQL database, we would create `gemfiles/Gemfile.5.0.pg` with these contents:
+If a second dependency is Rails 5.0 with a PostgreSQL database, we would create `./Gemfile.5.0.pg` with these contents:
```ruby
source 'https://rubygems.org'
# Runtime dependencies
@@ -183,41 +178,41 @@
gem 'rake'
gem 'byebug'
gem 'gemika'
# Gem under test
-gem 'my_gem', :path => '..'
+gem 'my_gem', :path => '.'
```
-In this example, your `gemfiles` directory should now look like this:
+In this example, your project directory should now also contain:
```
-gemfiles/Gemfile.4.2.mysql2
-gemfiles/Gemfile.5.0.pg
+Gemfile.4.2.mysql2
+Gemfile.5.0.pg
```
### Define combinations of gemfiles and Ruby versions
We will now define a test matrix that contains all permutations of gemfiles and tested Ruby versions.
-We store the matrix in a `.travis.yml` file, **even if the project is not using Travis CI**. This allows us to configure the matrix once and us it for both local developent and Travis CI builds.
+We store the matrix in a `.travis.yml` file, **even if the project is not using Travis CI**. This allows us to configure the matrix once and us it for both local development and Travis CI builds.
Create a `.travis.yml` that lists all gemfiles and Ruby versions you'd like to test against:
```yaml
rvm:
- 2.1.8
- 2.2.4
- 2.3.1
gemfile:
- - gemfiles/Gemfile.3.2.mysql2
- - gemfiles/Gemfile.4.2.mysql2
- - gemfiles/Gemfile.4.2.pg
- - gemfiles/Gemfile.5.0.mysql2
- - gemfiles/Gemfile.5.0.pg
+ - Gemfile.3.2.mysql2
+ - Gemfile.4.2.mysql2
+ - Gemfile.4.2.pg
+ - Gemfile.5.0.mysql2
+ - Gemfile.5.0.pg
```
Don't mind the `rvm` key if you're using a different version manager locally (like rbenv). Things will still work.
@@ -226,13 +221,13 @@
There might be incompatible combinations of gemfiles and Rubies, e.g. Rails 5.0 does not work with Ruby 2.1 or lower. In this case, add an `matrix`/`exclude` key to your `.travis.yml`:
```yaml
matrix:
exclude:
- - gemfile: gemfiles/Gemfile.5.0.mysql2
+ - gemfile: Gemfile.5.0.mysql2
rvm: 2.1.8
- - gemfile: gemfiles/Gemfile.5.0.pg
+ - gemfile: Gemfile.5.0.pg
rvm: 2.1.8
```
### Generate lockfiles
@@ -240,17 +235,17 @@
```shell
rake matrix:install
```
-In this example, your `gemfiles` directory should now contain a lockfile for each gemfile:
+In this example, your project directory should now contain a lockfile for each gemfile:
```
-gemfiles/Gemfile.4.2.mysql2
-gemfiles/Gemfile.4.2.mysql2.lock
-gemfiles/Gemfile.5.0.pg
-gemfiles/Gemfile.5.0.pg.lock
+Gemfile.4.2.mysql2
+Gemfile.4.2.mysql2.lock
+Gemfile.5.0.pg
+Gemfile.5.0.pg.lock
```
Gemfiles and lockfiles should be committed to your repo.
Make sure to re-run `rake matrix:install` after each change to your gemfiles, and commit the generated changes.
@@ -267,12 +262,12 @@
```
Choose a default dependency set and symlink both gemfile and lockfile to your project root:
```
-ln -s gemfiles/Gemfile.4.2.mysql2 Gemfile
-ln -s gemfiles/Gemfile.4.2.mysql2.lock Gemfile.lock
+ln -s Gemfile.4.2.mysql2 Gemfile
+ln -s Gemfile.4.2.mysql2.lock Gemfile.lock
```
Commit both `.ruby-version` and symlinks to your repo.
We recommend to setup Travis CI (see below) to check the entire test matrix after each push, even if a developer only tested with the defaults.
@@ -293,10 +288,13 @@
postgresql:
database: minidusen_test
user:
password:
+
+sqlite:
+ database: ":memory:"
```
We don't want to commit our local credentials, so add a line to your `.gitignore`:
```
@@ -429,11 +427,11 @@
```
Note that if your current Ruby version is *very* far away from your [default Ruby](#default-ruby-and-default-gemfile) in `.ruby-version`, you might need to run `rake` with a gemfile that has compatible dependencies:
```shell
-BUNDLE_GEMFILE=gemfiles/Gemfile.2.3 bundle exec rake matrix:install
-BUNDLE_GEMFILE=gemfiles/Gemfile.2.3 bundle exec rake matrix:spec
+BUNDLE_GEMFILE=Gemfile.2.3 bundle exec rake matrix:install
+BUNDLE_GEMFILE=Gemfile.2.3 bundle exec rake matrix:spec
```
We recommend to setup Travis CI to check the entire test matrix after each push, including all Rubies. This way developers can stay on the [default Ruby and gemfile](#default-ruby-and-default-gemfile) most of the time while Travis CI checks make sure that nothing broken gets merged.