flows 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eed3e3ba742be2b25c1ae3ca7b52d2db3418183e0950616409ef8d05232365de
-  data.tar.gz: c2f340f63e6e55178426c28fcfe29aa6d6c9af7d9a4b539d43461f068f4a6082
+  metadata.gz: dd10b19c7b749fd46c6b8897db3c9912603b4111af7793449d5ff49f69adfcb1
+  data.tar.gz: b18271b7321f199e978ebd4f66f2d21e532c20dd37cd61b6b641b00d875c2f4c
 SHA512:
-  metadata.gz: 44a6ac9cdcedb674aab92373647582e038602c9459361d1ccbc6502cd78556835042fb81004c2329f1c1a95108371040dddb829fbd11a8eaa20bf310817163f3
-  data.tar.gz: 333ff1f85e39a794c5e4073e7deeca887562a0568497cd480d75b26338aff242dc8c5d1a8f67ce822083e894beecfe033b7abcffe25e931490de53db7e52cf29
+  metadata.gz: 6b3e90d9b76911f1e0a0539bd89eee76a68dcba04f4136858412e4d0e0e1ca51ff8f35027963ef52fdd870f2b74ffe9a326aca4802cd443af2e55f8bf18f67b1
+  data.tar.gz: 5a6306a15a6024a1c9412f325ab3454b029abcd7d80defee6a9d5b286e8664981b572fb0ecf6f91d06b98c7d5f3040169fe02aae43b8ee8261fa7b65c469fe54

data/.github/workflows/{build.yml → test.yml}

@@ -1,4 +1,4 @@
-name: Build
+name: Test
 
 on:
   push:
@@ -11,7 +11,7 @@ on:
     - cron: 0 2 * * 1-5
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -19,6 +19,7 @@ jobs:
         ruby:
           - 2.5.x
           - 2.6.x
+          # - 2.7.x
     steps:
       - uses: actions/checkout@v1
       - name: Set up Ruby
@@ -31,13 +32,7 @@ jobs:
         run: sudo apt-get install hunspell
       - name: Install Deps
         run: bundle install --jobs 4 --retry 3
-      - name: Rubocop
-        run: bundle exec rubocop
-      - name: RSpec
+      - name: Test
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        run: bundle exec rspec
-      - name: Markdown Linter (docs)
-        run: bundle exec mdl docs/**/*.md README.md
-      - name: Spelling Check (docs & code)
-        run: bundle exec forspell
+        run: bundle exec rake

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/.vendor/
 /.yardoc
 /_yardoc/
 /coverage/
@@ -12,4 +13,11 @@
 
 # profile results folder
 /profile/
-!/profile/.keep
+!/profile/.keep
+
+# OS specific stuff
+.DS_Store
+
+# In case of gem development we don't need to track Gemfile.lock
+# All the constraints must be expressed in gemspec
+/Gemfile.lock

data/.mdlrc

@@ -1 +1 @@
-rules "~MD013", "~MD033"
+rules "~MD013", "~MD033", "~MD024"

data/.reek.yml

@@ -0,0 +1,54 @@
+# default config: https://github.com/troessner/reek/blob/master/docs/defaults.reek.yml
+# detectors' docs: https://github.com/troessner/reek/tree/master/docs
+---
+exclude_paths:
+  - 'bin/'
+  - 'spec/'
+
+detectors:
+  LongParameterList:
+    enabled: true
+    exclude: []
+    max_params: 4 # +1 to default value
+    overrides:
+      initialize:
+        max_params: 6 # +1 to default value
+  ModuleInitialize:
+    enabled: false
+  TooManyInstanceVariables:
+    enabled: true
+    exclude: []
+    max_instance_variables: 5 # +1 to default value
+  DataClump:
+    exclude:
+      - Flows::Result::Helpers
+      - Flows::SharedContextPipeline::DSL::Tracks
+  IrresponsibleModule:
+    exclude:
+      - Flows::SharedContextPipeline
+  FeatureEnvy:
+    exclude:
+      - Flows::SharedContextPipeline#call
+      - Flows::Contract # too many false positives here
+      - Flows::Plugin::Profiler::Report#events
+  TooManyStatements:
+    exclude:
+      - Flows::SharedContextPipeline#call
+      - Flows::Plugin::Profiler::Wrapper#make_instance_wrapper
+      - Flows::Plugin::Profiler::Wrapper#make_singleton_wrapper
+      - initialize
+  DuplicateMethodCall:
+    exclude:
+      - Flows::SharedContextPipeline#call
+      - Flows::Plugin::Profiler::Wrapper#make_instance_wrapper
+      - Flows::Plugin::Profiler::Wrapper#make_singleton_wrapper
+      - 'length'
+  MissingSafeMethod:
+    exclude:
+      - Flows::Contract
+  BooleanParameter:
+    exclude:
+      - Flows::Plugin::OutputContract::DSL
+  TooManyMethods:
+    exclude:
+      - Flows::Plugin::Profiler::Report::Tree::Node

data/.rubocop.yml

@@ -1,12 +1,24 @@
+inherit_from: .rubocop_todo.yml
+
 require:
   - rubocop-rspec
   - rubocop-performance
   - rubocop-md
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 2.5
+  NewCops: enable
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
 
-LineLength:
+Layout/LineLength:
   Max: 120
 
 Metrics/BlockLength:
@@ -22,9 +34,10 @@ Metrics/ParameterLists:
 Style/WhileUntilModifier:
   Enabled: false
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   Exclude:
     - '**/*.md'
+    - 'spec/**/*'
 
 Style/MixinUsage:
   Exclude:
@@ -38,10 +51,16 @@ Lint/UnusedBlockArgument:
   Exclude:
     - '**/*.md'
 
-Lint/UnreachableCode:
+Style/CaseEquality:
   Exclude:
-    - 'docs/result_objects/do_notation.md'
+    - 'lib/flows/contract/**/*'
+
+Naming/RescuedExceptionsVariableName:
+  PreferredName: err
 
-Lint/Void:
+Style/Documentation:
   Exclude:
-    - 'docs/result_objects/do_notation.md'
+    - 'lib/flows/shared_context_pipeline/step.rb' # false positive here
+
+Style/SlicingWithRange:
+  Enabled: false # to support Ruby 2.5

data/.rubocop_todo.yml

@@ -0,0 +1,27 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --auto-gen-only-exclude`
+# on 2020-08-22 07:49:05 UTC using RuboCop version 0.89.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 27
+#
+# *** NON-GENERATED COMMENT ***
+# I'm not sure about enabling this cop
+# * using super may has performance impact
+# * but for some cases it still can be useful
+# Research needed
+Lint/MissingSuper:
+  Enabled: false
+
+# Offense count: 5
+# Configuration parameters: AllowSubject, Max.
+#
+# *** NON-GENERATED COMMENT ***
+# Might be it's impossible to satisfy this cop or significant refactoring of these tests needed
+RSpec/MultipleMemoizedHelpers:
+  Exclude:
+    - 'spec/flows/flow/node_spec.rb'
+    - 'spec/flows/util/inheritable_singleton_vars/isolation_strategy_spec.rb'

data/.ruby-version

@@ -1 +1 @@
-2.6.2
+2.6.6

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Types of changes:
+
+* _Added_ - for new features.
+* _Changed_ -  for changes in existing functionality.
+* _Deprecated_ - for soon-to-be removed features.
+* _Removed_ - for now removed features.
+* _Fixed_ -- for any bug fixes.
+* _Security_ - in case of vulnerabilities.
+
+## [Unreleased]
+
+## [0.6.0] - 2020-09-23
+
+### Added
+
+* `Flows::Plugin::Interface` basic implementation
+* `Flows::SharedContextPipeline` simple sub-pipelines injection
+
+### Changed
+
+* `Flows::SharedContextPipeline` callbacks execution method is changed to `instance_exec` (previously was `.call`)
+
+### Fixed
+
+* `Flows::Plugin::DependencyInjector` and modules generated by `Flows::Util::InheritableSingletonVars::DupStrategy` now can be safely included several times in the inheritance chain
+
+## [0.5.1] - 2020-06-29
+
+### Fixed
+
+* `Flows::SharedContextPipeline` wrap DSL failure in case of inheritance, [issue](https://github.com/ffloyd/flows/issues/18)
+
+## [0.5.0] - 2020-05-18
+
+### Added
+
+* `Flows::SharedContextPipeline` wrap DSL, [issue](https://github.com/ffloyd/flows/issues/7)
+* `Flows::Flow` routing integrity check on initialization
+* `Flows::Plugin::OutputContract` skip contract DSL method
+* `Flows::Plugin::Profiler` introduced. Report types: raw, tree and flat.
+
+### Changed
+
+* `Flows::SharedContextPipeline` callback API, [issue](https://github.com/ffloyd/flows/issues/6)
+* `Flows::Util` modules API, [issue](https://github.com/ffloyd/flows/issues/11)
+* `Flows::Contract::CaseEq` default error expanded to present more context
+
+## [0.4.0] - 2020-04-21
+
+### Added
+
+* `Flows::Contract` - type contracts with specific transformation feature.
+* `Flows::Flow` - fast and lightweight logic execution engine, designed for
+  internal usage and library writers.
+* `Flows::Plugin::DependencyInjector` - simple dependency injection plugin for your classes
+* `Flows::Plugin::ImplicitInit` - allows to use `MyClass.call` instead of
+  `MyClass.new.call`, an class instance will be created once.
+* `Flows::Plugin::OutputContract` - plugin for output type checks and
+  transformations for service objects which return `Flows::Result`.
+* `Flows::Railway` - stupid simple implementation of the railway pattern.
+* `Flows::Result` - general purpose Result Object designed after Rust Result type.
+* `Flows::Result::Do` - do-notation for Result Objects.
+* `Flows::SharedContextPipeline` - much more flexible adoption of the railway
+  pattern for Ruby.
+* `Flows::Util::InheritableSingletonVars` - allows to define behavior for
+  singleton variables in the context of inheritance.
+* `Flows::Util::PrependToClass` - allows to prepend some module to class even if
+  target module did not included directly into class.
+
+[unreleased]: https://github.com/ffloyd/flows/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ffloyd/flows/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/ffloyd/flows/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/ffloyd/flows/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/ffloyd/flows/compare/v0.3.0...v0.4.0

data/Gemfile

@@ -2,9 +2,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in flows.gemspec
 gemspec
-
-# temporary dev dependencies,
-# move it to gemspec after PRs will be merged into realesed version of a gem
-group :development do
-  gem 'mdl', github: 'ffloyd/markdownlint', branch: 'update-kramdown-dep'
-end

data/README.md

@@ -1,12 +1,16 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/badge.svg)](https://github.com/ffloyd/flows/actions)
 [![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
 [![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
 
 Small and fast ruby framework for implementing railway-like operations.
-By design it is close to [Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/) and [Dry::Transaction](https://dry-rb.org/gems/dry-transaction/),
-but has simpler and flexible DSL for defining operations and matching results. Also `flows` is faster, see [Performance](#performance).
+By design it is close to
+[Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/),
+[Dry::Transaction](https://dry-rb.org/gems/dry-transaction/) and Rust control
+flow style.
+Flows has simple and flexible DSL for defining operations and matching results.
+Also `flows` is faster than Ruby's alternatives.
 
 `flows` has no production dependencies so it can be used with any framework.
 
@@ -15,7 +19,7 @@ but has simpler and flexible DSL for defining operations and matching results. A
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'flows'
+gem 'flows', '~> 0.5'
 ```
 
 And then execute:
@@ -30,436 +34,236 @@ Or install it yourself as:
 gem install flows
 ```
 
-## Usage
+## Supported Ruby versions
 
-### `Flows::Flow`
+CI tests against last patch versions every day:
 
-Low-level instrument for defining execution flows. Used internally as execution engine for `Flows::Operation`.
-Check out source code and specs for details.
+* `MRI 2.5.x`
+* `MRI 2.6.x`
 
-### `Flows::Result`
+`MRI 2.7.x` will be added later, right now (`2.7.1`) this version of MRI Ruby is too
+unstable and produce segmentation faults inside RSpec internals.
 
-Result Object implementation. Inspired by [Dry::Monads::Result](https://dry-rb.org/gems/dry-monads/1.0/result/) and
-[Rust Result Objects](https://doc.rust-lang.org/1.30.0/book/2018-edition/ch09-02-recoverable-errors-with-result.html).
+## Usage & Documentation
 
-Main concepts & conventions:
+* [YARD documentation](https://rubydoc.info/github/ffloyd/flows/master) - this
+  link is for master branch. You can also find YARD documentation for any released
+  version after `v0.4.0`. This documentation has a lot of examples, describes
+  motivation behind each abstraction, but lacks some guides and defined conventions.
+* [Guides](https://ffloyd.github.io/flows/#/) - guides, conventions, integration
+  and migration notes. Will be done before `v1.0.0` release. Right now is under development.
 
-* separate classes for successful (`Flows::Result::Ok`) and failure (`Flows::Result::Err`) results
-  * both classes has same parent class `Flows::Result`
-* result data should be a `Hash` with symbol keys and any values
-* result has a status
-  * default status for successful results is `:success`
-  * default status for failure results is `:failure`
+## Development
 
-Basic usage:
+`Flows` is designed to be framework for your business logic. It is a big
+responsibility. That's why `flows` has near to be sadistic development
+conventions and linter setup.
 
-```ruby
-# create successful result with data {a: 1, b: 2}
-result_ok = Flows::Result::Ok.new(a: 1, b: 2)
+### Anyone can make Flows even better
 
-# get `:a` from result
-result_ok.unwrap[:a] # 1
+If you see some typos or unclear things in documentation or code - feel free to open
+an issue. Even if you don't have plans to implement a solution - a problem reporting
+will help development much. We cannot fix what we don't know.
 
-# get error data from result
-result_ok.error[:a] # raises exception
+### [Lefthook](https://github.com/Arkweid/lefthook) as a git hook manager
 
-# get status from result
-result_ok.status # :success
+Installation on MacOS via Homebrew:
 
-# boolean flags
-result_ok.ok? # true
-result_ok.err? # false
+```sh
+brew install Arkweid/lefthook/lefthook
+```
 
-# create successful result with data {a: 1, b: 2} and status `:custom`
-result_ok_custom = Flows::Result::Ok.new({ a: 1, b: 2 }, status: :custom)
+Activation (in the root of the repo):
 
-# get status from result
-result_ok_custom.status # :custom
+```sh
+lefthook install
+```
 
-# create failure result with data {a: 1, b: 2}
-result_err = Flows::Result::Err.new(a: 1, b: 2)
+Run hooks manually:
 
-# get `:a` from result
-result_err.unwrap[:a] # raises exception
+```sh
+lefthook run pre-commit
+lefthook run pre-push
+```
 
-# get error data from result
-result_err.error[:a] # 1
+Please, never turn off the pre-commit and pre-push hooks.
 
-# get status from result
-result_err.status # :failure
+### Rubocop linter
 
-# boolean flags
-result_ok.ok? # false
-result_ok.err? # true
+[Rubocop](https://docs.rubocop.org/en/stable/) in this setup is responsible for:
 
-# create failure result with data {a: 1, b: 2} and status `:custom`
-result_err_custom = Flows::Result::Err.new({ a: 1, b: 2 }, status: :custom)
+* defining code style (indentation, etc.)
+* suggest performance improvements ([rubocop-performance](https://docs.rubocop.org/projects/performance/en/stable/))
+* forces all that stuff (with some exceptions) to snippets in Markdown files ([rubocop-md](https://github.com/rubocop-hq/rubocop-md))
+* forces unit-testing best practices ([rubocop-rspec](https://docs.rubocop.org/projects/rspec/en/latest/))
 
-# get status from result
-result_err_custom.status # :custom
-```
+Rubocop config for library and RSpec files should be close to standard one only
+with minor amount of exceptions.
 
-Mixin `Flows::Result::Helpers` contains tools for simpler generating and matching Result Objects:
+Code in Markdown snippets and `/bin` folder can ignore more rules. `/bin` folder
+contains only development-related scripts and tools so it's ok to ease linter requirements.
 
-```ruby
-include Flows::Result::Helpers
-
-# create successful result with data {a: 1, b: 2}
-result_ok = ok(a: 1, b: 2)
-
-# create successful result with data {a: 1, b: 2} and status `:custom`
-result_ok_custom = ok(:custom, a: 1, b: 2)
-
-# create failure result with data {a: 1, b: 2}
-result_err = err(a: 1, b: 2)
-
-# create failure result with data {a: 1, b: 2} and status `:custom`
-result_err_custom = err(:custom, a: 1, b: 2)
-
-# matching helpers
-result = SomeOperation.new.call
-
-case result
-when match_ok(:custom)
-  # matches only successful results with status :custom
-  do_something
-when match_ok
-  # matches only successful results with any status
-  do_something
-when match_err(:custom)
-  # matches only failure results with status :custom
-  do_something
-when match_err
-  # matches only failure results with any status
-  do_something
-end
-```
+Rubocop Metrics (ABC-size, method/class length, etc) must not be eased
+globally. Never.
 
-### `Flows::Operation`
+### Reek linter
 
-Let's solve simple task using operation:
+[Ruby Reek](https://github.com/troessner/reek) is a very aggressive linter that
+forces you to do a clean OOP design.
 
-* given numbers `a` and `b`
-* result should contain sum of this numbers
-* result should contain square of this sum
+You will be tempted to just shut up this linter many times. But believe me, in 9
+of 10 cases it worth to refactor. And after each such refactoring you will
+understand OOP design better and better.
 
-```ruby
-class Summator
-  # Make this class an operation by including this module.
-  # It adds DSL, initializer and call method.
-  # Also it includes Flows::Result::Helper both on DSL and instance level.
-  include Flows::Operation
-
-  # This is step definitions.
-  # In simplest form step defined by its name and
-  # step implementation expected to be in a method
-  # with same name.
-  #
-  # Steps will be executed in a definition order.
-  step :validate
-  step :calc_sum
-  step :calc_square
-
-  # Which keys of operation data we want to expose on success
-  ok_shape :sum, :sum_square
-
-  # Which keys of operation data we want to expose on failure
-  err_shape :message
-
-  # Step implementation receives execution context as keyword arguments.
-  # For the first step context equals to operation arguments.
-  #
-  # Step implementation must return Result Object.
-  # Result Objects's data will be merged into operation context.
-  #
-  # If result is successful - next step will be executed.
-  # If not - operation terminates and returns failure.
-  def validate(a:, b:, **)
-    err(message: 'a is not a number') unless a.is_a?(Number)
-    err(message: 'b is not a number') unless b.is_a?(Number)
-
-    ok
-  end
-
-  def calc_sum(a:, b:, **)
-    ok(sum: a + b)
-  end
-
-  # We may get data from previous steps because all results' data are merged to context.
-  def calc_square(sum:, **)
-    ok(sum_square: sum * sum)
-  end
-end
-
-# prepare operation
-operation = Summator.new
-
-# execute operation
-result = operation.call(a: 1, b: 2)
-
-result.ok? # true
-result.unwrap # { sum: 3, sum_square: 9 } - only keys from success shape present
-
-result = operation.call(a: nil, b: nil)
-
-result.ok? # false
-result.error # { message: 'a is not a number' } - only keys from error shape present
-```
+### Rest of the linters
 
-#### Result Shapes
+* [MDL](https://github.com/markdownlint/markdownlint) - for consistent format of Markdown files
+* [forspell](https://github.com/kkuprikov/forspell) - for spellchecking in comments and markdown files
+* [inch](http://rrrene.org/inch/) - for documentation coverage suggestions (the
+  only optional linter)
 
-You may limit list of exposed fields by defining success and failure shapes. _After_ step definitions use `ok_shape` to define shapes of success result, and `err_shape` to define shapes of failure result. Examples:
+### Default Rake task and CI
 
-```ruby
-# Set exposed keys for :success status of successful result.
-#
-# Success result will have shape like { key1: ..., key2: ... }
-#
-# If one of keys is missing in the final operation context an exception will be raised.
-ok_shape :key1, :key2
-
-# Set different exposed keys for different statuses.
-#
-# Operation result status is a status of last executed step result.
-ok_shape status1: %i[key1 key2],
-         status2: [:key3]
-
-# Failure shapes defined in the same way:
-err_shape :key1, :key2
-err_shape status1: %i[key1 key2],
-          status2: [:key3]
-```
+Default rake task (`bundle exec rake`) executes the following checks:
 
-Operation definition should have exact one `ok_shape` DSL-call and zero or one `err_shape` DSL-call. If you want to disable shaping
-you can write `no_shape` DSL-call instead of shape definitions.
+* Rubocop
+* Ruby Reek
+* RSpec
+* Spellcheck (forspell)
+* MarkdownLint (mdl)
 
-#### Routing & Tracks
+CI is also performing default Rake task. So, if you want to reproduce CI error
+locally - just run `bundle exec rake`.
 
-You define side tracks, even nested ones:
+Default Rake task is also executed as a pre-push git hook.
 
-```ruby
-step :outer_1 # next step is outer_2
-
-track :some_track do
-  step :inner_1 # next step is inner_2
-  track :inner_track do
-    step :deep_1 # next step is deep_2
-    step :deep_2 # next step is inner_2
-  end
-  step :inner_2 # next step in outer_2
-end
-
-step :outer_2
-```
+### Error reporting
 
-In definition above tracks will not be used because there is no routes to this tracks. You may define routing like this:
+I hope no one will argue that clear errors makes development noticeably faster.
+That's why _each_ exception in `flows` should be clear and easy to read.
 
-```ruby
-# if result is successful and has status :to_some_track - next step will be inner_1
-# for any other successful results - outer_2
-step :outer_1, routes(
-  when_ok(:to_some_track) => :some_track
-)
-
-track :some_track do
-  step :inner * 1, routes(when_err => :inner_track) # redirect to inner_track on any failure result
-  track :inner_track do
-    step :deep_1, routes(when_ok(:some_status) => :outer_2) # you may redirect to steps too
-    step :deep_2
-  end
-  step :inner_2
-end
-
-step :outer_2
-```
+This cannot be tested automatically: you only can test correctness
+automatically, convenience can only be tested manually. That's why when you
+introduce any new `raise` you have to:
 
-You also can use less verbose, but shorter form of definition:
+* make an error message clear and descriptive
+* add this error to _errors demo CLI_ (`bin/errors`)
+* add this errors to _all the errors demo_ (`bin/all_the_errors`)
+* make sure that error is displayed correctly and follows a style of the rest
+  of implemented errors
 
-```ruby
-step :name,
-     match_ok(:status) => :track_name,
-     match_ok => :track_name
-```
+`bin/errors` is done using [GLI](https://davetron5000.github.io/gli/) library,
+run `bin/errors -h` to explore possibilities.
 
-Step has default routes:
+### Performance
 
-```ruby
-routes(
-  when_ok => next_step_name,
-  when_err => :term
-)
-```
+Ruby is slow. Moreover, Ruby is very slow. Yes, again. In the past time we had
+to compare Ruby with Python. Python was faster and that's why people started to
+complain about Ruby performance. That was fixed. But is Ruby fast nowadays? No.
+Because languages like Clojure, Go, Rust, Elixir appeared and in comparison
+with any of these languages Ruby is very very slow.
 
-Custom routes have bigger priority than default ones. Moreover, default routes can be overriden.
+That's why you **must** be extra careful with performance. Some business
+operations can be executed hundreds or even thousands times per request. Each
+line of code in your abstraction will slow down such request a bit. That's why
+you should think about each line performance.
 
-#### Lambda Steps
+Also, it's nearly impossible to make zero-cost abstractions in Ruby. The best
+thing you can do - to offload calculations to a class loading or initialization
+step. Sacrifice some warm-up time to make runtime performance better.
 
-You can use lambda for in-place step implementation:
+And to compare performance overhead between different `flows` abstractions
+and another alternatives a benchmarking CLI was done: `bin/benchmark`.
 
-```ruby
-step :name, ->(a:, b:, **) { ok(sum: a + b) }
-```
+This CLI is done using GLI, run `bin/benchmark -h` to explore possibilities.
 
-#### Dependency Injection
+So far, `flows` offers the best performance among alternatives. And this CLI
+is made to simplify comparison with alternatives and keep `flows` the fastest solution.
 
-You can override or inject step implementation on initialization:
+### Documentation
 
-```ruby
-class Summator
-  include Flows::Operation
+Each public API method or module **must** be properly documented with examples
+and motivation behind.
 
-  step :sum
+To run documentation server locally run `bin/docserver`.
 
-  ok_shape :sum
-end
+Respect `@since` YARD documentation tag. When some module, class or method has any
+API change - you have to provide correct `@since` tag value to the documentation.
 
-summator = Summator.new(deps: {
-                          sum: ->(a:, b:, **) { ok(sum: a + b) }
-                        })
+### Documentation Driven Development
 
-summator.call(a: 1, b: 2).unwrap[:sum] # 3
-```
+When you about to do some work, the following guideline can lead to the best
+results:
 
-#### Wrapping steps
+* first, write needed class and method structure without implementation
+* write YARD documentation with motivation and usage examples for each public
+  class, method, module.
+* write unit tests, check that tests are failing
+* write implementation until tests are green
 
-You can wrap several steps with some logic:
+Yes, it's TDD approach with documentation step prepended.
 
-```ruby
-step :first
-
-wrap :wrapper do
-  step :wrapped
-end
-
-def wrapper(**_context)
-  # do smth
-  result = yield # execute wrapped steps
-  # do smth or modify result
-  result
-end
-```
+### Unit test
 
-There is routing limitation when you use wrap:
+Each public API method or module **must** be properly tested. Internal modules
+can be tested indirectly through public API.
 
-* outside `wrap` block you may route to wrapped block by wrapper name (`:wrapper` in the provided example)
-* you may route wrapped steps only to wrapped steps in the same wrap block
-* you cannot route to wrapped steps from outside
+Test coverage **must** be higher than 95%.
 
-## Performance
+### Commit naming
 
-You can compare performance for some cases by executing `bin/benchmark`. Examples for benchmark are presented in `bin/examples.rb`.
+You **must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
-`Flows::Operation` and `Dry::Trancation` may be executed in two ways:
+Allowed prefixes since `v0.4.0`:
 
-_Build once:_ when we create operation instance once (build operation):
+* `feat:` - for new features
+* `fix:` - for bugfixes
+* `perf:` - for performance improvements
+* `refactor:` - for refactoring work
+* `ci:` - updates for CI configuration
+* `docs:` - for documentation update
 
-```ruby
-operation = OperationClass.new
+Sometimes commit can have several responsibilities. As example: when you write
+documentation, test and implementation for a feature in the one commit. You can do
+extra effort to split and rearrange commits to make it atomic. But does it
+really provide significant value if we already have a strong convention for
+changelog (see the next section)?
 
-10_000.times { operation.call }
-```
+So, when you in such situation use the first applicable prefix in the list:
+between `docs` and `refactor` - pick `refactor`.
 
-_Build each time:_ when we create operation instance each execution:
+Also, there is one more special prefix for release commits. Release commit
+messages **must** look like: `release: v0.4.0`.
 
-```ruby
-10_000.times { OperationClass.new.call }
-```
+### Changelog
 
-`flows` and `dry` are much faster in _build once_ way of using. Note that Trailblazer gives you only one way to execute operation.
-
-### Benchmark Results
-
-Host:
-
-* MacBook Pro (13-inch, 2017, Four Thunderbolt 3 Ports)
-* 3.1 GHz Intel Core i5
-* 8 GB 2133 MHz LPDDR3
-
-Results:
-
-```text
---------------------------------------------------
-- task: A + B, one step implementation
---------------------------------------------------
-Warming up --------------------------------------
-Flows::Operation (build each time)
-                         9.147k i/100ms
-Flows::Operation (build once)
-                        25.738k i/100ms
-Dry::Transaction (build each time)
-                         2.294k i/100ms
-Dry::Transaction (build once)
-                        21.836k i/100ms
-Trailblazer::Operation
-                         5.057k i/100ms
-Calculating -------------------------------------
-Flows::Operation (build each time)
-                         96.095k (± 2.3%) i/s -    484.791k in   5.047684s
-Flows::Operation (build once)
-                        281.248k (± 1.7%) i/s -      1.416M in   5.034728s
-Dry::Transaction (build each time)
-                         23.683k (± 1.7%) i/s -    119.288k in   5.038506s
-Dry::Transaction (build once)
-                        237.379k (± 3.3%) i/s -      1.201M in   5.066073s
-Trailblazer::Operation
-                         52.676k (± 1.5%) i/s -    268.021k in   5.089306s
-
-Comparison:
-Flows::Operation (build once):   281248.4 i/s
-Dry::Transaction (build once):   237378.7 i/s - 1.18x  slower
-Flows::Operation (build each time):    96094.9 i/s - 2.93x  slower
-Trailblazer::Operation:    52676.3 i/s - 5.34x  slower
-Dry::Transaction (build each time):    23682.9 i/s - 11.88x  slower
-
-
---------------------------------------------------
-- task: ten steps returns successful result
---------------------------------------------------
-Warming up --------------------------------------
-Flows::Operation (build each time)
-                         1.496k i/100ms
-Flows::Operation (build once)
-                         3.847k i/100ms
-Dry::Transaction (build each time)
-                       274.000  i/100ms
-Dry::Transaction (build once)
-                         2.992k i/100ms
-Trailblazer::Operation
-                         1.082k i/100ms
-Calculating -------------------------------------
-Flows::Operation (build each time)
-                         15.013k (± 3.8%) i/s -     76.296k in   5.089734s
-Flows::Operation (build once)
-                         39.239k (± 1.6%) i/s -    196.197k in   5.001538s
-Dry::Transaction (build each time)
-                          2.743k (± 3.7%) i/s -     13.700k in   5.002847s
-Dry::Transaction (build once)
-                         30.441k (± 1.8%) i/s -    152.592k in   5.014565s
-Trailblazer::Operation
-                         11.022k (± 1.4%) i/s -     55.182k in   5.007543s
-
-Comparison:
-Flows::Operation (build once):    39238.6 i/s
-Dry::Transaction (build once):    30440.5 i/s - 1.29x  slower
-Flows::Operation (build each time):    15012.7 i/s - 2.61x  slower
-Trailblazer::Operation:    11022.1 i/s - 3.56x  slower
-Dry::Transaction (build each time):     2743.0 i/s - 14.30x  slower
-```
+Starting from `v0.4.0` [keep a changelog](https://keepachangelog.com/en/1.0.0/)
+guideline must be met.
 
-## Development
+If you adding something - provide some lines to the unreleased section of the `CHANGELOG.md`.
+
+### Versioning
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+The project strictly follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+After `v1.0.0` even smallest backward incompatible change will bump major
+version. _No exceptions._
 
-## Contributing
+Commit with a version bump should contain _only_ version bump and CHANGELOG.md update.
 
-Bug reports and pull requests are welcome on GitHub at [ffloyd/fflows](https://github.com/ffloyd/flows). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+### GitHub Flow
 
-## License
+Since `v0.4.0` this repo strictly follow [GitHub
+Flow](https://guides.github.com/introduction/flow/) with some additions:
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+* branch naming using dash: `improved-contexts`
+* use [references to
+  issues](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+  in commit messages and make links to issues in CHANGELOG.md
 
-## Code of Conduct
+### Planned features for v1.0.0
 
-Everyone interacting in the Flows project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ffloyd/flows/blob/master/CODE_OF_CONDUCT.md).
+* validation framework
+* error reporting improvements
+* various plugins for SCP (tracing, benchmarking, logging, etc)
+* site with guides and conventions