whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From curc...@apache.org
Subject [whimsy] branch master updated: Improve links and config docs; update some versions to current
Date Sat, 18 May 2019 13:47:47 GMT
This is an automated email from the ASF dual-hosted git repository.

curcuru pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/whimsy.git


The following commit(s) were added to refs/heads/master by this push:
     new 179ebc6  Improve links and config docs; update some versions to current
179ebc6 is described below

commit 179ebc6cb7b1d9b24aa6b2a10361a834a2b29afb
Author: Shane Curcuru <asf@shanecurcuru.org>
AuthorDate: Sat May 18 09:47:39 2019 -0400

    Improve links and config docs; update some versions to current
---
 DEVELOPMENT.md | 18 ++++++++++--------
 MACOSX.md      | 23 +++++++++++++----------
 2 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index bc98e7e..22ac8a7 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -61,16 +61,17 @@ Setup Whimsy Locally
 =====
 
 This section is for those desiring to run a whimsy tool on their own machine.
-[See below for deploying](#advanced-configuration) in a Docker container or a Vagrant VM.
+[See below for deploying](#advanced-configuration) in a Docker container or a Vagrant VM,
+or read the [detailed MACOSX setup steps](MACOSX.md).
 
-1. **Setup ruby 1.9.3 or higher.**  Verify with `ruby -v`.
+1. **Setup ruby 2.3.x or higher.**  Verify with `ruby -v`.
    If you use a system provided version of Ruby, you may need to prefix
    certain commands (like gem install) with `sudo`.  Alternatives to using
    the system provided version include using a Ruby version manager like
    `rbenv` or `rvm`.  Rbenv generally requires you to be more aware of what you
    are doing (e.g., the need for rbenv shims).  Rvm tends to be more of a set
    and forget operation, but it tends to be more system intrusive (e.g. aliasing
-   'cd' in bash).  Note the Whimsy server currently uses **ruby 2.5+**.
+   'cd' in bash).  Note the Whimsy server currently uses **ruby 2.4.1+**.
 
     For more information:
 
@@ -83,7 +84,7 @@ This section is for those desiring to run a whimsy tool on their own machine.
 
    `gem install whimsy-asf bundler`  (mail and listen may be needed too)
 
-   - If you're using Mac OS El Capitan or higher, you may need to do this:
+   - If you're using [Mac OS El Capitan or higher](MACOSX.md), you may need to do this:
 
    `sudo gem install bundler -n /usr/local/bin`
 
@@ -143,7 +144,8 @@ This section is for those desiring to run a whimsy tool on their own machine.
 
    It should print out an HTML page with current board members.
    See comments in the `board.rb` file for running the script as a 
-   standalone server to view in a local web browser.
+   standalone server to view in a local web browser.  This test script 
+   verifies the environment used by many, but not all, Whimsy tools.
 
 6. **Configure mail sending** :mailbox_with_mail: (_optional_):
 
@@ -189,7 +191,7 @@ See also [How To: Keep Your Local Environment Updated](#how-to-keep-your-local-e
 1. CGI applications can be run from a command line, and produce output to
    standard out.  If you would prefer to see the output in a browser, you
    will need to have a web server configured to run CGI, and a small CGI
-   script which runs your application.  For CGI scripts that make use of
+   script which runs your application.  For CGI scripts (chmod 755) that make use of
    wunderbar, this script can be generated and installed for you by
    passing a `--install` option on the command, for example:
 
@@ -231,7 +233,7 @@ a virtual host, complete with authentication:
       Enable the modules you need using `a2ensite`.  Restart the Apache httpd
       web server using `service apache2 restart`.
 
-   b. On Mac OS/X, place the generated vhost definition into
+   b. [On Mac OS/X](MACOSX.md), place the generated vhost definition into
       `/private/etc/apache2/extra/httpd-vhosts.conf`.  Edit
       `/etc/apache2/httpd.conf` and uncomment out the line that includes
       `httpd-vhosts.conf`, and
@@ -297,7 +299,7 @@ just when running into temp dirs (typically to modify them and commit
 changes).  If you have trouble using the existing [ASF::SVN classes](lib/whimsy/asf/svn.rb)

 class to access files from Subversion on the server, then check:
 
-- Default SVN checkouts: [repository.yml](repository.yml)
+- Default SVN checkout mappings: [repository.yml](repository.yml)
 
 ### How To: Keep Your Local Environment Updated
 
diff --git a/MACOSX.md b/MACOSX.md
index 7740d0c..83d62ee 100644
--- a/MACOSX.md
+++ b/MACOSX.md
@@ -12,9 +12,10 @@ Install Homebrew
 
 Homebrew is a package manager for OSX, which is used to install other tools.
 Follow the instructions from [brew.sh](http://brew.sh/). You might
-have to change shells if you are using csh. Bash works fine.
+have to change shells if you are using csh. Bash works fine.  Be sure to 
+read the Homebrew prerequisites; you may need part(s) of Apple's XCode.
 
-Verify using:
+Verify minimum version installed using:
 
 ```
 $ brew --version
@@ -28,9 +29,9 @@ Update using:
 $ brew update
 ```
 
-Homebrew has removed options we need from two of the formulas we need.
+Homebrew has (as of 2019) removed options we need from two of the formulas we need.
 Fix formulas for `openldap` and `apr-util` to make the required options standard.
-Note that we have to remove the bottles otherwise a version of the software is downloaded
that does not include the options we require.
+Note that we have to remove the bottles otherwise a version of the software is downloaded
that does not include the options we require.  You will need to fix these formulas and re-update
brew.
 
 ```
 $ cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula
@@ -109,7 +110,8 @@ ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]
 ```
 
 If you don't see 2.3.1 or later, run `hash -r` and try again.  If you previously
-installed ruby via brew, you may need to run `brew upgrade ruby` instead. 
+installed ruby via brew, you may need to run `brew upgrade ruby` instead; 
+if you use rbenv or rvm, make sure they get the expected ruby version. 
 
 Install:
 
@@ -118,7 +120,7 @@ $ brew install rbenv
 $ rbenv install 2.5.1
 ```
 
-Use `ln -s` in `/usr/local/bin` for both `ruby` and `gem` pointing to the locations
+You may need to use `ln -s` in `/usr/local/bin` for both `ruby` and `gem` pointing to the
locations
 where `rbenv` installed ruby in your home directory
 
 ```
@@ -126,7 +128,7 @@ ln -s /usr/local/bin/ruby /Users/${user}/.rbenv/versions/2.5.1/bin/ruby
 ln -s /usr/local/bin/gem /Users/${user}/.rbenv/versions/2.5.1/bin/gem
 ```
 
-Upgrade Node.js
+Install Node.js
 ---------------
 
 Install:
@@ -190,7 +192,7 @@ Clone the Whimsy code
 ------------
 
 Depending on whether or not you have a GitHub account ([Apache committer setup](https://gitbox.apache.org/)),

-run one of the following:
+use GitHub Desktop or run one of the following:
 
 ```
 git clone git@github.com:apache/whimsy.git
@@ -208,7 +210,8 @@ git remote add github git@github.com:apache/whimsy.git
 git remote add asf https://gitbox.apache.org/repos/asf/whimsy.git
 ```
 
-Establish a link to this repository in a known location:
+Establish a link to this repository in a known location - this step is 
+optional to do basic work but required for a number of tools:
 
 ```
 cd whimsy
@@ -352,7 +355,7 @@ Restart Apache httpd using:
 apachectl restart
 ```
 
-Additional Notes:
+**Additional Notes:**
 
  * `sudo lsof -i:8080` may be helpful should you find that another process
    already has port 8080 open.


Mime
View raw message