Update documentation

Author: pitr-ch

.github/CONTRIBUTING.md

@@ -1,10 +1,12 @@
 # Contributing to Concurrent Ruby
 
-You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby) or on the [mailing list](https://groups.google.com/forum/#!forum/concurrent-ruby).
+You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby).
 
 #### Find Something to Work on
 
-If you want to contribute but aren't sure what to work on, we keep our list of current todos on our [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).
+If you want to contribute but aren't sure what to work on, there are tasks marked with [**looking-for-contributor**](https://github.com/ruby-concurrency/concurrent-ruby/issues?q=is%3Aissue+is%3Aopen+label%3Alooking-for-contributor) label. Complete list of tasks can be found on [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). We appreciate your help. 
+
+Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).
 
 #### Fork the Project
 
@@ -52,12 +54,12 @@ Make sure that `bundle exec rake` completes without errors.
 
 #### Follow the Guidelines
 
-There are a few very strong guidelines which we follow when adding features. Submissions which fail to follow these guidelines will likely be rejected or will require modification before acceptance.
+There are a few guidelines which we follow when adding features. Consider that submissions which do not follow these guidelines will require modification before acceptance.
 
 * **No downstream dependencies:** Concurrent Ruby is a foundational library used by major projects like [Rails](http://rubyonrails.org/). Our downstream dependencies become everyone's dependencies. Because we cannot guarantee that downstream projects meet our development standards, it's best for everyone if we simply aviod dependencies.
 * **Do not monkey patch Ruby:** Changing Ruby for our convenience affects every gem in every project that uses Concurrent Ruby. Monkey patching Ruby may change the behavior of other libraries in unexpected ways and destabilize projects which depend on us.
 * **Do not pollute the global namespace:** Putting all our code within the `Concurrent` module guarantees that there will be no namespace collisions with other gems or the projects which depend on us.
-* **No global varaibles:** Global state should be kept to an absolute minimum. When it's necessary, add it to the global gem configuration.
+* **No global state:** We are removing global state we have.
 * **Minimize per-object configuration:** Ruby makes programmers happy. One of Ruby's charms is its simplicity. Concurrent Ruby aims to mirror this simplicity. Advanced configuration options are encouraged when they provide value, but every abstraction should have reasonable defaults that meet the needs of most users.
 * **Provide explicit behavior and guarantees:** Our APIs should be concrete and clearly define what they do (and don't do). Users of Concurrent Ruby should never be surprised by unexpected behavior or be given guarantees we cannot keep.
 * **Eat our own dog food:** Concurrent Ruby provides a rich set of low-level (internal and public) classes which provide strong guarantees and are optimized for performance across platforms. All our high-level abstractions should make use of these tools.
@@ -102,20 +104,13 @@ git rebase upstream/master
 git push origin my-feature-branch -f
 ```
 
-#### Update CHANGELOG Again
+#### Update CHANGELOG
 
 Update the [CHANGELOG](CHANGELOG.md) with a description of what you have changed.
 
-Amend your previous commit and force push the changes.
-
-```
-git commit --amend
-git push origin my-feature-branch -f
-```
-
 #### Check on Your Pull Request
 
-Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues and amend your commit as described above.
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues (amending your commit).
 
 Please note that testing concurrency is hard. Very hard. We have a few tests that occasionally fail due (mostly) to incorrect synchronization within the test itself. If everything passes locally but you see an error on CI, it's possibly you've become victim to one of the tests. Don't worry, the Concurrent Ruby team reviews the tests output of all failed CI runs and will let you know if the failing test is unrelated to your commit.
 

CODE_OF_CONDUCT.md

@@ -1,22 +1,71 @@
-# Contributor Code of Conduct
+# Contributor Covenant Code of Conduct
 
-As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+## Our Pledge
 
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project
+a harassment-free experience for *everyone*.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the project
+* Showing empathy towards other project members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery
-* Personal attacks
-* Trolling or insulting/derogatory comments
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing other's private information, such as physical or electronic addresses, without explicit permission
-* Other unethical or unprofessional conduct.
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project. Examples of
+representing a project include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at `[email protected]`. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
 
-This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+## Attribution
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
 
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

README.md

@@ -20,20 +20,23 @@ and classic concurrency patterns.
 
 The design goals of this gem are:
 
-*   Be an 'unopinionated' toolbox that provides useful utilities without
-    debating which is better or why
+*   Be an 'unopinionated' toolbox that provides useful utilities without debating which is better 
+    or why
 *   Remain free of external gem dependencies
 *   Stay true to the spirit of the languages providing inspiration
 *   But implement in a way that makes sense for Ruby
 *   Keep the semantics as idiomatic Ruby as possible
 *   Support features that make sense in Ruby
 *   Exclude features that don't make sense in Ruby
 *   Be small, lean, and loosely coupled
+*   Thread-safety
+*   Backward compatibility
 
 ## Contributing
 
-**This gem depends on contributions and we appreciate your help. Would you like to contribute? 
-Great! Have a look at 
+**This gem depends on 
+[contributions](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors) and we 
+appreciate your help. Would you like to contribute? Great! Have a look at 
 [issues with `looking-for-contributor` label](https://github.com/ruby-concurrency/concurrent-ruby/issues?q=is%3Aissue+is%3Aopen+label%3Alooking-for-contributor).**
 
 ## Thread Safety
@@ -55,15 +58,31 @@ other Ruby library, many of which support the mantra of
 Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and
 immutable variable types and data structures.
 
+We've also initiated discussion to document [memory model](doc/synchronization.md) of Ruby which 
+would provide consistent behaviour and guarantees on all three of the main Ruby interpreters 
+(MRI/CRuby, JRuby, Rubinius, TruffleRuby).
+
 ## Features & Documentation
 
 **The primary site for documentation is the automatically generated 
 [API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html) which is up to 
 date with latest release.** This readme matches the master so may contain new stuff not yet 
 released.
 
-We also have a [mailing list](http://groups.google.com/group/concurrent-ruby) 
-and [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).
+We also have a [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).
+
+### Versioning
+
+*   `concurrent-ruby` uses [Semantic Versioning](http://semver.org/)
+*   `concurrent-ruby-ext` has always same version as `concurrent-ruby`
+*   `concurrent-ruby-edge` will always be 0.y.z therefore following 
+    [point 4](http://semver.org/#spec-item-4) applies *"Major version zero 
+    (0.y.z) is for initial development. Anything may change at any time. The 
+    public API should not be considered stable."* However we additionally use 
+    following rules:
+    *   Minor version increment means incompatible changes were made
+    *   Patch version increment means only compatible changes were made
+
 
 #### General-purpose Concurrency Abstractions
 
@@ -191,17 +210,17 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
 
 *   [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html): Implements 
     the Actor Model, where concurrent actors exchange messages.
-    Status: Partial documentation and tests; depends on new future/promise framework; stability is good.
+    *Status: Partial documentation and tests; depends on new future/promise framework; stability is good.*
 *   [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/Channel.html):
     Communicating Sequential Processes ([CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes)).
     Functionally equivalent to Go [channels](https://tour.golang.org/concurrency/2) with additional
     inspiration from Clojure [core.async](https://clojure.github.io/core.async/).
-    Status: Partial documentation and tests.
+    *Status: Partial documentation and tests.*
 *   [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
 *   [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
-    Status: will be moved to core soon.
+    *Status: will be moved to core soon.*
 *   [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LockFreeStack.html)
-    Status: missing documentation and tests.
+    *Status: missing documentation and tests.*
 
 ## Supported Ruby versions
 
@@ -220,6 +239,8 @@ Everything within this gem can be loaded simply by requiring it:
 require 'concurrent'
 ```
 
+*Requiring only specific abstractions from Concurrent Ruby is not yet supported.*
+
 To use the tools in the Edge gem it must be required separately:
 
 ```ruby
@@ -295,19 +316,22 @@ best practice is to depend on `concurrent-ruby` and let users to decide if they
 
 ## Maintainers
 
-*   [**Petr Chalupa**](https://github.com/pitr-ch) (lead maintainer)
+*   [Petr Chalupa](https://github.com/pitr-ch) (lead maintainer, point-of-contact)
 *   [Jerry D'Antonio](https://github.com/jdantonio) (creator)
-*   [Michele Della Torre](https://github.com/mighe)
 *   [Chris Seaton](https://github.com/chrisseaton)
-*   [Paweł Obrok](https://github.com/obrok)
-*   [Lucas Allan](https://github.com/lucasallan)
 
 ### Special Thanks
 
 *   [Brian Durand](https://github.com/bdurand) for the `ref` gem
 *   [Charles Oliver Nutter](https://github.com/headius) for the `atomic` and `thread_safe` gems
 *   [thedarkone](https://github.com/thedarkone) for the `thread_safe` gem
 
+### Maintainer of the past
+
+*   [Michele Della Torre](https://github.com/mighe)
+*   [Paweł Obrok](https://github.com/obrok)
+*   [Lucas Allan](https://github.com/lucasallan)
+
 ## License and Copyright
 
 *Concurrent Ruby* is free software released under the 

lib-edge/concurrent/actor.rb

@@ -12,7 +12,7 @@ module Concurrent
 
   # {include:file:doc/actor/main.md}
   # @api Actor
-  # @!macro edge_warning
+  # @!macro warn.edge
   module Actor
 
     require 'concurrent/actor/type_check'

lib-edge/concurrent/channel.rb

@@ -9,7 +9,7 @@
 module Concurrent
 
   # {include:file:doc/channel.md}
-  # @!macro edge_warning
+  # @!macro warn.edge
   class Channel
     extend Forwardable
     include Enumerable

lib-edge/concurrent/edge.rb

@@ -15,7 +15,7 @@ module Concurrent
   # features should remain in this module until merged into the core gem. This
   # will prevent namespace collisions.
   #
-  # @!macro [attach] edge_warning
+  # @!macro [attach] warn.edge
   #   @api Edge
   #   @note **Edge Features** are under active development and may change frequently.
   #

lib-edge/concurrent/edge/cancellation.rb

@@ -14,7 +14,7 @@ module Concurrent
   #   end
   #   sleep 0.1
   #   cancellation.cancel # Stop the thread by cancelling
-  # @!macro edge_warning
+  # @!macro warn.edge
   class Cancellation < Synchronization::Object
     safe_initialization!
 
@@ -133,7 +133,7 @@ def initialize(cancel)
       end
     end
 
-    # FIXME (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
+    # TODO (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
     # TODO (pitr-ch 27-Mar-2016): examples (scheduled to be cancelled in 10 sec)
   end
 end

lib-edge/concurrent/edge/lock_free_linked_set.rb

@@ -18,7 +18,7 @@ module Edge
     #
     # This algorithm is a variation of the Nonblocking Linked Set found in
     # 'The Art of Multiprocessor Programming' by Herlihy and Shavit.
-    # @!macro edge_warning
+    # @!macro warn.edge
     class LockFreeLinkedSet
       include Enumerable
 

lib-edge/concurrent/edge/processing_actor.rb

@@ -13,7 +13,7 @@ module Concurrent
   #     values = actors.map(&:termination).map(&:value)
   #     values[0,5]                                        # => [1, 2, 3, 4, 5]
   #     values[-5, 5]                                      # => [49996, 49997, 49998, 49999, 50000]
-  # @!macro edge_warning
+  # @!macro warn.edge
   class ProcessingActor < Synchronization::Object
     # TODO (pitr-ch 18-Dec-2016): (un)linking, bidirectional, sends special message, multiple link calls has no effect,
     # TODO (pitr-ch 21-Dec-2016): Make terminated a cancellation token?

lib-edge/concurrent/edge/throttle.rb

@@ -48,7 +48,7 @@ module Concurrent
   # @!macro throttle.example.throttled_future
   # @!macro throttle.example.throttled_future_chain
   # @!macro throttle.example.throttled_block
-  # @!macro edge_warning
+  # @!macro warn.edge
   class Throttle < Synchronization::Object
     # TODO (pitr-ch 21-Dec-2016): consider using sized channel for implementation instead when available