Merge pull request #1090 from sudo-bmitch/pr-markdown-lint

Add a markdown linter

.github/PULL_REQUEST_TEMPLATE/maintainer_nomination.md

@@ -11,11 +11,13 @@ Name of the new maintainer with GitHub username
 ## Justification
 
 Highlight any work contributed by the new maintainer. Examples of contributions may be:
+
 - Community involvement in mailing lists and meetings
 - Involvement in any OCI working groups
 - Contributions to any of the OCI git repositories
 
 Other considerations may be:
+
 - Diversity of organizations
 - Time involved in the community
 - Personal experience working with the new maintainer

.markdownlint.yml

@@ -0,0 +1,18 @@
+# all lists use a `-`
+MD004:
+  style: dash
+
+# allow tabs in code blocks (for Go)
+MD010:
+  code_blocks: false
+
+# disable line length, prefer one sentence per line for PRs
+MD013: false
+
+# emphasis with underscore (`_emphasis_`)
+MD049:
+  style: "underscore"
+
+# bold with asterisk (`**bold**`)
+MD050:
+  style: "asterisk"

EMERITUS.md

@@ -1,9 +1,11 @@
+# Emeritus
+
 We would like to acknowledge previous OCI image spec maintainers and their huge contributions to our collective success:
 
-* Brandon Philips (@philips)
-* Brendan Burns (@brendandburns)
-* Jason Bouzane (@jbouzane)
-* John Starks (@jstarks)
-* Keyang Xie (@xiekeyang)
+- Brandon Philips (@philips)
+- Brendan Burns (@brendandburns)
+- Jason Bouzane (@jbouzane)
+- John Starks (@jstarks)
+- Keyang Xie (@xiekeyang)
 
 We thank these members for their service to the OCI community.

HACKING.md

@@ -10,8 +10,8 @@ This spec includes several Go packages, and a command line tool considered to be
 
 Prerequisites:
 
-* Go - current release only, earlier releases are not supported
-* make
+- Go - current release only, earlier releases are not supported
+- make
 
 The following make targets are relevant for any work involving the Go packages.
 
@@ -43,7 +43,7 @@ This target auto-formats all JSON files in the `schema` directory using the `jq`
 
 Prerequisites:
 
-* [jq][jq] >=1.5
+- [jq][jq] >=1.5
 
 Invocation:
 
@@ -57,7 +57,7 @@ This target generates a PDF/HTML version of the OCI image specification.
 
 Prerequisites:
 
-* [Docker][docker]
+- [Docker][docker]
 
 Invocation:
 
@@ -91,7 +91,7 @@ This target generates PNG image files from DOT source files in the `img` directo
 
 Prerequisites:
 
-* [graphviz][graphviz]
+- [graphviz][graphviz]
 
 Invocation:
 

Makefile

@@ -41,6 +41,8 @@ DOC_FILES := \
 FIGURE_FILES := \
 	img/media-types.png
 
+MARKDOWN_LINT_VER?=v0.8.1
+
 TOOLS := gitvalidation 
 
 default: check-license lint test
@@ -81,10 +83,20 @@ check-license: ## check license headers in source files
 	@./.tool/check-license
 
 .PHONY: lint
-lint: .install.lint ## lint check of Go files using golangci-lint
-	@echo "checking lint"
+
+.PHONY: lint
+lint: lint-go lint-md ## Run all linters
+
+.PHONY: lint-go
+lint-go: .install.lint ## lint check of Go files using golangci-lint
+	@echo "checking Go lint"
 	@GO111MODULE=on $(GOPATH)/bin/golangci-lint run
 
+.PHONY: lint-md
+lint-md: ## Run linting for markdown
+	docker run --rm -v "$(PWD):/workdir:ro" docker.io/davidanson/markdownlint-cli2:$(MARKDOWN_LINT_VER) \
+	  **/*.md "#vendor"
+
 .PHONY: test
 test: ## run the unit tests
 	go test -race -cover $(shell go list ./... | grep -v /vendor/)

README.md

@@ -1,9 +1,8 @@
 # OCI Image Format Specification
-<div>
-<a href="https://travis-ci.org/opencontainers/image-spec">
-<img src="https://travis-ci.org/opencontainers/image-spec.svg?branch=master"></img>
-</a>
-</div>
+
+![GitHub Actions for Docs and Linting](https://img.shields.io/github/actions/workflow/status/opencontainers/image-spec/docs-and-linting.yml?branch=main&label=GHA%20docs%20and%20linting)
+![License](https://img.shields.io/github/license/opencontainers/image-spec)
+[![Go Reference](https://pkg.go.dev/badge/github.com/opencontainers/image-spec.svg)](https://pkg.go.dev/github.com/opencontainers/image-spec)
 
 The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format).
 
@@ -28,8 +27,8 @@ At this point the OCI Runtime Bundle would be run by an OCI Runtime.
 
 This entire workflow supports the UX that users have come to expect from container engines like Docker and rkt: primarily, the ability to run an image with no additional arguments:
 
-* docker run example.com/org/app:v1.0.0
-* rkt run example.com/org/app,version=v1.0.0
+- docker run example.com/org/app:v1.0.0
+- rkt run example.com/org/app,version=v1.0.0
 
 To support this UX the OCI Image Format contains sufficient information to launch the application on the target platform (e.g. command, arguments, environment variables, etc).
 
@@ -51,14 +50,14 @@ Find more [FAQ on the OCI site](https://www.opencontainers.org/faq).
 
 The [GitHub milestones](https://github.com/opencontainers/image-spec/milestones) lay out the path to the future improvements.
 
-# Contributing
+## Contributing
 
 Development happens on GitHub for the spec.
 Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
 
 The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
 
-## Discuss your design
+### Discuss your design
 
 The project welcomes submissions, but please let everyone know what you are working on.
 
@@ -69,33 +68,33 @@ It also guarantees that the design is sound before code is written; a GitHub pul
 Typos and grammatical errors can go straight to a pull-request.
 When in doubt, start on the [mailing-list](#mailing-list).
 
-## Meetings
+### Meetings
 
-Please see the [OCI org repository README](https://github.com/opencontainers/org#meetings) for the most up-to-date information on OCI contributor and maintainer meeting schedules. 
+Please see the [OCI org repository README](https://github.com/opencontainers/org#meetings) for the most up-to-date information on OCI contributor and maintainer meeting schedules.
 You can also find links to meeting agendas and minutes for all prior meetings.
 
-## Mailing List
+### Mailing List
 
 You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev).
 
-## IRC
+### IRC
 
 OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]).
 
-## Markdown style
+### Markdown style
 
 To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
 This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
 For example, this paragraph will span three lines in the Markdown source.
 
-## Git commit
+### Git commit
 
-### Sign your work
+#### Sign your work
 
 The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch.
 The rules are pretty simple: if you can certify the below (from [developercertificate.org](https://developercertificate.org/)):
 
-```
+```text
 Developer Certificate of Origin
 Version 1.1
 
@@ -136,7 +135,9 @@ By making a contribution to this project, I certify that:
 
 then you just add a line to every git commit message:
 
-    Signed-off-by: Joe Smith <joe@gmail.com>
+```text
+Signed-off-by: Joe Smith <joe@gmail.com>
+```
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
 
@@ -154,9 +155,8 @@ Read more on [How to Write a Git Commit Message](https://chris.beams.io/posts/gi
 5. Use the imperative mood in the subject line
 6. Wrap the body at 72 characters
 7. Use the body to explain what and why vs. how
-  * If there was important/useful/essential conversation or information, copy or include a reference
+   - If there was important/useful/essential conversation or information, copy or include a reference
 8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
 
-
 [code-of-conduct]: https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
 [irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/

RELEASES.md

@@ -20,59 +20,60 @@ They may not propose a v1.0.0-rc3 until the v1.0.0-rc2 is accepted (on the 7th i
 The OCI maintains three categories of projects: specifications, applications, and conformance-testing tools.
 However, specification releases have special restrictions in the [OCI charter][charter]:
 
-* They are the target of backwards compatibility (§7.g), and
-* They are subject to the OFWa patent grant (§8.d and e).
+- They are the target of backwards compatibility (§7.g), and
+- They are subject to the OFWa patent grant (§8.d and e).
 
 To avoid unfortunate side effects (onerous backwards compatibility requirements or Member resignations), the following additional procedures apply to specification releases:
 
 ### Planning a release
 
 Every OCI specification project SHOULD hold meetings that involve maintainers reviewing pull requests, debating outstanding issues, and planning releases.
 This meeting MUST be advertised on the project README and MAY happen on a phone call, video conference, or on IRC.
-Maintainers MUST send updates to the dev@opencontainers.org with results of these meetings.
+Maintainers MUST send updates to the <dev@opencontainers.org> with results of these meetings.
 
 Before the specification reaches v1.0.0, the meetings SHOULD be weekly.
 Once a specification has reached v1.0.0, the maintainers may alter the cadence, but a meeting MUST be held within four weeks of the previous meeting.
 
-The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. https://github.com/opencontainers/runtime-spec/milestones).
+The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. <https://github.com/opencontainers/runtime-spec/milestones>).
 GitHub milestones and issues are only used for community organization and all releases MUST follow the [project governance](GOVERNANCE.md) rules and procedures.
 
 ### Timelines
 
 Specifications have a variety of different timelines in their lifecycle.
 
-* Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
-* Major specification releases MUST release at least three release candidates spaced a minimum of one week apart.
+- Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
+- Major specification releases MUST release at least three release candidates spaced a minimum of one week apart.
     This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself.
     Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced.
     For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0.
-* Minor and patch releases SHOULD be made on an as-needed basis.
+- Minor and patch releases SHOULD be made on an as-needed basis.
 
 [charter]: https://github.com/opencontainers/tob/blob/main/CHARTER.md
 
 ## Checklist
 
 Releases usually follow a few steps:
 
-* [ ] prepare a pull-request for the release
-  * [ ] a commit updating `./ChangeLog`
-    * [ ] `git log --oneline --no-merges --decorate --name-status v1.0.1..HEAD | vim -`
-    * [ ] `:% s/(pr\/\(\d*\))\(.*\)/\2 (#\1)/` to move the PR to the end of line and match previous formatting
-    * [ ] review `(^M|^A|^D)` for impact of the commit
-    * [ ] group commits to `Additions:`, `Minor fixes and documentation:`, `Breaking changes:`
-    * [ ] delete the `(^M|^A|^D)` lines, `:%!grep -vE '(^M|^A|^D)'`
-    * [ ] merge multi-commit PRs (so each line has a `(#num)` suffix)
-    * [ ] drop hash and indent, `:'<,'> s/^\w*  /^I* /`
-  * [ ] a commit bumping `./specs-go/version.go` to next version and empty the `VersionDev` variable
-  * [ ] a commit adding back the "+dev" to `VersionDev`
-* [ ] send email to dev@opencontainers.org
-  * [ ] copy the exact commit hash for bumping the version from the pull-request (since master always stays as "-dev")
-  * [ ] count the PRs since last release (that this version is tracking, in the cases of multiple branching), like `git log --pretty=oneline --no-merges --decorate $priorTag..$versionBumpCommit  | grep \(pr\/ | wc -l`
-  * [ ] get the date for a week from now, like `TZ=UTC date --date='next week'`
-  * [ ] OPTIONAL find a cute animal gif to attach to the email, and subsequently the release description
-  * [ ] subject line like `[runtime-spec VOTE] tag $versionBumpCommit as $version (closes $dateWeekFromNowUTC)`
-  * [ ] email body like
-```
+- [ ] prepare a pull-request for the release
+  - [ ] a commit updating `./ChangeLog`
+    - [ ] `git log --oneline --no-merges --decorate --name-status v1.0.1..HEAD | vim -`
+    - [ ] `:% s/(pr\/\(\d*\))\(.*\)/\2 (#\1)/` to move the PR to the end of line and match previous formatting
+    - [ ] review `(^M|^A|^D)` for impact of the commit
+    - [ ] group commits to `Additions:`, `Minor fixes and documentation:`, `Breaking changes:`
+    - [ ] delete the `(^M|^A|^D)` lines, `:%!grep -vE '(^M|^A|^D)'`
+    - [ ] merge multi-commit PRs (so each line has a `(#num)` suffix)
+    - [ ] drop hash and indent, `:'<,'> s/^\w*  /^I* /`
+  - [ ] a commit bumping `./specs-go/version.go` to next version and empty the `VersionDev` variable
+  - [ ] a commit adding back the "+dev" to `VersionDev`
+- [ ] send email to <dev@opencontainers.org>
+  - [ ] copy the exact commit hash for bumping the version from the pull-request (since master always stays as "-dev")
+  - [ ] count the PRs since last release (that this version is tracking, in the cases of multiple branching), like `git log --pretty=oneline --no-merges --decorate $priorTag..$versionBumpCommit  | grep \(pr\/ | wc -l`
+  - [ ] get the date for a week from now, like `TZ=UTC date --date='next week'`
+  - [ ] OPTIONAL find a cute animal gif to attach to the email, and subsequently the release description
+  - [ ] subject line like `[runtime-spec VOTE] tag $versionBumpCommit as $version (closes $dateWeekFromNowUTC)`
+  - [ ] email body like
+
+```text
 Hey everyone,
 
 There have been $numPRs PRs merged since $priorTag release (https://github.com/opencontainers/image-spec/compare/$priorTag...$versionBumpCommit).
@@ -83,14 +84,15 @@ Please respond LGTM or REJECT (with reasoning).
 
 $sig
 ```
-* [ ] edit/update the pull-request to link to the VOTE thread, from https://groups.google.com/a/opencontainers.org/forum/#!forum/dev
-* [ ] a week later, if the vote passes, merge the PR
-  * [ ] `git tag -s $version $versionBumpCommit`
-  * [ ] `git push --tags`
-* [ ] produce release documents
-  * [ ] git checkout the release tag, like `git checkout $version`
-  * [ ] `make docs`
-  * [ ] rename the output PDF and HTML file to include version, like `mv output/oci-runtime-spec.pdf output/oci-runtime-spec-$version.pdf``
-  * [ ] attach these docs to the release on https://github.com/opencontainers/runtime-spec/releases
-  * [ ] link to the the VOTE thread and include the passing vote count
-  * [ ] link to the pull request that merged the release
+
+- [ ] edit/update the pull-request to link to the VOTE thread, from <https://groups.google.com/a/opencontainers.org/forum/#!forum/dev>
+- [ ] a week later, if the vote passes, merge the PR
+  - [ ] `git tag -s $version $versionBumpCommit`
+  - [ ] `git push --tags`
+- [ ] produce release documents
+  - [ ] git checkout the release tag, like `git checkout $version`
+  - [ ] `make docs`
+  - [ ] rename the output PDF and HTML file to include version, like `mv output/oci-runtime-spec.pdf output/oci-runtime-spec-$version.pdf``
+  - [ ] attach these docs to the release on <https://github.com/opencontainers/runtime-spec/releases>
+  - [ ] link to the the VOTE thread and include the passing vote count
+  - [ ] link to the pull request that merged the release