chore: documentation and CI updates

Author: ffloyd

.github/workflows/build.yml

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

.rubocop.yml

@@ -54,3 +54,7 @@ Style/CaseEquality:
 
 Naming/RescuedExceptionsVariableName:
   PreferredName: err
+
+Style/Documentation:
+  Exclude:
+    - 'lib/flows/shared_context_pipeline/step.rb' # false positive here

README.md

@@ -4,11 +4,13 @@
 [![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)
 
-**Right now library is under heavy development. Version 0.4.0 will be the first stable API candidate. And version 1.0.0 is coming after.**
-
 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.
+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.
 
@@ -17,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.4'
 ```
 
 And then execute:
@@ -32,7 +34,173 @@ Or install it yourself as:
 gem install flows
 ```
 
-_Rest of documentation will be here when v0.4.0 be ready._ Stay tuned.
+## Usage & Documentation
+
+* [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.
+
+## Development
+
+`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.
+
+### Anyone can make Flows even better
+
+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.
+
+### [Lefthook](https://github.com/Arkweid/lefthook) as a git hook manager
+
+Installation on MacOS via Homebrew:
+
+```sh
+brew install Arkweid/lefthook/lefthook
+```
+
+Activation (in the root of the repo):
+
+```sh
+lefthook install
+```
+
+Run hook manually:
+
+```sh
+lefthook run pre-commit
+```
+
+Please, never turn off pre-commit hook.
+
+### Rubocop as the first linter
+
+[Rubocop](https://docs.rubocop.org/en/stable/) in this setup is responsible for:
+
+* 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/))
+
+Rubocop config for library and RSpec files should be close to standard one only
+with minor amount of exceptions.
+
+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.
+
+Rubocop Metrics (ABC-size, method/class length, etc) must not be eased
+globally. Never.
+
+### Reek as the second linter
+
+[Ruby Reek](https://github.com/troessner/reek) is a very aggressive linter that
+forces you to do a clean OOP design.
+
+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.
+
+### Rest of the linters
+
+* [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)
+
+### Default Rake task and CI
+
+Default rake task (`bundle exec rake`) executes the following checks:
+
+* Rubocop
+* Ruby Reek
+* RSpec
+* Spellcheck (forspell)
+* MarkdownLint (mdl)
+
+CI is also performing default Rake task. So, if you want to reproduce CI error
+locally - just run `bundle exec rake`.
+
+Default Rake task is also executed as a pre-push git hook.
+
+### Error reporting
+
+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.
+
+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:
+
+* 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
+
+`bin/errors` is done using [GLI](https://davetron5000.github.io/gli/) library,
+run `bin/errors -h` to explore possibilities.
+
+### Performance
+
+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.
+
+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.
+
+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.
+
+And to compare performance overhead between different `flows` abstractions
+and another libraries alternatives a benchmarking CLI was done: `bin/benchmark`.
+
+This CLI is done using GLI, run `bin/benchmark -h` to explore possibilities.
+
+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.
+
+### Documentation
+
+Each public API method or module **must** be properly documented with examples
+and motivation behind.
+
+To run documentation server locally run `bin/docserver`.
+
+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.
+
+### Unit test
+
+Each public API method or module **must** be properly tested. Internal modules
+can be tested indirectly through public API.
+
+### Commit naming
+
+You **must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.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
+
+The project strictly follows [SemVer](https://semver.org/spec/v2.0.0.html).
+
+After `v1.0.0` even smallest backward incompatible change will bump major
+version. _No exceptions._
 
 ## Readme TODO: list of tasks to accomplish before
 

forspell.dict

@@ -12,3 +12,6 @@ postprocessor
 upcase
 fixpoint
 Megatron
+homebrew
+MDL
+forspell

lefthook.yml

@@ -14,3 +14,8 @@ pre-commit:
     forspell:
       glob: "{*.md,*.rb}"
       run: bundle exec forspell {staged_files}
+
+pre-push:
+  commands:
+    test:
+      run: bundle exec rake

lib/flows.rb

@@ -1,11 +1,5 @@
 # Namespace for all the classes and modules of the library.
 #
-# The most important ones are:
-#
-# * {Flows::Result}
-# * {Flows::Railway}
-# * TODO: fill this list
-#
 # @since 0.4.0
 module Flows
   # Base class for all the library's errors.

lib/flows/contract.rb

@@ -274,8 +274,8 @@ module Flows
   # But you should avoid constructing static contracts at runtime -
   # it's better to instantiate them during loading time (by putting it into constant, for example).
   #
-  # TODO: Some {SharedContextPipeline} plugins will add DSL for contracts.
-  # So, you don't need to invent anything to use contracts with shared context pipelines.
+  # {Flows::Plugin::OutputContract} in combination with {SharedContextPipeline} will add DSL for contracts.
+  # So, you don't need to invent anything to use output contracts with shared context pipelines.
   #
   # ## Private helper methods
   #

lib/flows/flow.rb

@@ -22,7 +22,7 @@ module Flows
   # > From any state, there is only one transition for any allowed input.
   #
   # So, we represent DFSM states as {Node}s. Each {Node}, basing on input (input includes execution context also)
-  # performs some side effects and returns output and next {Node} (DFSM state).
+  # performs some side effects and returns output and next {Node} name (DFSM state).
   #
   # Side effects here can be spitted into two types:
   #

lib/flows/plugin.rb

@@ -1,6 +1,8 @@
 module Flows
   # Namespace for class behaviour extensions.
   #
+  # Feel free to use it to empower your abstractions.
+  #
   # @since 0.4.0
   module Plugin
   end

lib/flows/plugin/dependency_injector.rb

@@ -41,7 +41,7 @@ module Plugin
     # @example
     #
     #     class MyClass
-    #       include Flows::Util::DepencyInjector
+    #       include Flows::Plugin::DependencyInjector
     #
     #       dependency :logger, required: true
     #       dependency :name, default: 'Boris', type: String # by default dependency is optional.

lib/flows/shared_context_pipeline/step.rb

@@ -1,6 +1,3 @@
-# rubocop:disable Style/Documentation
-# ^^^ it is false positive here
-
 module Flows
   class SharedContextPipeline
     EMPTY_ARRAY = [].freeze
@@ -47,5 +44,3 @@ def to_node(pipeline_class)
     )
   end
 end
-
-# rubocop:enable Style/Documentation