From f77c6e55bf735ab3e08feaa8dbbf4a995512a992 Mon Sep 17 00:00:00 2001
From: Miek Gieben <miek@miek.nl>
Date: Fri, 31 Jan 2020 12:37:24 +0100
Subject: [PATCH] presubmit: test README.md sections (#3644)

Automatically submitted.
---
 plugin.md                     |  2 +-
 plugin/cancel/README.md       |  2 ++
 plugin/k8s_external/README.md |  2 +-
 plugin/rewrite/README.md      |  2 ++
 plugin/secondary/README.md    |  2 ++
 plugin/transfer/README.md     |  4 +++
 test/readme_test.go           | 50 +++++++++++++++++++++++++++++++++++
 7 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/plugin.md b/plugin.md
index b85a4c28a..00bdb0e59 100644
--- a/plugin.md
+++ b/plugin.md
@@ -75,7 +75,7 @@ Each plugin should have a README.md explaining what the plugin does and how it i
 file should have the following layout:
 
 * Title: use the plugin's name
-* Subsection titled: "Named"
+* Subsection titled: "Name"
     with *PLUGIN* - one line description.
 * Subsection titled: "Description" has a longer description.
 * Subsection titled: "Syntax", syntax and supported directives.
diff --git a/plugin/cancel/README.md b/plugin/cancel/README.md
index 8561b1f6b..65224bf52 100644
--- a/plugin/cancel/README.md
+++ b/plugin/cancel/README.md
@@ -16,6 +16,8 @@ A plugin interested in the cancellation status should call `plugin.Done()` on th
 context was canceled due to a timeout the plugin should not write anything back to the client and
 return a value indicating CoreDNS should not either; a zero return value should suffice for that.
 
+## Syntax
+
 ~~~ txt
 cancel [TIMEOUT]
 ~~~
diff --git a/plugin/k8s_external/README.md b/plugin/k8s_external/README.md
index dc251ab02..9fded952a 100644
--- a/plugin/k8s_external/README.md
+++ b/plugin/k8s_external/README.md
@@ -57,7 +57,7 @@ k8s_external [ZONE...] {
 * **APEX** is the name (DNS label) to use for the apex records; it defaults to `dns`.
 * `ttl` allows you to set a custom **TTL** for responses. The default is 5 (seconds).
 
-# Examples
+## Examples
 
 Enable names under `example.org` to be resolved to in-cluster DNS addresses.
 
diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md
index 601bf0447..ca48a6d17 100644
--- a/plugin/rewrite/README.md
+++ b/plugin/rewrite/README.md
@@ -37,6 +37,8 @@ will behave as follows:
    * `continue` will continue applying the next rule in the rule list.
    * `stop` will consider the current rule the last rule and will not continue.  The default behaviour is `stop`
 
+## Examples
+
 ### Name Field Rewrites
 
 The `rewrite` plugin offers the ability to match the name in the question section of
diff --git a/plugin/secondary/README.md b/plugin/secondary/README.md
index 00a9d6b88..dab740284 100644
--- a/plugin/secondary/README.md
+++ b/plugin/secondary/README.md
@@ -10,6 +10,8 @@ With *secondary* you can transfer (via AXFR) a zone from another server. The ret
 *not committed* to disk (a violation of the RFC). This means restarting CoreDNS will cause it to
 retrieve all secondary zones.
 
+## Syntax
+
 ~~~
 secondary [ZONES...]
 ~~~
diff --git a/plugin/transfer/README.md b/plugin/transfer/README.md
index 45ec60c99..fdd4467d2 100644
--- a/plugin/transfer/README.md
+++ b/plugin/transfer/README.md
@@ -29,3 +29,7 @@ transfer [ZONE...] {
 
 * `to ` **HOST...** The hosts *transfer* will transfer to. Use `*` to permit
   transfers to all hosts.
+
+## Examples
+
+TODO
diff --git a/test/readme_test.go b/test/readme_test.go
index b857def12..38fbcc0e2 100644
--- a/test/readme_test.go
+++ b/test/readme_test.go
@@ -2,10 +2,12 @@ package test
 
 import (
 	"bufio"
+	"fmt"
 	"io/ioutil"
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/coredns/coredns/core/dnsserver"
@@ -39,6 +41,9 @@ PrivateKey: f03VplaIEA+KHI9uizlemUSbUJH86hPBPjmcUninPoM=
 //	# check-this-please
 // }
 // ~~~
+//
+// While we're at it - we also check the README.md itself. It should at least have the sections:
+// Name, Description, Syntax and Examples. See plugin.md for more details.
 func TestReadme(t *testing.T) {
 	port := 30053
 	caddy.Quiet = true
@@ -59,6 +64,10 @@ func TestReadme(t *testing.T) {
 		readme := filepath.Join(middle, d.Name())
 		readme = filepath.Join(readme, "README.md")
 
+		if err := sectionsFromReadme(readme); err != nil {
+			t.Fatal(err)
+		}
+
 		inputs, err := corefileFromReadme(readme)
 		if err != nil {
 			continue
@@ -118,6 +127,47 @@ func corefileFromReadme(readme string) ([]*Input, error) {
 	return input, nil
 }
 
+// sectionsFromReadme returns an error if the readme doesn't contains all
+// mandatory sections. The check is basic, as we match each line, this mostly
+// works, because markdown is such a simple format.
+// We want: Name, Description, Syntax, Examples - in this order.
+func sectionsFromReadme(readme string) error {
+	f, err := os.Open(readme)
+	if err != nil {
+		return nil // don't error when we can read the file
+	}
+	defer f.Close()
+
+	section := 0
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := s.Text()
+		switch section {
+		case 0:
+			if strings.HasPrefix(line, "## Name") {
+				section++
+			}
+		case 1:
+			if strings.HasPrefix(line, "## Description") {
+				section++
+			}
+		case 2:
+			if strings.HasPrefix(line, "## Syntax") {
+				section++
+			}
+		case 3:
+			if strings.HasPrefix(line, "## Examples") {
+				section++
+			}
+		}
+	}
+	if section != 4 {
+		return fmt.Errorf("Sections incomplete or ordered wrong: %q, want (at least): Name, Descripion, Syntax and Examples", readme)
+	}
+	return nil
+
+}
+
 func create(c map[string]string) {
 	for name, content := range c {
 		ioutil.WriteFile(name, []byte(content), 0644)