docs: updates some, remove others (#1187)

Fix typo in kubernetes/README.md and remove DEV-README.md as it is stale
and information on the website is more up to date.

Remove large sections of text in plugin.md; just talk about how to
structure your plugin and docs.

plugin.md

@@ -2,35 +2,6 @@
 
 ## Writing Plugins
 
-From the Caddy docs:
-
-> Oh yes, those pesky return values on ServeHTTP(). You read the documentation so you already know
-> what they mean. But what does that imply for the behavior of your plugin?
->
-> Basically, return a status code only if you did NOT write to the response body. If you DO write to
-> the response body, return a status code of 0. Return an error value if your plugin encountered
-> an error that you want logged. It is common to return an error status and an error value together,
-> so that the error handler up the chain can write the correct error page.
->
-> The returned status code is not logged directly; rather, it tells plugin higher up the chain
-> what status code to use if/when the response body is written. Again, return a 0 status if you've
-> already written a body!
-
-In the DNS status codes are called rcodes and it's slightly harder to return the correct
-answer in case of failure.
-
-So CoreDNS treats:
-
-* SERVFAIL (dns.RcodeServerFailure)
-* REFUSED (dns.RcodeRefused)
-* FORMERR (dns.RcodeFormatError)
-* NOTIMP (dns.RcodeNotImplemented)
-
-as special and will then assume nothing has written to the client. In all other cases it is assumes
-something has been written to the client (by the plugin).
-
-## Hooking It Up
-
 See a couple of blog posts on how to write and add plugin to CoreDNS:
 
 * <https://blog.coredns.io/2017/03/01/how-to-add-plugin-to-coredns/>
@@ -39,14 +10,14 @@ See a couple of blog posts on how to write and add plugin to CoreDNS:
 ## Metrics
 
 When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns"), and the
-*Subsystem* should be the name of the plugin. The README.md for the plugin should then
-also contain a *Metrics* section detailing the metrics. If the plugin supports dynamic health
-reporting it should also have *Health* section detailing on its inner workings.
+*Subsystem* should be the name of the plugin. The README.md for the plugin should then also contain
+ a *Metrics* section detailing the metrics. If the plugin supports dynamic health reporting it
+ should also have *Health* section detailing on some of its inner workings.
 
 ## Documentation
 
-Each plugin should have a README.md explaining what the plugin does and how it is
-configured. The file should have the following layout:
+Each plugin should have a README.md explaining what the plugin does and how it is configured. The
+file should have the following layout:
 
 * Title: use the plugin's name
 * Subsection titled: "Syntax"
@@ -72,16 +43,17 @@ standard domain names created for this purpose.
 
 ## Fallthrough
 
-In a perfect world the following would be true for plugin: "Either you are responsible for
-a zone or not". If the answer is "not", the plugin should call the next plugin in the chain.
-If "yes" it should handle *all* names that fall in this zone and the names below - i.e. it should
-handle the entire domain.
+In a perfect world the following would be true for plugin: "Either you are responsible for a zone or
+not". If the answer is "not", the plugin should call the next plugin in the chain. If "yes" it
+should handle *all* names that fall in this zone and the names below - i.e. it should handle the
+entire domain.
 
 ~~~ txt
 . {
     file example.org db.example
 }
 ~~~
+
 In this example the *file* plugin is handling all names below (and including) `example.org`. If
 a query comes in that is not a subdomain (or equal to) `example.org` the next plugin is called.
 
@@ -96,44 +68,6 @@ reverse cases and **all other** request are handled by the backing plugin. This
 "fallthrough" does. To keep things explicit we've opted that plugins implement such behavior
 should implement a `fallthrough` keyword.
 
-### Example Fallthrough Usage
-
-The following Corefile example, sets up the *reverse* plugin, but disables fallthrough. It
-also defines a zonefile for use with the *file* plugin for other names in the `compute.internal`.
-
-~~~ txt
-arpa compute.internal {
-    reverse 10.32.0.0/16 {
-        hostname ip-{ip}.{zone[2]}
-        #fallthrough
-    }
-    file db.compute.internal compute.internal
-}
-~~~
-
-This works for returning a response to a PTR request:
-
-~~~ sh
-% dig +nocmd @localhost +noall +ans -x 10.32.0.1
-1.0.32.10.in-addr.arpa.	3600	IN	PTR	ip-10-32-0-1.compute.internal.
-~~~
-
-And for the forward:
-
-~~~ sh
-% dig +nocmd @localhost +noall +ans A ip-10-32-0-1.compute.internal
-ip-10-32-0-1.compute.internal. 3600 IN	A	10.32.0.1
-~~~
-
-But a query for `mx compute.internal` will return SERVFAIL. Now when we remove the '#' from
-fallthrough and reload (on Unix: `kill -SIGUSR1 $(pidof coredns)`) CoreDNS, we *should* get an
-answer for the MX query:
-
-~~~ sh
-% dig +nocmd @localhost +noall +ans MX compute.internal
-compute.internal.	3600	IN	MX	10 mx.compute.internal.
-~~~
-
 ## Qualifying for main repo
 
 Plugins for CoreDNS can live out-of-tree, `plugin.cfg` defaults to CoreDNS' repo but other

plugin/kubernetes/DEV-README.md

-# Basic Setup for Development and Testing
-
-## Launch Kubernetes
-
-To run the tests, you'll need a private, live Kubernetes cluster. If you don't have one,
-you can try out [minikube](https://github.com/kubernetes/minikube), which is
-also available via Homebrew for OS X users.
-
-## Configure Test Data
-
-The test data is all in [this manifest](https://github.com/coredns/coredns/blob/master/.travis/kubernetes/dns-test.yaml)
-and you can load it with `kubectl apply -f`. It will create a couple namespaces and some services.
-For the tests to pass, you should not create anything else in the cluster.
-
-## Proxy the API Server
-
-Assuming your Kuberentes API server isn't running on http://localhost:8080, you will need to proxy from that
-port to your cluster. You can do this with `kubectl proxy --port 8080`.
-
-## Run CoreDNS Kubernetes Tests
-
-Now you can run the tests locally, for example:
-
-~~~
-$ cd $GOPATH/src/github.com/coredns/coredns/test
-$ go test -v -tags k8s
-~~~
-
-# Implementation Notes/Ideas
-
-* Additional features:
-	* Implement IP selection and ordering (internal/external). Related to
-	  wildcards and SkyDNS use of CNAMES.
-	* Expose arbitrary kubernetes repository data as TXT records?
-* DNS Correctness
-	* Do we need to generate synthetic zone records for namespaces?
-	* Do we need to generate synthetic zone records for the skydns synthetic zones?
-* Test cases
-	* Test with CoreDNS caching. CoreDNS caching for DNS response is working
-	  using the `cache` directive. Tested working using 20s cache timeout
-	  and A-record queries. Automate testing with cache in place.
-	* Automate CoreDNS performance tests. Initially for zone files, and for
-	  pre-loaded k8s API cache. With and without CoreDNS response caching.

plugin/kubernetes/README.md

@@ -38,7 +38,7 @@ kubernetes [ZONES...] {
 ```
 
 * `resyncperiod` specifies the Kubernetes data API **DURATION** period.
-* `endpoint` specifies the **URL** for a remove k8s API endpoint.
+* `endpoint` specifies the **URL** for a remote k8s API endpoint.
    If omitted, it will connect to k8s in-cluster using the cluster service account.
    Multiple k8s API endpoints could be specified, separated by `,`s, e.g.
    `endpoint http://k8s-endpoint1:8080,http://k8s-endpoint2:8080`. CoreDNS