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.