Introduce lint

Author: grampelberg

.circleci/config.yml

@@ -0,0 +1,19 @@
+version: 2
+jobs:
+  test:
+    docker:
+      - image: circleci/node:12
+
+    steps:
+      - checkout
+
+      - run:
+          name: Lint the markdown
+          command: |
+            make lint
+
+workflows:
+  version: 2
+  build-workflow:
+    jobs:
+      - test

.markdownlint.yaml

@@ -0,0 +1,3 @@
+line_length:
+  code_blocks: false
+  tables: false

CONTRIBUTING.md

@@ -9,23 +9,50 @@ Whether you are a user or contributor, official support channels include:
 
 ## CLA Requirement
 
-This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
-When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
-
-## Specifications subject to the Open Web Foundation Agreements.
-
-In addition, by making a contribution to specifications in this repository, you, on behalf of yourself, your employer, and its affiliates, are making those contributions subject to the obligations set forth in the [OWF Contributor License Agreement 1.0 - Copyright and Patent](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owf-contributor-license-agreement-1-0---copyright-and-patent).  
-Final specifications developed in this repository will be subject to the [Open Web Foundation Final Specification Agreement (“OWFa 1.0”)](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-00).  OWFa 1.0 will be applied as follows:
-
--	The maintainer will notify all contributors to a designated specification in writing via provided contact information of the start of a 30 day review period, after which the specification will be subject to the OWFa 1.0.
--	During that 30 day period, contributors may provide written notice to the maintainer that the contributor is not making the forgoing commitment under OWFa 1.0 for the designated specification (“Exclusion”).
--	Upon the end of that 30 day notice period, those contributors who have not issued an Exclusion, on behalf of themselves, their employer, and its affiliates, will, without further action, be subject to the obligations set forth in the OWFa 1.0 for the designated specification.  
+This project welcomes contributions and suggestions. Most contributions require
+you to agree to a Contributor License Agreement (CLA) declaring that you have
+the right to, and actually do, grant us the rights to use your contribution. For
+details, visit [https://cla.microsoft.com](https://cla.microsoft.com). When you
+submit a pull request, a CLA-bot will automatically determine whether you need
+to provide a CLA and decorate the PR appropriately (e.g., label, comment).
+Simply follow the instructions provided by the bot. You will only need to do
+this once across all repositories using our CLA.
+
+## Specifications subject to the Open Web Foundation Agreements
+
+In addition, by making a contribution to specifications in this repository, you,
+on behalf of yourself, your employer, and its affiliates, are making those
+contributions subject to the obligations set forth in the [OWF Contributor
+License Agreement 1.0 - Copyright and
+Patent](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owf-contributor-license-agreement-1-0---copyright-and-patent).
+
+Final specifications developed in this repository will be subject to the [Open
+Web Foundation Final Specification Agreement (“OWFa
+1.0”)](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-00).
+OWFa 1.0 will be applied as follows:
+
+- The maintainer will notify all contributors to a designated specification in
+  writing via provided contact information of the start of a 30 day review
+  period, after which the specification will be subject to the OWFa 1.0.
+
+- During that 30 day period, contributors may provide written notice to the
+  maintainer that the contributor is not making the forgoing commitment under
+  OWFa 1.0 for the designated specification (“Exclusion”).
+
+- Upon the end of that 30 day notice period, those contributors who have not
+  issued an Exclusion, on behalf of themselves, their employer, and its
+  affiliates, will, without further action, be subject to the obligations set
+  forth in the OWFa 1.0 for the designated specification.
 
 ## Project Governance
 
 Project maintainership is outlined in the [GOVERNANCE](GOVERNANCE.md) file.
 
 ## Code of Conduct
 
-This project has adopted the [Microsoft Open Source Code of conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [email protected] (mailto:[email protected]) with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of
+conduct](https://opensource.microsoft.com/codeofconduct/). For more information
+see the [Code of Conduct
+FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
+[email protected] (mailto:[email protected]) with any additional
+questions or comments.

GOVERNANCE.md

@@ -2,12 +2,27 @@
 
 ## Project Maintainers
 
-[Project maintainers](CODEOWNERS) are responsible for activities around maintaining and updating the SMI specification. Final decisions on the spec reside with the project maintainers.
+[Project maintainers](CODEOWNERS) are responsible for activities around
+maintaining and updating the SMI specification. Final decisions on the spec
+reside with the project maintainers.
 
-Maintainers MUST remain active. If they are unresponsive for >3 months, they will be automatically removed unless a [super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) of the other project maintainers agrees to extend the period to be greater than 3 months.
+Maintainers MUST remain active. If they are unresponsive for >3 months, they
+will be automatically removed unless a
+[super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) of
+the other project maintainers agrees to extend the period to be greater than 3
+months.
 
-New maintainers can be added to the project by a [super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) vote of the existing maintainers. A potential maintainer may be nominated by an existing maintainer. A vote is conducted in private between the current maintainers over the course of a one week voting period. At the end of the week, votes are counted and a pull request is made on the repo adding the new maintainer to the [CODEOWNERS](CODEOWNERS) file.
+New maintainers can be added to the project by a
+[super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote)
+vote of the existing maintainers. A potential maintainer may be nominated by an
+existing maintainer. A vote is conducted in private between the current
+maintainers over the course of a one week voting period. At the end of the week,
+votes are counted and a pull request is made on the repo adding the new
+maintainer to the [CODEOWNERS](CODEOWNERS) file.
 
-A maintainer may step down by submitting an [issue](https://github.com/deislabs/smi-spec/issues/new) stating their intent.
+A maintainer may step down by submitting an
+[issue](https://github.com/deislabs/smi-spec/issues/new) stating their intent.
 
-Changes to this governance document require a pull request with approval from a [super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) of the current maintainers.
+Changes to this governance document require a pull request with approval from a
+[super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) of
+the current maintainers.

Makefile

@@ -0,0 +1,10 @@
+
+HAS_MDLINT := $(shell command -v markdownlint;)
+
+.PHONY: lint
+lint:
+	@# lint the markdown
+ifndef HAS_MDLINT
+	npm install -g markdownlint-cli
+endif
+	markdownlint -c .markdownlint.yaml .

README.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 ![SMI Logo](./images/smi-banner.png)
 
 ## Service Mesh Interface
@@ -61,18 +62,21 @@ from internal types to those the API expects to return.
 This approach to pluggable interfaces is similar to other core Kubernetes APIs
 like +NetworkPolicy+, +Ingress+ and +CustomMetrics+.
 
-
 ## Communications
 
 ### Slack Channel
-#general Slack channel for related discussion in the
-[SMI Slack](http://smi-spec.slack.com).
 
-If you are not yet a member of the SMI Slack you may sign up [here](https://aka.ms/smi/slack).
+If you are not yet a member of the SMI Slack you may sign up
+[here](https://aka.ms/smi/slack).
+
+## Contributing
 
-### Contributing
+Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on
+contributing to the specification.
 
-Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on contributing to the specification.
+## License
 
-### License
-The specification is licensed under [OWF Contributor License Agreement 1.0 - Copyright and Patent](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owf-contributor-license-agreement-1-0---copyright-and-patent) in the [LICENSE](./LICENSE) file.
+The specification is licensed under [OWF Contributor License Agreement 1.0 -
+Copyright and
+Patent](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owf-contributor-license-agreement-1-0---copyright-and-patent)
+in the [LICENSE](./LICENSE) file.

traffic-access-control.md

@@ -1,4 +1,4 @@
-## Traffic Access Control
+# Traffic Access Control
 
 This set of resources allows users to define access control policy for their
 applications. It is the *authorization* side of the picture. Authentication

traffic-metrics.md

@@ -1,4 +1,4 @@
-## Traffic Metrics
+# Traffic Metrics
 
 This resource provides a common integration point for tools that can benefit by
 consuming metrics related to HTTP traffic. It follows the pattern of

traffic-specs.md

@@ -1,4 +1,4 @@
-## Traffic Spec
+# Traffic Spec
 
 This set of resources allows users to specify how their traffic looks. It is
 used in concert with [access control](traffic-access-control.md) and other

traffic-split.md

@@ -1,4 +1,4 @@
-## Traffic Split
+# Traffic Split
 
 This resource allows users to incrementally direct percentages of traffic
 between various services. It will be used by *clients* such as ingress
@@ -324,8 +324,8 @@ Assume a `TrafficSplit` object that looks like:
 When a new `TrafficSplit` object is created, it instantiates the following Kubernetes
 objects:
 
-    * Service who's name is the same as `spec.service` in the TrafficSplit (`web`)
-    * A Deployment running `nginx` which has labels that match the Service
+* Service who's name is the same as `spec.service` in the TrafficSplit (`web`)
+* A Deployment running `nginx` which has labels that match the Service
 
 The nginx layer serves as an HTTP(s) layer which implements the canary. In
 particular the nginx config looks like: