Merge branch 'master' into pr/get

.gitignore

@@ -13,15 +13,15 @@
 
 # kn binary itself, if you want to `go build cmd/kn` in the top dir.
 /kn
-/kn-*`
+/kn-*
 
 # emacs tempfiles
 \#*
 *~
 
 # vim swap
-[._]*.s[a-w][a-z]
-[._]s[a-w][a-z]
+[._]*.s[a-w][a-z].
+[._]s[a-w][a-z].
 
 # session
 Session.vim

DEVELOPMENT.md

@@ -66,7 +66,7 @@ Once you've [setup your development environment](#prerequisites), let's build
 **Building:**
 
 ```sh
-$ go build ./cmd/...
+$ hack/build.sh
 ```
 
 It builds `kn` binary in your current directory. You can start playing with it.

README.md

@@ -5,6 +5,15 @@ implementation, and reference Knative client libraries.
 
 If you are interested in contributing, see the Knative community [contribution guide](https://www.knative.dev/contributing/) and [DEVELOPMENT.md](./DEVELOPMENT.md).
 
+# Docs
+
+Start with the [user's guide](docs/README.md) and from there you can can read about common use cases, get detail docs on each command, and even how to extend the `kn` CLI. Links below for easy access.
+
+* [User's guide](docs/README.md)
+* [Basic workflows](docs/workflows.md) (use cases)
+* [Generated documentation](docs/cmd/kn.md)
+* [Plugins](docs/plugins.md) motivation and guide
+
 **Bash auto completion:**
 
 Run following to enable bash auto completion
@@ -22,3 +31,11 @@ completion revision service
 $ kn revision <TAB>
 describe list
 ```
+
+# Developers
+
+If you'd like to contribute, please see
+[CONTRIBUTING](https://github.com/knative/docs/blob/master/contributing/CONTRIBUTING.md)
+for more information.
+
+To build `kn`, see our [Development](DEVELOPMENT.md) guide.

docs/README.md

@@ -0,0 +1,83 @@
+# Kn
+
+Kn is the Knative command line interface (CLI). 
+
+It is designed with the goals of:
+
+1. Following closely the Knative [serving](https://github.com/knative/serving) and [eventing](https://github.com/knative/eventing) APIs
+2. Being scriptable to allow users to create different Knative workflows
+3. Exposing useful Golang packages to allow integration into other programs or CLIs or plugins
+4. Use consistent verbs, nouns, and flags that it exposes for each set (groups or categories) of commands
+5. To be easily extended via a plugin mechanism (similar to Kubectl) to allow for experimentations and customization
+
+## Command Families
+
+Most Kn commands typically fall into one of a few categories:
+
+| Type                 | Used For                       | Description                                                       |
+|----------------------|--------------------------------|-------------------------------------------------------------------|
+| Service Management   | Managing Kn services           | List, create, update, and delete a Kn service                     |
+| Revision Management  | Managing Kn service revisions  | List, create, update, and delete the revision(s) of a Kn service  |
+| Miscellaneous        | Collection of utility commands | Show version of Kn, help, plugin list, and other useful commands  |
+
+## Service Management
+
+A Knative service is the embodiment of a serverless workload. Generally in the form of a collection of containers running in a group of pods in the underlying Kubernetes cluster. Each Knative service associates with a collection of revisions which represents the evolution of that service.
+
+With the Kn CLI a user can [`list`](cmd/kn_service_list.md), [`create`](cmd/kn_service_create.md), [`delete`](cmd/kn_service_delete.md), and [`update`](cmd/kn_service_update.md) Knative services. The [detail reference](cmd/kn_service.md) of each sub-command under the [`service` command](cmd/kn_service.md) shows the options and flags for this group of commands.
+
+Examples:
+
+```bash
+# Create a new service from an image
+
+kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
+```
+
+You are able to also specify the requests and limits of both CPU and memory when creating a service. See [`service create` command](cmd/kn_service_create.md) reference for additional details.
+
+```bash
+# List existing services in the 'default' namespace of your cluster
+
+kn service list
+```
+
+You can also list services from all namespaces or specific namespace using flags: `--all-namespaces` and `--namespace mynamespace`. See [`service list` command](cmd/kn_service_list.md) reference for additional details.
+
+## Revision Management
+
+A Knative revision is a change to the specification of a service. For instance, when a Knative service is created with environment variable `FOO=bar` a revision is added to the service. When later the environment variable is changed to `baz` or additional variables are added, a new revision is created. [What other changes can create revisions?]
+
+With the [`revision` command group](cmd/kn_revision.md) you can [list](cmd/kn_revision_list.md) and [describe](cmd/kn_revision_describe.md) the current revisions on a service.
+
+Examples:
+
+```bash
+# Listing a service's revision
+
+kn revision list --service srvc # CHECK this since current command does not have --service flag
+```
+
+## Miscellaneous
+
+This is a grab all category for commands that do not fit into the previous categories. We can divide this into two.
+
+### Utilities
+
+These are commands that provide some useful information to the user.
+
+* The `kn help` command displays a list of the commands with helpful information.
+* The [`kn version` command](cmd/kn_version.md) will display the current version of the Kn build including date and Git commit revision.
+* The [`kn completion` command](cmd/kn_completion.md) will output a BASH completion script for Kn to allow command completions with tabs.
+
+### Plugins
+
+[Plugins](plugins.md) are an experimental feature to allow users to extend and customize the Kn CLI.
+
+## Common Flags
+
+For every Kn command you can use these optional common additional flags:
+
+* `-h` or `--help` to display specific help for that command
+* `--config string` which specifies the Kn config file (default is $HOME/.kn.yaml)
+* `--kubeconfig string` which specifies the kubectl config file (default is $HOME/.kube/config)

docs/cmd/kn.md

@@ -0,0 +1,28 @@
+## kn
+
+Knative client
+
+### Synopsis
+
+Manage your Knative building blocks:
+
+Serving: Manage your services and release new software to them.
+Build: Create builds and keep track of their results.
+Eventing: Manage event subscriptions and channels. Connect up event sources.
+
+### Options
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+  -h, --help                help for kn
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn completion](kn_completion.md)	 - Output bash completion code
+* [kn revision](kn_revision.md)	 - Revision command group
+* [kn service](kn_service.md)	 - Service command group
+* [kn version](kn_version.md)	 - Prints the client version
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_completion.md

@@ -0,0 +1,30 @@
+## kn completion
+
+Output bash completion code
+
+### Synopsis
+
+Output bash completion code
+
+```
+kn completion [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn](kn.md)	 - Knative client
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_revision.md

@@ -0,0 +1,28 @@
+## kn revision
+
+Revision command group
+
+### Synopsis
+
+Revision command group
+
+### Options
+
+```
+  -h, --help   help for revision
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn](kn.md)	 - Knative client
+* [kn revision describe](kn_revision_describe.md)	 - Describe revisions.
+* [kn revision list](kn_revision_list.md)	 - List available revisions.
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_revision_describe.md

@@ -0,0 +1,34 @@
+## kn revision describe
+
+Describe revisions.
+
+### Synopsis
+
+Describe revisions.
+
+```
+kn revision describe NAME [flags]
+```
+
+### Options
+
+```
+      --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
+  -h, --help                          help for describe
+  -n, --namespace string              List the requested object(s) in given namespace.
+  -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|templatefile|template|jsonpath|jsonpath-file. (default "yaml")
+      --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn revision](kn_revision.md)	 - Revision command group
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_revision_list.md

@@ -0,0 +1,35 @@
+## kn revision list
+
+List available revisions.
+
+### Synopsis
+
+List available revisions.
+
+```
+kn revision list [flags]
+```
+
+### Options
+
+```
+      --all-namespaces                If present, list the requested object(s) across all namespaces. Namespace in current context is ignored even if specified with --namespace.
+      --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
+  -h, --help                          help for list
+  -n, --namespace string              List the requested object(s) in given namespace.
+  -o, --output string                 Output format. One of: json|yaml|name|template|go-template|go-template-file|templatefile|jsonpath|jsonpath-file. (default "jsonpath={range .items[*]}{.metadata.name}{\"\\n\"}{end}")
+      --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview].
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn revision](kn_revision.md)	 - Revision command group
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_service.md

@@ -0,0 +1,31 @@
+## kn service
+
+Service command group
+
+### Synopsis
+
+Service command group
+
+### Options
+
+```
+  -h, --help   help for service
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn](kn.md)	 - Knative client
+* [kn service create](kn_service_create.md)	 - Create a service.
+* [kn service delete](kn_service_delete.md)	 - Delete a service.
+* [kn service describe](kn_service_describe.md)	 - Describe available services.
+* [kn service list](kn_service_list.md)	 - List available services.
+* [kn service update](kn_service_update.md)	 - Update a service.
+
+###### Auto generated by spf13/cobra on 3-May-2019

docs/cmd/kn_service_create.md

@@ -0,0 +1,48 @@
+## kn service create
+
+Create a service.
+
+### Synopsis
+
+Create a service.
+
+```
+kn service create NAME --image IMAGE [flags]
+```
+
+### Examples
+
+```
+
+  # Create a service 'mysvc' using image at dev.local/ns/image:latest
+  kn service create mysvc --image dev.local/ns/image:latest
+
+  # Create a service with multiple environment variables
+  kn service create mysvc --env KEY1=VALUE1 --env KEY2=VALUE2 --image dev.local/ns/image:latest
+```
+
+### Options
+
+```
+  -e, --env stringArray          Environment variable to set. NAME=value; you may provide this flag any number of times to set multiple environment variables.
+  -h, --help                     help for create
+      --image string             Image to run.
+      --limits-cpu string        The limits on the requested CPU (e.g., 1000m).
+      --limits-memory string     The limits on the requested CPU (e.g., 1024Mi).
+  -n, --namespace string         List the requested object(s) in given namespace.
+      --requests-cpu string      The requested CPU (e.g., 250m).
+      --requests-memory string   The requested CPU (e.g., 64Mi).
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       config file (default is $HOME/.kn.yaml)
+      --kubeconfig string   kubectl config file (default is $HOME/.kube/config)
+```
+
+### SEE ALSO
+
+* [kn service](kn_service.md)	 - Service command group
+
+###### Auto generated by spf13/cobra on 3-May-2019