flows 0.1.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a69e7b183fcc1a9a0e0eabeaac0e66aff9fc55ea458fa34a5c37de86c7970ab
-  data.tar.gz: 20dbb58536ba20c0f7c7032757679ea968088965890851e93af81e2b4cb148f4
+  metadata.gz: e6f029a3e03c0cd3ac484cb703f67a1c4910a10c8395e7b1024518dc84a14cb5
+  data.tar.gz: 23f44992d336cd637c02ff6d96c82a99f7e6af2a2affc82bcdc2c3f4ee1153a2
 SHA512:
-  metadata.gz: b606d7df548e65d694f4700ecf6991667bca8f6626a41111bce6cbe9f8949ad0c5cfc58830fd1596b1fc3c170eaca7aed2b4f8f83092a5a7d174979978ece70b
-  data.tar.gz: 4fbfd1e9422aca8b7800b4930d32a7a3a4f4eca67eceab08cf0b20fcde24ef628d677f5bc40ffa1f7a1c9c3af6f1f80de78a6e248adf145f23f63d3d4ae6c77c
+  metadata.gz: 17015a5eb9868ced9c18872706625df9aeb51aa90717be36929fe223006b5e28fa439fcc63db49b43a047c0375b3d6493f4640da6164be21815b3df95291ae96
+  data.tar.gz: b2170ec9d8a710b70fd676772ba7a5556ab23b9a50313bf34f321afb440f07d9fe66bc76634a9e53f02dd7063ebf92e27a94e162e6470e2b22a87703a6856f48

data/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  schedule:
+    - cron: 0 2 * * 1-5
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.5.x
+          - 2.6.x
+          # - 2.7.x
+    steps:
+      - uses: actions/checkout@v1
+      - name: Set up Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install Bundler
+        run: gem install bundler
+      - name: Install Hunspell
+        run: sudo apt-get install hunspell
+      - name: Install Deps
+        run: bundle install --jobs 4 --retry 3
+      - name: Test
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        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

@@ -0,0 +1 @@
+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,11 +1,22 @@
 require:
   - rubocop-rspec
   - rubocop-performance
+  - rubocop-md
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 2.7
+  NewCops: enable
 
-LineLength:
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Layout/LineLength:
   Max: 120
 
 Metrics/BlockLength:
@@ -20,3 +31,34 @@ Metrics/ParameterLists:
 
 Style/WhileUntilModifier:
   Enabled: false
+
+Naming/MethodParameterName:
+  Exclude:
+    - '**/*.md'
+    - 'spec/**/*'
+
+Style/MixinUsage:
+  Exclude:
+    - '**/*.md'
+
+Lint/UnusedMethodArgument:
+  Exclude:
+    - '**/*.md'
+
+Lint/UnusedBlockArgument:
+  Exclude:
+    - '**/*.md'
+
+Style/CaseEquality:
+  Exclude:
+    - 'lib/flows/contract/**/*'
+
+Naming/RescuedExceptionsVariableName:
+  PreferredName: err
+
+Style/Documentation:
+  Exclude:
+    - 'lib/flows/shared_context_pipeline/step.rb' # false positive here
+
+Style/SlicingWithRange:
+  Enabled: false # to support Ruby 2.5

data/.ruby-version

@@ -1 +1 @@
-2.6.2
+2.6.5

data/.yardopts

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

data/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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.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.5.1...HEAD
+[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/README.md

@@ -1,339 +1,269 @@
 # Flows
 
-[![Build Status](https://travis-ci.com/ffloyd/flows.svg?branch=master)](https://travis-ci.com/ffloyd/flows)
+[![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 close to [Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/) and [Dry::Transaction](https://dry-rb.org/gems/dry-transaction/),
-but has more simpler and flexible DSL for defining operations and matching results. Also `flows` is significantly faster.
+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 you can use it with any framework.
+`flows` has no production dependencies so it can be used with any framework.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'flows'
+gem 'flows', '~> 0.5'
 ```
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install flows
+```sh
+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
+Rubocop Metrics (ABC-size, method/class length, etc) must not be eased
+globally. Never.
 
-# create successful result with data {a: 1, b: 2}
-result_ok = ok(a:1, b: 2)
+### Reek linter
 
-# create successful result with data {a: 1, b: 2} and status `:custom`
-result_ok_custom = ok(:custom, a: 1, b: 2)
+[Ruby Reek](https://github.com/troessner/reek) is a very aggressive linter that
+forces you to do a clean OOP design.
 
-# create failure result with data {a: 1, b: 2}
-result_err = err(a:1, b: 2)
+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.
 
-# create failure result with data {a: 1, b: 2} and status `:custom`
-result_err_custom = err(:custom, a: 1, b: 2)
+### Rest of the linters
 
-# matching helpers
-result = ...
+* [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)
 
-case result
-when match_ok(:custom)
-  # matches only successful results with status :custom
-when match_ok
-  # matches only successful results with any status
-when match_err(:custom)
-  # matches only failure results with status :custom
-when match_err
-  # matches only failure results with any status
-end
-```
+### Default Rake task and CI
 
-### `Flows::Operation`
+Default rake task (`bundle exec rake`) executes the following checks:
 
-Let's solve simple task using operation:
+* Rubocop
+* Ruby Reek
+* RSpec
+* Spellcheck (forspell)
+* MarkdownLint (mdl)
 
-* given numbers `a` and `b`
-* result should contain sum of this numbers
-* result should contain square of this sum
+CI is also performing default Rake task. So, if you want to reproduce CI error
+locally - just run `bundle exec rake`.
 
-```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') if !a.is_a?(Number)
-    err(message: 'b is not a number') if !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: a * b)
-  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
-```
+Default Rake task is also executed as a pre-push git hook.
 
-#### Result Shapes
+### Error reporting
 
-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:
+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
-# 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: [:key1, :key2],
-        status2: [:key3]
-        
-# Failure shapes defined in the same way:
-err_shape :key1, :key2
-err_shape status1: [:key1, :key2],
-        status2: [:key3]
-```
+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:
 
-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.
+* 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
 
-#### Routing & Tracks
+`bin/errors` is done using [GLI](https://davetron5000.github.io/gli/) library,
+run `bin/errors -h` to explore possibilities.
 
-You define side tracks, even nested ones:
+### Performance
 
-```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
-```
+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.
 
-In definition above tracks will not be used because there is no routes to this tracks. You may define routing like this: 
+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.
 
-```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,
-  match_ok(:to_some_track) => :some_track
-
-track :some_track do
-  step :inner_1, match_err => :inner_track # redirect to inner_track on failure result
-  track :inner_track do
-    step :deep_1, match_ok(:some_status) => :outer_2 # you may redirect to steps too
-    step :deep_2
-  end
-  step :inner_2
-end
-
-step :outer_2
-```
+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.
 
-#### Lambda Steps
+And to compare performance overhead between different `flows` abstractions
+and another alternatives a benchmarking CLI was done: `bin/benchmark`.
 
-You can use lambda for in-place step implementation:
+This CLI is done using GLI, run `bin/benchmark -h` to explore possibilities.
 
-```ruby
-step :name, ->(a:, b:, **) { ok(sum: a + b) }
-```
+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.
 
-#### Dependency Injection
+### Documentation
 
-You can override or inject step implementation on initialization:
+Each public API method or module **must** be properly documented with examples
+and motivation behind.
 
-```ruby
-class Summator
-  include Flows::Operation
-  
-  step :sum
-  
-  ok_shape :sum
-end
-
-summator = Summator.new(deps: {
-  sum: ->(a:, b:, **) { ok(sum: a + b) }
-})
-
-summator.call(a: 1, b: 2).unwrap[:sum] # 3
-```
+To run documentation server locally run `bin/docserver`.
 
-#### Wrapping steps
+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.
 
-You can wrap several steps with some logic:
+### Documentation Driven Development
 
-```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
-```
+When you about to do some work, the following guideline can lead to the best
+results:
 
-There is routing limitation when you use wrap:
+* 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
 
-* 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
+Yes, it's TDD approach with documentation step prepended.
 
-## Development
+### Unit test
+
+Each public API method or module **must** be properly tested. Internal modules
+can be tested indirectly through public API.
+
+Test coverage **must** be higher than 95%.
+
+### Commit naming
+
+You **must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Allowed prefixes since `v0.4.0`:
+
+* `feat:` - for new features
+* `fix:` - for bugfixes
+* `perf:` - for performance improvements
+* `refactor:` - for refactoring work
+* `ci:` - updates for CI configuration
+* `docs:` - for documentation update
+
+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)?
+
+So, when you in such situation use the first applicable prefix in the list:
+between `docs` and `refactor` - pick `refactor`.
+
+Also, there is one more special prefix for release commits. Release commit
+messages **must** look like: `release: v0.4.0`.
+
+### Changelog
+
+Starting from `v0.4.0` [keep a changelog](https://keepachangelog.com/en/1.0.0/)
+guideline must be met.
+
+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 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