README.md in gemika-0.1.4 vs README.md in gemika-0.2.0

- old
+ new

@@ -1,13 +1,17 @@ -# Gemika +# Gemika [![Build Status](https://travis-ci.org/makandra/gemika.svg?branch=master)](https://travis-ci.org/makandra/gemika) ## Test a Ruby gem against multiple versions of everything Gemika helps you test your gem against multiple versions of Ruby, gem dependencies and database types. -Here's what Gemika can give your test's development setup (all steps are opt-in): +![Matrix task output](https://raw.githubusercontent.com/makandra/gemika/master/doc/minidusen_test.png) +## Features + +Here's what Gemika can give your test's development setup (all features are opt-in): + - Test one codebase against multiple sets of gem dependency sets (e.g. Rails 4.2, Rails 5.0). - Test one codebase against multiple Ruby versions (e.g. Ruby 2.1.8, Ruby 2.3.1). - Test one codebase against multiple database types (currently MySQL or PostgreSQL). - Compute a matrix of all possible dependency permutations (Ruby, gem set, database type). Manually exclude incompatible dependency permutations (e.g. Rails 5.0 does not work with Ruby 2.1). - Let developers enter their local credentials for MySQL and PostgreSQL in a `database.yml` file. @@ -17,16 +21,25 @@ - Define an [ActiveRecord database migration](http://api.rubyonrails.org/classes/ActiveRecord/Migration.html) that sets up your test database. - Automatically drop and re-create your test database before each run of your test suite. - Configure RSpec to wrap each example in a transaction that is rolled back when the example ends. This way each example starts with a blank database. -## Requirements +## Compatibility -- Gemika currently assumes you're testing with [RSpec](http://rspec.info/). -- If you use any database-related features, you need `activaterecord` as a development dependency +Gemika currently supports the following dependency versions: +- Ruby: 1.8.7, 2.1, 2.2, 2.3 +- RSpec: Versions 1, 3 +- ActiveRecord: Versions 2.3, 3.2, 4.2, 5.0 +- Databases: PostgreSQL (with `pg` gem), MySQL or MariaDB (with `mysql2` gem) +Gemika also makes some assumption about your Gem: + +- You're testing with [RSpec](http://rspec.info/). +- If you use any database-related features, you need `activerecord` as a development dependency + + ## 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 @@ -42,17 +55,18 @@ .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' README.md # README for your gem -lib/my_gem.rb # Library files for your gem +lib/my_gem.rb # Main file to require for your gem lib/my_gem/my_class.rb # Class delivered by your gem lib/my_gem/version.rb # Version definition for your gem spec/spec_helper.rb # Requires 'gemika' and all files in support folder -spec/support/database.rb # Calls `Gemika.rewrite_schema! { ... }` -spec/support/database.yml # Local -spec/support/database.travis.yml # Calls `Gemika.rewrite_schema! { ... }` +spec/support/database.rb # Database schema for test database +spec/support/database.yml # Database credentials for local development (not checked in) +spec/support/database.sample.yml # Sample database credentials for new developers +spec/support/database.travis.yml # Database credentials for Travis CI spec/my_gem/my_class_spec.rb # Tests for your gem ``` For a live example of this setup, check the [makandra/minidusen](https://github.com/makandra/minidusen) repo. @@ -62,15 +76,15 @@ ### Have a standard gem setup Gemika expects a standard gem directory that looks roughly like this: +```shell +my_gem.gemspec # Specification for your gem +Rakefile # Rake tasks for your gem +lib/my_gem.rb # Main file to require for your gem ``` -my_gem.gemspec # Specification for your gem -Rakefile # Should require 'gemika/tasks' -lib/my_gem.rb # Library files for your gem -``` If you don't have a directory yet, you can [ask Bundler to create it for you](http://bundler.io/rubygems.html): ``` bundle gem my_gem @@ -242,10 +256,12 @@ ``` ln -s gemfiles/Gemfile.4.2.mysql2 Gemfile ln -s gemfiles/Gemfile.4.2.mysql2.lock Gemfile.lock ``` +Note that since you now have a Gemfile in your project root, you will need to call `bundle exec rake` instead of `rake` from this point on. + 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. @@ -489,9 +505,31 @@ - Install development dependencies using `bundle matrix:install` - Run tests using `bundle matrix:spec` Note that we have configured Travis CI to automatically run tests in all supported Ruby versions and dependency sets after each push. We will only merge pull requests after a green Travis build. ``` + + +Development +----------- + +Here are some hints when you try to make changes to Gemika: + +There are tests in `spec`. We only accept PRs with tests. To run tests: + +- Install Ruby 2.2.4 +- Create a local test database `gemika_test` in both MySQL and PostgreSQL +- Copy `spec/support/database.sample.yml` to `spec/support/database.yml` and enter your local credentials for the test databases +- Install development dependencies using `bundle install` +- Run tests using `bundle exec rspec` + +We recommend to test large changes against multiple versions of Ruby and multiple dependency sets. Supported combinations are configured in `.travis.yml`. We provide some rake tasks to help with this: + +- Install development dependencies using `bundle matrix:install` +- Run tests using `bundle matrix:spec` + +Note that we have configured Travis CI to automatically run tests in all supported Ruby versions and dependency sets after each push. We will only merge pull requests after a green Travis build. + Credits ------- Henning Koch from [makandra](http://makandra.com/)