Update README files

- Removes use of "our" from CONTRIBUTING guide
- Updates/adds README.md files
- Commnents and typo fix in watchdog
- Adds good/bad examples of commit messages

Signed-off-by: Alex Ellis (VMware) <alexellis2@gmail.com>

CONTRIBUTING.md

@@ -6,19 +6,19 @@ Guidelines for contributing.
 
 ### How can I get involved?
 
-First of all, we'd love to welcome you into our Slack community where we exchange ideas, ask questions and chat about OpenFaaS, Raspberry Pi and other cloud-native technology. (*See below for how to join*)
+The Slack community is the best place to keep up to date with the project and to get help contributing. Here we exchange ideas, ask questions and chat about OpenFaaS. There are also channels for Raspberry Pi/ARM, Kubernetes and other cloud-native topics. (*See below for how to join*)
 
-We have a number of areas where we can accept contributions:
+There are a number of areas where contributions can be accepted:
 
 * Write Golang code for the CLI, Gateway or other providers
-* Write for our front-end UI (JS, HTML, CSS)
+* Write features for the front-end UI (JS, HTML, CSS)
 * Write sample functions in any language
 * Review pull requests
 * Test out new features or work-in-progress
 * Get involved in design reviews and technical proof-of-concepts (PoCs)
-* Help us release and package OpenFaaS including the helm chart, compose files, kubectl YAML, marketplaces and stores
+* Help release and package OpenFaaS including the helm chart, compose files, `kubectl` YAML, marketplaces and stores
 * Manage, triage and research Issues and Pull Requests
-* Help our growing community feel at home
+* Engage with the growing community by providing technical support on Slack/GitHub
 * Create docs, guides and write blogs
 * Speak at meet-ups, conferences or by helping folks with OpenFaaS on Slack
 
@@ -48,20 +48,20 @@ If you are proposing a new tool or service please do due diligence. Does this to
 
 ### Paperwork for Pull Requests
 
-Please read this whole guide and make sure you agree to our DCO agreement (included below):
+Please read this whole guide and make sure you agree to the Developer Certificate of Origin (DCO) agreement (included below):
 
 * See guidelines on commit messages (below)
-* Sign-off your commits
+* Sign-off your commits (`git commit --signoff` or `-s`)
 * Complete the whole template for issues and pull requests
 * [Reference addressed issues](https://help.github.com/articles/closing-issues-using-keywords/) in the PR description & commit messages - use 'Fixes #IssueNo' 
 * Always give instructions for testing
-* Provide us CLI commands and output or screenshots where you can
+ * Provide us CLI commands and output or screenshots where you can
 
 ### Commit messages
 
 The first line of the commit message is the *subject*, this should be followed by a blank line and then a message describing the intent and purpose of the commit. These guidelines are based upon a [post by Chris Beams](https://chris.beams.io/posts/git-commit/).
 
-* When you run `git commit` make sure you sign-off the commit by typing `git commit --signoff` or `git commit -s`.
+* When you run `git commit` make sure you sign-off the commit by typing `git commit --signoff` or `git commit -s`
 * The commit subject-line should start with an uppercase letter
 * The commit subject-line should not exceed 72 characters in length
 * The commit subject-line should not end with punctuation (., etc)
@@ -70,7 +70,7 @@ When giving a commit body:
 * Leave a blank line after the subject-line
 * Make sure all lines are wrapped to 72 characters
 
-Here's an example:
+Here's an example that would be accepted:
 
 ```
 Add alexellis to the .DEREK.yml file
@@ -81,6 +81,21 @@ duties.
 Signed-off-by: Alex Ellis <alex@openfaas.com>
 ```
 
+Some invalid examples:
+
+```
+(feat) Add page about X to documentation
+```
+
+> This example does not follow the convention by adding a custom scheme of `(feat)`
+
+```
+Update the documentation for page X so including fixing A, B, C and D and F.
+```
+
+> This example will be truncated in the GitHub UI and via `git log --oneline`
+
+
 If you would like to ammend your commit follow this guide: [Git: Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
 
 #### Unit testing with Golang
@@ -89,20 +104,47 @@ Please follow style guide on [this blog post](https://blog.alexellis.io/golang-w
 
 #### I have a question, a suggestion or need help
 
-Please raise an Issue or email alex@openfaas.com for an invitation to our Slack community.
+If you have a simple question you can [join the Slack community](https://docs.openfaas.com/community) and ask there, but please bear in mind that contributors may live in a different timezone or be working to a different timeline to you. If you have an urgent request then let them know about this.
+
+If you have a deeply technical request or need help debugging your application then you should prepare a simple, public GitHub repository with the minimum amount of code required to reproduce the issue. 
+
+If you feel there is an issue with OpenFaaS or were unable to get the help you needed from the Slack channels then raise an issue on one of the GitHub repositories.
 
 #### I need to add a dependency
 
-We use vendoring for projects written in Go. This means that we will maintain a copy of the source-code of dependencies within Git. It allows a repeatable build and isolates change. 
+Vendoring is used for projects written in Go. This means that we will maintain a copy of the source-code of dependencies within Git in the `vendor` folder. This allows for a repeatable build and isolates change.
 
-We use Golang's `dep` tool to manage dependencies for Golang projects - https://github.com/golang/dep
+The vendoring tool in use is Golang's `dep`. You can get it here: https://github.com/golang/dep
 
 ### How are releases made?
-To cut a release please ask Alex via the #contributors [slack channel](https://docs.openfaas.com/community/#slack-workspace)
+
+Releases are made by the project lead when deemed necessary. If you want to request a new release then mention this on your PR or Issue.
+
+Releases are cut with Git tags and a successful Travis build results in new binary artifacts and Docker images being published to the Docker Hub and Quay.io. See the "Build" badge on each GitHub README file for more.
 
 ### How do I become a maintainer?
 
-Maintainers are well-known contributors with a track record of:
+In the OpenFaaS community there are three levels of maintainership:
+
+* Core Contributors
+* GitHub Organisation Members
+* Those with Derek access
+
+#### Who are the Core Contributors?
+
+The Core Contributor group includes:
+
+- Alex Ellis (@alexellis)
+- Richard Gee (@rgee0)
+- Stefan Prodan (@stefanprodan)
+- Lucas Roesler (@LucasRoesler)
+- Burton Rheutan (@burtonr)
+
+The Core Contributors have the ear of the project lead and help with strategy, project maintenance, community management and make a regular commitment of time to the project. Core Contributors attend all project meetings and calls.
+
+#### GitHub Organisation Members
+
+GitHub Organisation Members are well-known contributors with a track record of:
 
 * Fixing, testing and triaging issues
 * Joining contributor meetings and supporting new contributors
@@ -110,23 +152,13 @@ Maintainers are well-known contributors with a track record of:
 * Offering other project support and strategical advice
 * Attending contributors' meetings
 
-Varying levels of write access are made available via our project bot [Derek](https://github.com/alexellis/derek) to help regular contributors transition to maintainers.
+Varying levels of write access are made available via the project bot [Derek](https://github.com/alexellis/derek) to help regular contributors transition to GitHub Organisation Membership.
 
-#### How do I work with Derek?
+#### How do I get access to Derek?
 
-If you have been added to the `.DEREK.yml` file in the root of an OpenFaaS repository then you can help us manage our community and contributions by issuing comments on Issues and Pull Requests. See [Derek](https://github.com/alexellis/derek) for available commands.
+If you have been added to the `.DEREK.yml` file in the root of an OpenFaaS repository then you can help us manage the community and contributions by issuing comments on Issues and Pull Requests. See [Derek](https://github.com/alexellis/derek) for available commands.
 
-### Who are the Core Contributors?
-
-The Core Contributor group includes:
-
-- Alex Ellis (@alexellis)
-- Richard Gee (@rgee0)
-- Stefan Prodan (@stefanprodan)
-- Burton Rheutan (@burtonr)
-- Lucas Roesler (@LucasRoesler)
-
-The Core Contributors have the ear of the project lead and help with strategy, project maintenance, community management and make a regular commitment of time to the project. Core Contributors attend all project meetings and calls.
+If you are a regular contributor then you are welcome to request access.
 
 #### Community/project meetings and calls
 

DEV.md

@@ -20,7 +20,6 @@ Functions run as Docker containers with the Watchdog component embedded to handl
 
 You can find the [reference documentation for the Watchdog here](https://github.com/openfaas/faas/tree/master/watchdog).
 
-
 **Markdown Parser**
 
 This is the basis of a function which generates HTML from MarkDown:
@@ -82,15 +81,19 @@ Update your Docker stack with this definition:
 ```
 
 **Tip:**
+
 You can optimize Docker to cache getting the watchdog by using curl, instead of ADD.
 To do so, replace the related lines with:
+
 ```
 RUN apt-get update && apt-get install -y curl \
     && curl -sL https://github.com/openfaas/faas/releases/download/0.9.4/fwatchdog > /usr/bin/fwatchdog \
     && chmod +x /usr/bin/fwatchdog \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 ```
+
 or with the following for Alpine based images:
+
 ```
 RUN apk --no-cache add curl \
     && curl -sL https://github.com/openfaas/faas/releases/download/0.9.4/fwatchdog > /usr/bin/fwatchdog \

contrib/README.md

@@ -0,0 +1,10 @@
+## contrib
+
+This folder contains miscellaneous scripts and packages for CI, development and custom Docker images.
+
+* Hack on the UI Portal with [HACK.md](./HACK.md)
+* Deploy a [Grafana dashboard](./grafana.json)
+* Build and publish all project images for ARMHF with [publish-armhf.sh](./publish-armhf.sh)
+* Run experimental end-to-end tests with Docker in Docker with [dind.sh](./dind.sh)
+
+Custom Docker images for ARMHF/ARM64 are available for AlertManager and Prometheus in this folder.

docs/README.md

@@ -2,4 +2,4 @@
 
 ![https://blog.alexellis.io/content/images/2017/08/faas_side.png](https://blog.alexellis.io/content/images/2017/08/faas_side.png)
 
-Please see our [new documentation site](https://docs.openfaas.com) or our [more detailed set of guides on GitHub](https://github.com/openfaas/faas/tree/master/guide).
+Please see the [official documentation site](https://docs.openfaas.com) or our [more detailed set of guides on GitHub](https://github.com/openfaas/faas/tree/master/guide).

gateway/README.md

@@ -6,11 +6,12 @@ The gateway will scale functions according to demand by altering the service rep
 
 In summary:
 
-* UI built-in
-* Deploy your own functions or from the Function Store
+* Built-in UI Portal
+* Deploy functions from the Function Store or deploy your own
 * Instrumentation via Prometheus
-* Auto-scaling via AlertManager
-* REST API available
+* Auto-scaling via AlertManager and Prometheus
+* Scaling up from zero
+* REST API available documented with Swagger
 
 ![](https://raw.githubusercontent.com/openfaas/faas/master/docs/of-overview.png)
 
@@ -24,6 +25,24 @@ Providers for functions can be written using the [faas-provider](https://github.
 
 Swagger docs: https://github.com/openfaas/faas/tree/master/api-docs
 
+## CORS
+
+By default the only CORS path allowed is for the Function Store which is served from the GitHub RAW CDN.
+
+## UI Portal
+
+The built-in UI Portal is served through static files bound at the /ui/ path.
+
+The UI was written in Angular 1.x and makes uses of jQuery for interactions and the Angular Material theme for visual effects and components.
+
+View the source in the [assets](./assets/) folder.
+
+### Function Store
+
+The Function Store is rendered through a static JSON file served by the GitHub RAW CDN. The Function Store can also be used via the [OpenFaaS CLI](https://github.com/openfaas/faas-cli).
+
+See the [openfaas/store](https://github.com/openfaas/store) repo for more.
+
 ## Logs
 
 Logs are available at the function level and can be accessed through Swarm or Kubernetes using native tooling. You can also install a Docker logging driver to aggregate your logs. By default functions will not write the request and response bodies to stdout. You can toggle this behaviour by setting `read_debug` for the request and `write_debug` for the response.
@@ -52,7 +71,7 @@ The gateway can be configured through the following environment variables:
 | `faas_nats_port`    | Port for NATS service. Requrired for asynchronous mode |
 | `faas_prometheus_host`         | Host to connect to Prometheus. Default: `"prometheus"` |
 | `faas_promethus_port`         | Port to connect to Prometheus. Default: `9090` |
-| `direct_functions`            | `true` or `false` -  functions are invoked directly over overlay network without passing through provider |
+| `direct_functions`            | `true` or `false` -  functions are invoked directly over overlay network by DNS name without passing through the provider |
 | `direct_functions_suffix`     | Provide a DNS suffix for invoking functions directly over overlay network  |
 | `basic_auth`              | Set to `true` or `false` to enable embedded basic auth on the /system and /ui endpoints (recommended) |
 | `secret_mount_path`       | Set a location where you have mounted `basic-auth-user` and `basic-auth-password`, default: `/run/secrets/`. |

watchdog/README.md

@@ -9,6 +9,10 @@ The watchdog provides an unmanaged and generic interface between the outside wor
 
 Every function needs to embed this binary and use it as its `ENTRYPOINT` or `CMD`, in effect it is the init process for your container. Once your process is forked the watchdog passses in the HTTP request via `stdin` and reads a HTTP response via `stdout`. This means your process does not need to know anything about the web or HTTP.
 
+### Next-gen: of-watchdog
+
+Are you looking for more control over your HTTP responses, "hot functions", persistent connection pools or to cache a machine-learning model in memory? Then check out the *http mode* of the new [of-watchdog](https://github.com/openfaas-incubator/of-watchdog).
+
 ## Create a new function the easy way
 
 **Create a function via the CLI**
@@ -34,7 +38,7 @@ Here's how to package your function if you don't want to use the CLI or have exi
 Example Dockerfile for an `echo` function:
 
 ```
-FROM alpine:3.7
+FROM alpine:3.8
 
 ADD https://github.com/openfaas/faas/releases/download/0.9.4/fwatchdog /usr/bin
 RUN chmod +x /usr/bin/fwatchdog

watchdog/handler.go

@@ -20,6 +20,10 @@ import (
 	"github.com/openfaas/faas/watchdog/types"
 )
 
+type requestInfo struct {
+	headerWritten bool
+}
+
 // buildFunctionInput for a GET method this is an empty byte array.
 func buildFunctionInput(config *WatchdogConfig, r *http.Request) ([]byte, error) {
 	var res []byte
@@ -48,16 +52,13 @@ func buildFunctionInput(config *WatchdogConfig, r *http.Request) ([]byte, error)
 	return res, err
 }
 
+// debugHeaders prints HTTP headers as key/value pairs
 func debugHeaders(source *http.Header, direction string) {
 	for k, vv := range *source {
 		fmt.Printf("[%s] %s=%s\n", direction, k, vv)
 	}
 }
 
-type requestInfo struct {
-	headerWritten bool
-}
-
 func pipeRequest(config *WatchdogConfig, w http.ResponseWriter, r *http.Request, method string) {
 	startTime := time.Now()
 

watchdog/main.go

@@ -1,6 +1,9 @@
 // Copyright (c) Alex Ellis 2017. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+// Package main provides the OpenFaaS Classic Watchdog. The Classic Watchdog is a HTTP
+// shim for serverless functions providing health-checking, graceful shutdowns,
+// timeouts and a consistent logging experience.
 package main
 
 import (
@@ -73,6 +76,10 @@ func markUnhealthy() error {
 	return removeErr
 }
 
+// listenUntilShutdown will listen for HTTP requests until SIGTERM
+// is sent at which point the code will wait `shutdownTimeout` before
+// closing off connections and a futher `shutdownTimeout` before
+// exiting
 func listenUntilShutdown(shutdownTimeout time.Duration, s *http.Server, suppressLock bool) {
 
 	idleConnsClosed := make(chan struct{})

watchdog/version.go

@@ -1,18 +1,18 @@
 package main
 
 var (
-	//Version release version of the watchdog
+	// Version release version of the watchdog
 	Version string
-	//GitCommit SHA of the last git commit
+	// GitCommit SHA of the last git commit
 	GitCommit string
-	//DevVerison string for the development version
-	DevVerison = "dev"
+	// DevVersion string for the development version
+	DevVersion = "dev"
 )
 
-//BuildVersion returns current version of watchdog
+// BuildVersion returns current version of watchdog
 func BuildVersion() string {
 	if len(Version) == 0 {
-		return DevVerison
+		return DevVersion
 	}
 	return Version
 }