Update building instructions

Author: pitr-ch

BUILDING.md

@@ -353,19 +353,43 @@ and load the appropriate C extensions.
 No gems should depend on `concurrent-ruby-ext`. Doing so will force C extensions on your users. The
 best practice is to depend on `concurrent-ruby` and let users to decide if they want C extensions.
 
+## Building the gem
+
+### Requirements
+
+* Recent CRuby
+* JRuby, `rbenv install jruby-9.2.17.0`
+* Set env variable `CONCURRENT_JRUBY_HOME` to point to it, e.g. `/usr/local/opt/rbenv/versions/jruby-9.2.17.0`
+* Install Docker, required for Windows builds
+
+### Publishing the Gem
+
+* Update`version.rb`
+* Update the CHANGELOG
+* Update the Yard documentation
+    - Add the new version to `docs-source/signpost.md`. Needs to be done only if there are visible changes in the
+      documentation.
+    - Run `bundle exec rake yard` to update the master documentation and signpost.
+    - Run `bundle exec rake yard:<new-version>` to add or update the documentation of the new version.
+* Commit (and push) the changes.
+* Use `be rake release` to release the gem. It consists
+  of `['release:checks', 'release:build', 'release:test', 'release:publish']` steps. It will ask at the end before
+  publishing anything. Steps can also be executed individually.
+
 ## Maintainers
 
-*   [Petr Chalupa](https://github.com/pitr-ch) (lead maintainer, point-of-contact)
-*   [Jerry D'Antonio](https://github.com/jdantonio) (creator)
-*   [Chris Seaton](https://github.com/chrisseaton)
+*   [Petr Chalupa](https://github.com/pitr-ch) — Lead maintainer, point-of-contact.
+*   [Chris Seaton](https://github.com/chrisseaton) —
+    If Petr is not available Chris can help or poke Petr to pay attention where it is needed.
 
 ### Special Thanks to
 
+*   [Jerry D'Antonio](https://github.com/jdantonio) for creating the gem
 *   [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
 
-and to the past maintainers
+to the past maintainers
 
 *   [Michele Della Torre](https://github.com/mighe)
 *   [Paweł Obrok](https://github.com/obrok)

README.md

@@ -135,7 +135,7 @@ begin
     task :update_readme do
       Dir.chdir __dir__ do
         content = File.read(File.join('README.md')).
-            gsub(/\[([\w ]+)\]\(http:\/\/ruby-concurrency\.github\.io\/concurrent-ruby\/master\/.*\)/) do |_|
+          gsub(/\[([\w ]+)\]\(http:\/\/ruby-concurrency\.github\.io\/concurrent-ruby\/master\/.*\)/) do |_|
           case $1
           when 'LockFreeLinkedSet'
             "{Concurrent::Edge::#{$1} #{$1}}"
@@ -165,9 +165,9 @@ begin
       desc "* of #{name} into subdir #{name}"
       YARD::Rake::YardocTask.new(name) do |yard|
         yard.options.push(
-            '--output-dir', output_dir,
-            '--main', 'tmp/README.md',
-            *common_yard_options)
+          '--output-dir', output_dir,
+          '--main', 'tmp/README.md',
+          *common_yard_options)
         yard.files = ['./lib/concurrent-ruby/**/*.rb',
                       './lib/concurrent-ruby-edge/**/*.rb',
                       './ext/concurrent_ruby_ext/**/*.c',
@@ -189,9 +189,9 @@ begin
     desc "* signpost for versions"
     YARD::Rake::YardocTask.new(:signpost) do |yard|
       yard.options.push(
-          '--output-dir', 'docs',
-          '--main', 'docs-source/signpost.md',
-          *common_yard_options)
+        '--output-dir', 'docs',
+        '--main', 'docs-source/signpost.md',
+        *common_yard_options)
       yard.files = ['no-lib']
     end
 
@@ -206,7 +206,7 @@ begin
               sh 'diff -r docs/ docs-copy/' do |ok, res|
                 unless ok
                   begin
-                    STDOUT.puts 'Command failed. Continue? (y/n)'
+                    STDOUT.puts "yard:#{name} is not properly generated and committed.", "Continue? (y/n)"
                     input = STDIN.gets.strip.downcase
                   end until %w(y n).include?(input)
                   exit 1 if input == 'n'
@@ -242,18 +242,19 @@ namespace :release do
       sh 'test -z "$(git status --porcelain)"' do |ok, res|
         unless ok
           begin
-            STDOUT.puts 'Command failed. Continue? (y/n)'
+            status = `git status --porcelain`
+            STDOUT.puts 'There are local changes that you might want to commit.', status, 'Continue? (y/n)'
             input = STDIN.gets.strip.downcase
           end until %w(y n).include?(input)
           exit 1 if input == 'n'
         end
       end
       sh 'git fetch'
       sh 'test $(git show-ref --verify --hash refs/heads/master) = ' +
-             '$(git show-ref --verify --hash refs/remotes/origin/master)' do |ok, res|
+           '$(git show-ref --verify --hash refs/remotes/origin/master)' do |ok, res|
         unless ok
           begin
-            STDOUT.puts 'Command failed. Continue? (y/n)'
+            STDOUT.puts 'Local master branch is not pushed to origin.', 'Continue? (y/n)'
             input = STDIN.gets.strip.downcase
           end until %w(y n).include?(input)
           exit 1 if input == 'n'
@@ -292,12 +293,12 @@ namespace :release do
 
     task :ask do
       begin
-        STDOUT.puts 'Do you want to publish anything? (y/n)'
+        STDOUT.puts 'Do you want to publish anything now? (y/n)'
         input = STDIN.gets.strip.downcase
       end until %w(y n).include?(input)
       exit 1 if input == 'n'
       begin
-        STDOUT.puts 'Do you want to publish edge? (y/n)'
+        STDOUT.puts 'It will publish `concurrent-ruby`. Do you want to publish `concurrent-ruby-edge`? (y/n)'
         input = STDIN.gets.strip.downcase
       end until %w(y n).include?(input)
       publish_edge = input == 'y'
@@ -326,9 +327,10 @@ namespace :release do
 
     desc '** print post release steps'
     task :post_steps do
-      puts 'Manually: create a release on GitHub with relevant changelog part'
-      puts 'Manually: send email same as release with relevant changelog part'
-      puts 'Manually: tweet'
+      # TODO: (petr 05-Jun-2021) automate and renew the process
+      # puts 'Manually: create a release on GitHub with relevant changelog part'
+      # puts 'Manually: send email same as release with relevant changelog part'
+      # puts 'Manually: tweet'
     end
   end
 end