Merge pull request #1528 from LadyMozzarella/958-877-readme-updates

Add relevant discussion links from issues to Readmes, Clean up a few Readmes

frameworks/CSharp/README.md

@@ -1,26 +1,30 @@
-# Limited Travis-CI Verification 
+# C# (CSharp) Frameworks
 
-Because the verification system uses the linux-only Travis-CI
-service, verifying Windows-only tests has to be done manually
-and is very time consuming. 
+The information below contains information specific to C#. 
+For further guidance, review the 
+[documentation](http://frameworkbenchmarks.readthedocs.org/en/latest/).
 
-Consider including an additional test, likely based on Mono and 
-FastCGI (e.g. xsp), that can run on Linux when submitting a new
-framework. This will drastically speed up our ability to merge
-in your pull request. 
+## Infrastructure Software Versions
 
-# Different Mono Versions
+* [Mono C# compiler latest version](http://www.mono-project.com/docs/about-mono/languages/csharp/)
+
+## Adding a New C# Framework
+
+### Different Mono Versions
 
 While we have not currently run into the need to have multiple 
 simultaneous Mono installations, it is [possible](http://www.mono-project.com/docs/compiling-mono/parallel-mono-environments/)
 
-# Debugging Mono + NuGet
+### Debugging Mono + NuGet
 
-Mono understands an environment variable `MONO_LOG_LEVEL=debug` that is helpful for checking that 
+Mono understands an environment variable `MONO_LOG_LEVEL=debug` 
+that is helpful for checking that 
 mono is properly working e.g. loading necessary DLL's. 
 
-Most NuGet commands understand a `-Verbosity` flag, which is great because the error messages can be completely
-mystifying when working with Mono too. Use this would enable all the debugging you can: 
+Most NuGet commands understand a `-Verbosity` flag, which is 
+great because the error messages can be completely
+mystifying when working with Mono too. Use this would enable 
+all the debugging you can: 
 
     $ MONO_LOG_LEVEL=debug mono NuGet2.exe update -Verbosity "detailed" -self
 
@@ -28,10 +32,38 @@ For example, aspnet was constantly failing with this message:
     
     Could not connect to the feed specified at 'https://www.nuget.org/api/v2/'. Please verify that the package source (located in the Package Manager Settings) is valid and ensure your network connectivity.`. 
 
-Using `-Verbosity "detailed"` shows that the real error is actually a Mono library problem, as so: 
+Using `-Verbosity "detailed"` shows that the real error is 
+actually a Mono library problem, as so: 
 
     System.InvalidOperationException: Could not connect to the feed specified at 'https://www.nuget.org/api/v2/'. Please verify that the package source (located in the Package Manager Settings) is valid and ensure your network connectivity. ---> System.Net.WebException: libMonoPosixHelper.so ---> System.DllNotFoundException: libMonoPosixHelper.so
       at (wrapper managed-to-native) System.IO.Compression.DeflateStreamNative:CreateZStream (System.IO.Compression.CompressionMode,bool,System.IO.Compression.DeflateStreamNative/UnmanagedReadOrWrite,intptr)
       <snip>
 
 More helpful info is [here](http://www.mono-project.com/docs/advanced/pinvoke/dllnotfoundexception/), [here](http://docs.nuget.org/docs/reference/command-line-reference)
+
+### Limited Travis-CI Verification 
+
+Because the verification system uses the linux-only Travis-CI
+service, verifying Windows-only tests has to be done manually
+and is very time consuming. 
+
+Consider including an additional test, likely based on Mono and 
+FastCGI (e.g. xsp), that can run on Linux when submitting a new
+framework. This will drastically speed up our ability to merge
+in your pull request. 
+
+## Get Help
+
+### C# Experts
+
+_There aren't any C# experts listed, yet. If you're an expert, add yourself!_
+
+### C# Community
+
+_We don't have any community links added. Add some to help further guide 
+future contirbutors._
+
+### Resources
+
+_If you stumble upon some helpful links or discussions, add them 
+for easy reference for future contributors._

frameworks/CSharp/nancy/README.md

@@ -1,21 +1,54 @@
-# Nancy on Mono and Windows
+# Nancy on Mono and Windows Benchmarking Test
 
-## Tests
+The information below contains information specific to Nancy on Mono and Windows. 
+For further guidance, review the 
+[documentation](http://frameworkbenchmarks.readthedocs.org/en/latest/). 
+Also note the additional information provided in the [CSharp README](../).
 
-### JSON
+This is the Nancy on Mono and Windows portion of a [benchmarking test suite](../../) 
+comparing a variety of web platforms.
 
-* `http://localhost:8080/json`
+## Infrastructure Software Versions
 
----
+**Language**
+
+* C# 5.0
+
+**Platforms**
+
+* .NET Framework 4.5 (Windows)
+* Mono 3.0.X (Linux)
+
+**Web Servers**
+
+* IIS 8 (Windows)
+* nginx 1.4.0 & XSP FastCGI (Linux)
+
+**Web Stack**
+
+* ASP.NET 4.5
+* Nancy 0.17.1 (custom build to address this issue: https://github.com/NancyFx/Nancy/pull/1100)
+
+**Databases**
+
+* MySQL Connector/Net
+
+**Developer Tools**
+
+* Visual Studio 2012
+
+## Paths & Source for Tests
+
+* [JSON Serialization](NancyModules/JsonModule.cs): "/json"
 
 ### Nancy - Dapper (ORM)
 
-**MySQL**
+* [Single Database Query](NancyModules/DbModule.cs): "/db"
+* [Multiple Database Queries](NancyModules/DbModule.cs): "/db/10"
 
-* `http://localhost:8080/db`
-* `http://localhost:8080/db/10`
+## Add a New Test for Nancy
 
-## Mono Installation
+### Mono Installation
 
     sudo apt-get install build-essential autoconf automake libtool zlib1g-dev git
 
@@ -36,31 +69,18 @@
     make
     sudo make install
 
-## Versions
-
-**Language**
-
-* C# 5.0
-
-**Platforms**
-
-* .NET Framework 4.5 (Windows)
-* Mono 3.0.X (Linux)
-
-**Web Servers**
-
-* IIS 8 (Windows)
-* nginx 1.4.0 & XSP FastCGI (Linux)
+## Get Help
 
-**Web Stack**
+### Experts
 
-* ASP.NET 4.5
-* Nancy 0.17.1 (custom build to address this issue: https://github.com/NancyFx/Nancy/pull/1100)
+_There aren't any experts listed, yet. If you're an expert, add yourself!_
 
-**Databases**
+### Community
 
-* MySQL Connector/Net
+* Chat in the [#NancyFX](https://jabbr.net/account/login?ReturnUrl=%2F#/rooms/nancyfx) room on JabbR.
+* #NancyFx on Twitter.
 
-**Developer Tools**
+### Resources
 
-* Visual Studio 2012
+* [Source Code](https://github.com/NancyFx/Nancy)
+* [Issue #877 - Discussion regarding Event2.dll and Global.asax thread configuration](https://github.com/TechEmpower/FrameworkBenchmarks/issues/877)

frameworks/Java/README.md

@@ -1,7 +1,20 @@
-# Installation and Bash Configuration
+# Java Frameworks
 
-In order to declare that your framework requires Java, you should have an `install.sh`
-that contains at least
+The information below contains information specific to Java. 
+For further guidance, review the 
+[documentation](http://frameworkbenchmarks.readthedocs.org/en/latest/).
+
+## Infrastructure Software Versions
+
+* Java 7
+* Java 8
+
+## Adding a New Java Framework
+
+### Installation and Bash Configuration
+
+In order to declare that your framework requires Java, you 
+should have an `install.sh` that contains at least
 
     #!/bin/bash
 
@@ -9,7 +22,20 @@ that contains at least
 
 This installs the OpenJDK 7 JVM.
 
-Frameworks can also choose to install Oracle Java 8 JVM by declaring a dependency on "java8"
-instead of java. In order to use Java 8 JVM frameworks need to add the following line in their "setup.sh" file:
+Frameworks can also choose to install Oracle Java 8 JVM by 
+declaring a dependency on "java8" instead of java. In order 
+to use Java 8 JVM frameworks need to add the following line 
+in their "setup.sh" file:
+
+    export JAVA_HOME=/opt/java8
+
+## Get Help
+
+### Java Experts
+
+_There aren't any experts listed, yet. If you're an expert, 
+add yourself!_
+
+### Interesting Links
 
-export JAVA_HOME=/opt/java8
+* [Surprise! Java is fastest for server-side Web apps](http://www.infoworld.com/article/2609675/java/surprise--java-is-fastest-for-server-side-web-apps.html)

frameworks/PHP/README.md

@@ -1,10 +1,20 @@
-# PHP Version
+# PHP Frameworks
+
+The information below contains information specific to PHP. 
+For further guidance, review the 
+[documentation](http://frameworkbenchmarks.readthedocs.org/en/latest/).
+
+## Infrastructre Software Versions
+
+### PHP Version
 
 [Currently this toolset runs PHP 5.5.17](https://github.com/TechEmpower/FrameworkBenchmarks/blob/master/toolset/setup/linux/languages/php.sh). At the moment all PHP-based frameworks use the 
 same PHP version, but we are open to receiving a pull request
 that enables supporting multiple versions. 
 
-# PHP Acceleration and Caching
+## Adding New PHP-based Frameworks
+
+### PHP Acceleration and Caching
 
 Caching the output of the PHP bytecode compiler is expressly 
 allowed by this benchmark. As we use PHP 5.5, which comes 
@@ -43,7 +53,7 @@ easier to use systems such as APCu.
 
 Ask if you are not certain.
 
-# Adding New PHP-based Frameworks
+## Install.sh and Setup.sh Files
 
 Most PHP frameworks use `fw_depends php nginx composer` in their `install.sh` file, 
 which installs PHP, Nginx, and Composer automatically. They then create a `setup.sh`
@@ -75,7 +85,7 @@ When using `php`, `php-fpm`, or other binaries, always use the full path
 to the binary, e.g. instead of `php <command>`, 
 use `/home/foo/FrameworkBenchmarks/installs/php-5.5.17/bin/php <your command>`. 
 
-# Dependency Management Using Composer
+### Dependency Management Using Composer
 
 Many PHP apps use [Composer](https://getcomposer.org/) for dependency management, 
 which greatly simplifies downloading the framework, loading the framework, and 
@@ -90,7 +100,7 @@ The lock file is a fully-defined file generated by composer 1) reading your JSON
 dependencies 3) downloading a lot of data from Github. Without this lock file, composer takes 2-3x 
 longer to run, and it can even halt and require user input
 
-## Setting up Composer
+#### Setting up Composer
 
 Add a `composer.json` file to your framework's root folder, e.g. `php-fuel/composer.json`. 
 Ensure your `install.sh` lists composer as a dependency, and uses `composer.phar` to 
@@ -109,7 +119,7 @@ e.g. `php-fuel/vendor` that contains all dependencies. Update your PHP scripts
 to either directly reference files inside of vendor, or use the `vendor/autoload.php`
 file. 
 
-## Generating composer.lock file
+#### Generating composer.lock file
 
 Composer uses Github *a lot*, enough so that it is common for it to exceed the 
 API limit and cause infinite hangs or installation failures. To avoid this, it 
@@ -145,7 +155,7 @@ queries as they are shown. Use these steps
     # Add the lock file to this repository
     git add -f composer.lock
 
-## Updating Composer setup
+#### Updating Composer setup
 
 If you update `composer.json`, you need to regenerate the lock
 file. If you forget to do this, you will see this error message 
@@ -153,8 +163,20 @@ when running:
 
     Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run update to update them.
 
-# Debugging PHP Frameworks
+### Debugging PHP Frameworks
 
 The first stop for HTTP 500 errors is to enable stack traces. 
 Update `config/php-fpm.conf` to include `php_flag[display_errors] = on`. 
 If you don't use php-fpm, update the `config/php.ini`
+
+## Get Help
+
+### PHP Experts
+
+_There aren't any PHP experts listed, yet. If you're an expert, 
+add yourself!_
+
+### Resources & Interesting Links
+
+_If you find some interesting links related to the PHP tests, 
+add them here._

frameworks/PHP/symfony2/README.md

@@ -1,36 +1,14 @@
 # Symfony 2 Benchmarking Test
 
-This is the Symfony 2 PHP portion of a benchmarking test suite comparing a variety of web development platforms.
+The information below contains information specific to Symfony2. 
+For further guidance, review the 
+[documentation](http://frameworkbenchmarks.readthedocs.org/en/latest/). 
+Also note the additional information provided in the [PHP README](../).
 
-This implementation is the direct result of installing the 
-[Standard Edition of Symfony 2](https://github.com/symfony/symfony-standard) using [Composer](https://getcomposer.org/), and making 
-the minimum modifications necessary to support 
-running the benchmark. Specifically, unnecessary bundles 
-have *not* been removed from the kernel to properly 
-reflect "out of the box" performance. If you're interested
-in tuned performance, see the symfony-stripped test, which
-removes and unnecessary components. 
-
-Note: `app/bootstrap.php.cache` is generated by Composer
-when you first run `composer.phar install`
-
-### JSON Encoding Test
-Uses the PHP standard [JSON encoder](http://www.php.net/manual/en/function.json-encode.php).
-
-* [JSON test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
-
-### Data-Store/Database Mapping Test
-Uses the Symfony 2/Doctrine 2 Entity functionality.
-
-* [DB test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
-* [DB test model](src/Skamander/BenchmarkBundle/Entity/World.php)
-
-### Template Test
-Uses Symfony's template engine 'Twig'
-
-* [Template test controller](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
+This is the Symfony 2 PHP portion of a [benchmarking test suite](../../) comparing a variety of web development platforms.
 
 ## Infrastructure Software Versions
+
 The tests were run with:
 
 * [Symfony Version 2.2.1](http://symfony.com/)
@@ -38,25 +16,34 @@ The tests were run with:
 * [nginx 1.4.0](http://nginx.org/)
 * [MySQL 5.5.29](https://dev.mysql.com/)
 
-## Test URLs
-### JSON Encoding Test
-
-http://localhost/json
-
-### Data-Store/Database Mapping Test
+## Paths & Source for Tests
 
-http://localhost/db
+* [JSON Serialization](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
+: "/json" _Note: Uses the PHP standard 
+[JSON encoder](http://www.php.net/manual/en/function.json-encode.php)._
+* [Single Database Query](src/Skamander/BenchmarkBundle/Controller/BenchController.php) ([Model](src/Skamander/BenchmarkBundle/Entity/World.php))
+: "/db" _Note: Uses the Symfony 2/Doctrine 2 Entity functionality._
+* [Multiple Database Queries](src/Skamander/BenchmarkBundle/Controller/BenchController.php) ([Model](src/Skamander/BenchmarkBundle/Entity/World.php))
+: "/db?queries=" _Note: Uses the Symfony 2/Doctrine 2 Entity functionality._
+* [Fortunes Template Test](src/Skamander/BenchmarkBundle/Controller/BenchController.php)
+: "/fortunes" _Note: Uses Symfony's template engine 'Twig'_
 
-### Variable Query Test
-    
-http://localhost/db?queries=2
+## Advice for Adding Symfony2 Tests
 
-### Templating Test
+This implementation is the direct result of installing the 
+[Standard Edition of Symfony 2](https://github.com/symfony/symfony-standard) using [Composer](https://getcomposer.org/), and making 
+the minimum modifications necessary to support 
+running the benchmark. Specifically, unnecessary bundles 
+have *not* been removed from the kernel to properly 
+reflect "out of the box" performance. If you're interested
+in tuned performance, see the symfony-stripped test, which
+removes and unnecessary components. 
 
-http://localhost/fortunes
+Note: `app/bootstrap.php.cache` is generated by Composer
+when you first run `composer.phar install`
 
 # Interesting Links
 
-[Discussion on APC vs Zend Optimizer, PHP 5.4](http://www.ricardclau.com/2013/03/apc-vs-zend-optimizer-benchmarks-with-symfony2/)
-
-[Symphony2 Performance Tuning](http://symfony.com/doc/current/book/performance.html)
+* [Discussion on APC vs Zend Optimizer, PHP 5.4](http://www.ricardclau.com/2013/03/apc-vs-zend-optimizer-benchmarks-with-symfony2/)
+* [Symfony2 Performance Tuning](http://symfony.com/doc/current/book/performance.html)
+* [Why is Symfony2 performing so bad in benchmarks and does it matter?](http://stackoverflow.com/questions/16696763/why-is-symfony2-performing-so-bad-in-benchmarks-and-does-it-matter)

frameworks/Ruby/grape/README.md

@@ -23,12 +23,12 @@ The tests were run with:
 
 ## Paths & Source for Tests
 
-* [JSON Serialization](Config.ru): "/json"
-* [Single Database Query](Config.ru): "/db"
-* [Multiple Database Queries](Config.ru): "/query?queries={#}"
+* [JSON Serialization](config.ru): "/json"
+* [Single Database Query](config.ru): "/db"
+* [Multiple Database Queries](config.ru): "/query?queries={#}"
 * _Fortunes: N/A_
-* [Database Updates](Config.ru): "/updates?queries={#}"
-* [Plaintext](Config.ru): "/plaintext"
+* [Database Updates](config.ru): "/updates?queries={#}"
+* [Plaintext](config.ru): "/plaintext"
 
 ## Get Help