docs: Makefile.release and Makefile.doc (#2926)

* add metrics for reload
* documented release process better
* run: Makefile.doc all to push reload doc to man-pages

Signed-off-by: Miek Gieben <miek@miek.nl>

Makefile.doc

@@ -1,3 +1,8 @@
+# This Makefile generates the manual pages from the markdown README.mds. It depends
+# on https://github.com/mmarkdown/mmark to be installed. Generally we want this to be
+# updated before doing a release. The Debian package, for instance, looks at these pages
+# and will install them on your system.
+
 MMARK:=mmark -man
 PLUGINS:=$(wildcard plugin/*/README.md)
 READMES:=$(subst plugin/,,$(PLUGINS))

Makefile.release

@@ -5,30 +5,42 @@
 # (after some sanity checks).
 #
 # The release should be accompanied by release notes in the notes/ subdirectory.
-# These are published on coredns.io.
+# These are published on coredns.io. For example see: notes/coredns-1.5.1.md
-#
-# For example: https://coredns.io/2016/09/18/coredns-001-release/ .
 #
 # Getting the authors for this release is done with the following command line
+#
 # git log --pretty=format:'%an' v$(VERSION)..master | sort -u
 #
-# Steps:
+# Getting all pull requests merged since the last tag can be done with this "oneliner"
-# * Up the version in coremain/version.go
-# * Do a make -f Makefile.doc
-# * go generate
-# * Send PR to get this merged.
 #
-# * Open an issue for this release
+# % git log $(git describe --tags --abbrev=0)..HEAD --oneline | awk ' { $1="";print } ' | sed 's/^ //' | sed -e 's|#\([0-9]\)|https://github.com/coredns/coredns/pull/\1|'
-# * In an issue give the command: /release: master VERSION
+#
-#   Where VERSION is the version of the release - the release script double checks this with the
+# As seen in notes/coredns-1.5.1.md we want to style the notes in the following manner:
-#   actual CoreDNS version in coremain/version.go
+#
-# * (to test as release /release: -t master VERSION can be used.
+# * important changes at the top
+# * people who committed/review code (the latter is harder to get)
+# * Slightly abbreviated list of pull requests merged for this release.
+#
+# Steps to release, first:
+#
+# 1. Up the version in coremain/version.go
+# 2. Do a make -f Makefile.doc
+# 3. go generate
+# 4.* Send PR to get this merged.
+#
+# Then:
+#
+# 1. Open an issue for this release
+# 2. In an issue give the command: /release: master VERSION
+#    Where VERSION is the version of the release - the release script double checks this with the
+#    actual CoreDNS version in coremain/version.go
+# 3. (to test as release /release: -t master VERSION can be used.
 #
 # See https://github.com/coredns/release for documentation README on what needs to be setup for this to be
 # automated (can still be done by hand if needed). Especially what environment variables need to be
-# set!
+# set! This further depends on Caddy being setup and [dreck](https://github.com/miekg/dreck) running as a plugin in Caddy.
 #
-# To release we run, these target from the this Makefile:
+# To release we run, these target from the this Makefile.release ordered like:
 # * make release
 # * make docker
 # * make github-push

man/coredns-reload.7

@@ -134,6 +134,14 @@ In general be careful with assigning new port and expecting reload to work fully
 Also any \fB\fCimport\fR statement is not discovered by this plugin. This means if any of these imported files
 changes the \fIreload\fP plugin is ignorant of that fact.
 
+.SH "METRICS"
+.PP
+If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
+
+.IP \(bu 4
+\fB\fCcoredns_reload_failed_count_total{}\fR - counts the number of failed reload attempts.
+
+
 .SH "ALSO SEE"
 .PP
 See coredns-import(7) and corefile(5).

notes/coredns-1.5.1.md

@@ -3,7 +3,7 @@ title = "CoreDNS-1.5.1 Release"
 description = "CoreDNS-1.5.1 Release Notes."
 tags = ["Release", "1.5.1", "Notes"]
 release = "1.5.1"
-date = "2019-06-20T13:03:07+00:01"
+date = "2019-06-26T13:03:07+00:01"
 author = "coredns"
 +++
 
@@ -19,7 +19,10 @@ PR](https://github.com/coredns/coredns/pull/2793) otherwise we'll remove it in t
 # Plugins
 
 * A new plugin [*any*](/plugins/any) that block ANY queries according to [RFC 8482](https://tools.ietf.org/html/rfc8482) was added.
-* Failed reload fixes for: [*ready*](/plugins/ready), [*health*](/plugins/health) and [*prometheus*](/plugins/metrics) - when CoreDNS reloads and the Corefile is invalid these plugins now keep on working.
+* Failed reload fixes for: [*ready*](/plugins/ready), [*health*](/plugins/health) and
+  [*prometheus*](/plugins/metrics) - when CoreDNS reloads and the Corefile is invalid these plugins
+  now keep on working. The [*reload*](/plugin/reload) also gained a metric that export failed
+  reloads. ([PR](https://github.com/coredns/coredns/pull/2922).
 * [*tls*](/plugins/tls) now has a `client_auth` option that allows verification of client TLS certificates. Note that the default behavior continues to be to not require validation, however in version 1.6.0 this default will change to `required_and_verify` if the CA is provided.
 * [*kubernetes*](/plugins/kubernetes) can now publish metadata about the request and, if `pods verified` is enabled, about the client Pod. To enable this, you must enable the [*metadata*](/plugins/metadata) plugin.
   And also return pod IPs for running pods, instead of just the first