[GitHub] [accumulo-website] milleruntime commented on a change in pull request #217: Update README and post-commit to use asf-staging

[GitBox <gi...@apache.org>]

milleruntime commented on a change in pull request #217: Update README and post-commit to use asf-staging
URL: https://github.com/apache/accumulo-website/pull/217#discussion_r367951367
 
 

 ##########
 File path: README.md
 ##########
 @@ -1,47 +1,115 @@
 # Apache Accumulo Website
 
-Apache Accumulo uses [Jekyll] to build their website. It is recommended that you
-use [Bundler] to install the necessary dependencies to run and build the website.
+Apache Accumulo uses [Jekyll] to build its website and [Bundler] to manage its
+gem dependencies.
 
-## Install Bundler and dependencies
+Most commands on this page assume you have cloned your fork of the site
+repository on GitHub and changed your working directory to that clone. They
+also assume you have a remote named 'upstream' added to your clone that points
+to the one at ASF's GitHub.
 
-Ruby is required to use Bundler so first make sure you have Ruby on your machine.  If you are using
-an OS packaged version of Ruby, you will have to also install the ruby-dev (Ubuntu) or
-ruby-devel (Fedora) package as well. Depending on your OS, you may also need other packages, such as
-ruby-full, make, gcc, nodejs, build-essentials, or patch.
+```bash
+git clone https://github.com/<yourusername>/accumulo-website
+cd accumulo-website
+git remote add upstream https://github.com/apache/accumulo-website
+```
+
+## Install Ruby, RubyGems, Bundler, and other Dependencies
+
+Ruby and RubyGems are required to use Jekyll and Bundler, so first make sure
+you have those on your machine.
+
+If you are using an OS packaged version of Ruby, you may also need to install
+the ruby-dev (Ubuntu) or ruby-devel (Fedora) package as well to build any
+native code for gems that are installed later. Installing these will also
+ensure your system's RubyGems package is installed. Depending on your OS, you
+may also need other packages to install/build gems, such as ruby-full, make,
+gcc, nodejs, build-essentials, or patch.
+
+Once Ruby, RubyGems, and any necessary native tools are installed, you are
+ready to install [Bundler] to manage the remaining RubyGem dependencies.
+Bundler is included in Ruby 2.6 and later as a default gem, so installing it
+may not be needed.
+
+Because we use [Bundler] to install specific versions of gems, it is not
+recommended to use an OS packaged version of gems other than what comes
+built-in. If you are using an OS packaged version of Ruby, it is __strongly__
+recommended to avoid `sudo` when installing additional gems, in order to avoid
+conflicting with your system's package-managed installation. Instead, you can
+specify a `GEM_HOME` directory for installing gems locally in your home
+directory. You can do this in your `$HOME/.bashrc` file or other appropriate
+place for your environment:
 
 Review comment:
   Nice!  This burned me bad

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services