README.md in config-2.0.0 vs README.md in config-2.1.0

- old
+ new

@@ -2,10 +2,11 @@ [![Build Status](https://api.travis-ci.org/railsconfig/config.svg?branch=master)](http://travis-ci.org/railsconfig/config) [![Gem Version](https://badge.fury.io/rb/config.svg)](http://badge.fury.io/rb/config) [![Maintainability](https://api.codeclimate.com/v1/badges/85c206c13dce7de090af/maintainability)](https://codeclimate.com/github/railsconfig/config/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/85c206c13dce7de090af/test_coverage)](https://codeclimate.com/github/railsconfig/config/test_coverage) +[![Financial Contributors on Open Collective](https://opencollective.com/rubyconfig/all/badge.svg?label=financial+contributors)](https://opencollective.com/rubyconfig) ## Summary Config helps you easily manage environment specific settings in an easy and usable manner. @@ -55,38 +56,34 @@ register Config ``` ### Installing on Sinatra -Add the gem to your `Gemfile` and run `bundle install` to install it. Afterwards in need to register `Config` in your -app and give it a root so it can find the config files. +Add the gem to your `Gemfile` and run `bundle install` to install it. Afterwards in need to register `Config` in your app and give it a root so it can find the config files. ```ruby set :root, File.dirname(__FILE__) register Config ``` ### Installing on other ruby projects -Add the gem to your `Gemfile` and run `bundle install` to install it. -Then initialize `Config` manually within your configure block. +Add the gem to your `Gemfile` and run `bundle install` to install it. Then initialize `Config` manually within your configure block. ```ruby Config.load_and_set_settings(Config.setting_files("/path/to/config_root", "your_project_environment")) ``` -It's also possible to initialize `Config` manually within your configure block if you want to just give it some yml -paths to load from. +It's also possible to initialize `Config` manually within your configure block if you want to just give it some yml paths to load from. ```ruby Config.load_and_set_settings("/path/to/yaml1", "/path/to/yaml2", ...) ``` ## Accessing the Settings object -After installing the gem, `Settings` object will become available globally and by default will be compiled from the -files listed below. Settings defined in files that are lower in the list override settings higher. +After installing the gem, `Settings` object will become available globally and by default will be compiled from the files listed below. Settings defined in files that are lower in the list override settings higher. config/settings.yml config/settings/#{environment}.yml config/environments/#{environment}.yml @@ -134,12 +131,11 @@ ) ``` ### Environment specific config files -You can have environment specific config files. Environment specific config entries take precedence over common config -entries. +You can have environment specific config files. Environment specific config entries take precedence over common config entries. Example development environment config file: ```ruby #{Rails.root}/config/environments/development.yml @@ -151,19 +147,20 @@ #{Rails.root}/config/environments/production.yml ``` ### Developer specific config files -If you want to have local settings, specific to your machine or development environment, -you can use the following files, which are automatically `.gitignore` : +If you want to have local settings, specific to your machine or development environment, you can use the following files, which are automatically `.gitignore` : ```ruby Rails.root.join("config", "settings.local.yml").to_s, Rails.root.join("config", "settings", "#{Rails.env}.local.yml").to_s, Rails.root.join("config", "environments", "#{Rails.env}.local.yml").to_s ``` +**NOTE:** The file `settings.local.yml` will not be loaded in tests to prevent local configuration from causing flaky or non-deterministic tests. Environment-specific files (e.g. `settings/test.local.yml`) will still be loaded to allow test-specific credentials. + ### Adding sources at runtime You can add new YAML config files at runtime. Just use: ```ruby @@ -178,15 +175,13 @@ ```ruby Settings.prepend_source!("/path/to/source.yml") Settings.reload! ``` -This will do the same as `add_source`, but the given YML file will be loaded first (instead of last) and its settings -will be overwritten by any other configuration file. This is especially useful if you want to define defaults. +This will do the same as `add_source`, but the given YML file will be loaded first (instead of last) and its settings will be overwritten by any other configuration file. This is especially useful if you want to define defaults. -One thing I like to do for my Rails projects is provide a local.yml config file that is .gitignored (so its independent -per developer). Then I create a new initializer in `config/initializers/add_local_config.rb` with the contents +One thing I like to do for my Rails projects is provide a local.yml config file that is .gitignored (so its independent per developer). Then I create a new initializer in `config/initializers/add_local_config.rb` with the contents ```ruby Settings.add_source!("#{Rails.root}/config/settings/local.yml") Settings.reload! ``` @@ -250,22 +245,20 @@ Settings.section.servers[1].name # => amazon.com ``` ## Configuration -There are multiple configuration options available, however you can customize `Config` only once, preferably during -application initialization phase: +There are multiple configuration options available, however you can customize `Config` only once, preferably during application initialization phase: ```ruby Config.setup do |config| config.const_name = 'Settings' - ... + # ... end ``` -After installing `Config` in Rails, you will find automatically generated file that contains default configuration -located at `config/initializers/config.rb`. +After installing `Config` in Rails, you will find automatically generated file that contains default configuration located at `config/initializers/config.rb`. ### General * `const_name` - name of the object holing you settings. Default: `'Settings'` @@ -298,30 +291,63 @@ Check [Deep Merge](https://github.com/danielsdeleo/deep_merge) for more details. ### Validation -With Ruby 2.1 or newer, you can optionally define a schema to validate presence (and type) of specific config values: +With Ruby 2.1 or newer, you can optionally define a [schema](https://github.com/dry-rb/dry-schema) or [contract](https://github.com/dry-rb/dry-validation) (added in `config-2.1`) using [dry-rb](https://github.com/dry-rb) to validate presence (and type) of specific config values. Generally speaking contracts allow to describe more complex validations with depencecies between fields. +If you provide either validation option (or both) it will automatically be used to validate your config. If validation fails it will raise a `Config::Validation::Error` containing information about all the mismatches between the schema and your config. + +Both examples below demonstrates how to ensure that the configuration has an optional `email` and the `youtube` structure with the `api_key` field filled. The contract adds an additional rule. + +#### Contract + +Leverage dry-validation, you can create a contract with a params schema and rules: + ```ruby +class ConfigContract < Dry::Validation::Contract + params do + optional(:email).maybe(:str?) + + required(:youtube).schema do + required(:api_key).filled + end + end + + rule(:email) do + unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match?(value) + key.failure('has invalid format') + end + end +end + Config.setup do |config| + config.validation_contract = ConfigContract +end +``` + +The above example adds a rule to ensure the `email` is valid by matching it against the provided regular expression. + +Check [dry-validation](https://github.com/dry-rb/dry-validation) for more details. + +#### Schema + +You may also specify a schema using [dry-schema](https://github.com/dry-rb/dry-schema): + +```ruby +Config.setup do |config| # ... config.schema do + optional(:email).maybe(:str?) + required(:youtube).schema do required(:api_key).filled end end end ``` -The above example demonstrates how to ensure that the configuration has the `youtube` structure -with the `api_key` field filled. - -If you define a schema it will automatically be used to validate your config. If validation fails it will -raise a `Config::Validation::Error` containing a nice message with information about all the mismatches -between the schema and your config. - Check [dry-schema](https://github.com/dry-rb/dry-schema) for more details. ### Missing keys For an example settings file: @@ -369,46 +395,40 @@ See section below for more details. ## Working with environment variables -To load environment variables from the `ENV` object, that will override any settings defined in files, set the `use_env` -to true in your `config/initializers/config.rb` file: +To load environment variables from the `ENV` object, that will override any settings defined in files, set the `use_env` to true in your `config/initializers/config.rb` file: ```ruby Config.setup do |config| config.const_name = 'Settings' config.use_env = true end ``` -Now config would read values from the ENV object to the settings. For the example above it would look for keys starting -with `Settings`: +Now config would read values from the ENV object to the settings. For the example above it would look for keys starting with `Settings`: ```ruby ENV['Settings.section.size'] = 1 ENV['Settings.section.server'] = 'google.com' ``` It won't work with arrays, though. ### Working with Heroku -Heroku uses ENV object to store sensitive settings. You cannot upload such files to Heroku because it's ephemeral -filesystem gets recreated from the git sources on each instance refresh. To use config with Heroku just set the -`use_env` var to `true` as mentioned above. +Heroku uses ENV object to store sensitive settings. You cannot upload such files to Heroku because it's ephemeral filesystem gets recreated from the git sources on each instance refresh. To use config with Heroku just set the `use_env` var to `true` as mentioned above. To upload your local values to Heroku you could ran `bundle exec rake config:heroku`. ### Fine-tuning You can customize how environment variables are processed: -* `env_prefix` (default: `SETTINGS`) - which ENV variables to load into config -* `env_separator` (default: `.`) - what string to use as level separator - default value of `.` works well with - Heroku, but you might want to change it for example for `__` to easy override settings from command line, where using - dots in variable names might not be allowed (eg. Bash) +* `env_prefix` (default: `const_name`) - load only ENV variables starting with this prefix (case-sensitive) +* `env_separator` (default: `'.'`) - what string to use as level separator - default value of `.` works well with Heroku, but you might want to change it for example for `__` to easy override settings from command line, where using dots in variable names might not be allowed (eg. Bash) * `env_converter` (default: `:downcase`) - how to process variables names: * `nil` - no change * `:downcase` - convert to lower case * `env_parse_values` (default: `true`) - try to parse values to a correct type (`Boolean`, `Integer`, `Float`, `String`) @@ -440,40 +460,51 @@ Settings.section.ssl_enabled # => false ``` ## Contributing -Install appraisal +You are very warmly welcome to help. Please follow our [contribution guidelines](CONTRIBUTING.md) -```bash -gem install bundler -v 1.17.3 -gem install appraisal -``` +Any and all contributions offered in any form, past present or future are understood to be in complete agreement and acceptance with [MIT](LICENSE) license. -Bootstrap -```bash -appraisal install -``` -Run the test suite: - -```bash -appraisal rspec -``` - -If you modified any of the documentation files verify their format: - -```bash -mdl --style .mdlstyle.rb *.md -``` - ## Authors * [Piotr Kuczynski](http://github.com/pkuczynski) * [Fred Wu](http://github.com/fredwu) * [Jacques Crocker](http://github.com/railsjedi) * Inherited from [AppConfig](http://github.com/cjbottaro/app_config) by [Christopher J. Bottaro](http://github.com/cjbottaro) + +## Contributors + +### Code Contributors + +This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. +<a href="https://github.com/railsconfig/config/graphs/contributors"><img src="https://opencollective.com/rubyconfig/contributors.svg?width=890&button=false" /></a> + +### Financial Contributors + +[[Become a financial contributor](https://opencollective.com/rubyconfig/contribute)] and and support us with a small donation to help us continue our activities. Thank you if you already one! 🙏 + +#### Individuals + +<a href="https://opencollective.com/rubyconfig"><img src="https://opencollective.com/rubyconfig/individuals.svg?width=890"></a> + +#### Organizations + +Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/rubyconfig/contribute)] + +<a href="https://opencollective.com/rubyconfig/organization/0/website"><img src="https://opencollective.com/rubyconfig/organization/0/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/1/website"><img src="https://opencollective.com/rubyconfig/organization/1/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/2/website"><img src="https://opencollective.com/rubyconfig/organization/2/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/3/website"><img src="https://opencollective.com/rubyconfig/organization/3/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/4/website"><img src="https://opencollective.com/rubyconfig/organization/4/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/5/website"><img src="https://opencollective.com/rubyconfig/organization/5/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/6/website"><img src="https://opencollective.com/rubyconfig/organization/6/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/7/website"><img src="https://opencollective.com/rubyconfig/organization/7/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/8/website"><img src="https://opencollective.com/rubyconfig/organization/8/avatar.svg"></a> +<a href="https://opencollective.com/rubyconfig/organization/9/website"><img src="https://opencollective.com/rubyconfig/organization/9/avatar.svg"></a> ## License Config is released under the [MIT License](http://www.opensource.org/licenses/MIT).