ci: add mdlint (runfinch#88)

## Summary

PR adds [markdownlint](https://github.com/DavidAnson/markdownlint) to CI
and Makefile. It ensures a consistent markdown style, and it also
provides some useful checks (e.g., [broken link
fragments](https://github.com/DavidAnson/markdownlint/blob/v0.26.2/doc/Rules.md#md051)).

## License Acceptance

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Signed-off-by: Hsing-Yu (David) Chen <[email protected]>

.github/workflows/ci-docs.yaml

@@ -50,3 +50,12 @@ jobs:
     runs-on: ${{ matrix.os }} 
     steps:
       - run: echo "Skipping CI for docs & contrib files"
+  mdlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: avto-dev/markdown-lint@v1
+        with:
+          args: '**/*.md'
+          # CHANGELOG.md is only updated by release-please bot.
+          ignore: 'CHANGELOG.md'

.github/workflows/ci.yaml

@@ -108,3 +108,12 @@ jobs:
           which libtool
           make
       - run: make test-e2e
+  mdlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: avto-dev/markdown-lint@v1
+        with:
+          args: '**/*.md'
+          # CHANGELOG.md is only updated by release-please bot.
+          ignore: 'CHANGELOG.md'

.markdownlint.yaml

@@ -0,0 +1,2 @@
+# Modern IDEs usually automatically wrap long lines in *.md files, so this may be unnecessary.
+line-length: false

CONTRIBUTING.md

@@ -17,21 +17,19 @@
   - [Sign Your Commits](#sign-your-commits)
     - [DCO](#dco)
   - [Pull Request Checklist](#pull-request-checklist)
-    - [Build](#build-1)
-    - [Lint](#lint)
     - [Testing](#testing)
       - [Unit Testing - Parallel by Default](#unit-testing---parallel-by-default)
-      - [E2E Testing](#e2e-testing-1)
+      - [E2E Testing Guidelines](#e2e-testing-guidelines)
     - [Go File Naming](#go-file-naming)
 
 Welcome! We are glad that you want to contribute to our project! 💖
 
 As you get started, you are in the best position to give us feedback on areas of
 our project that we need help with including:
 
-* Problems found during setting up a new developer environment
-* Gaps in our Quickstart Guide or documentation
-* Bugs in our automation scripts
+- Problems found during setting up a new developer environment
+- Gaps in our Quickstart Guide or documentation
+- Bugs in our automation scripts
 
 If anything doesn't make sense, or doesn't work when you run it, please open a
 bug report and let us know!
@@ -58,13 +56,13 @@ Maintainers are established contributors who are responsible for the entire proj
 
 We welcome many different types of contributions including:
 
-* New features
-* Builds, CI/CD
-* Bug fixes
-* Documentation
-* Issue Triage
-* Communications / Social Media / Blog Posts
-* Release management
+- New features
+- Builds, CI/CD
+- Bug fixes
+- Documentation
+- Issue Triage
+- Communications / Social Media / Blog Posts
+- Release management
 
 ## Find an Issue
 
@@ -118,15 +116,14 @@ For more details, see [`.golangci.yaml`](./.golangci.yaml) and the `lint` target
 After cloning the repo, run `make` to build the binary.
 
 The binary in _output can be directly used. E.g. initializing the vm and display the version
-```
-./_output/bin/finch vm init
 
+```sh
+./_output/bin/finch vm init
 ./_output/bin/finch version
 ```
 
 You can run `make install` to make finch binary globally accessible.
 
-
 ### Unit Testing
 
 To run unit test locally, please run `make test-unit`. Please make sure to run the unit tests before pushing the changes.
@@ -135,23 +132,23 @@ Ideally each go file should have a test file ending with `_test.go`, and we shou
 
 To check unit test coverage, run `make coverage` under root finch-cli root directory.
 
-
 ### E2E Testing
 
 Run these steps at the first time of running e2e tests
 
 VM instance is not expected to exist before running e2e tests, please make sure to remove it before going into next step:
+
 ```sh
 ./_output/bin/finch vm stop
 ./_output/bin/finch vm remove
 ```
 
 To run e2e test locally, please run `make test-e2e`. Please make sure to run the e2e tests or add new e2e tests before pushing the changes.
 
-
 ## Sign Your Commits
 
 ### DCO
+
 Licensing is important to open source projects. It provides some assurances that
 the software will continue to be available based under the terms that the
 author(s) desired. We require that contributors sign off on commits submitted to
@@ -162,33 +159,37 @@ have the right to contribute the code you are submitting to the project.
 You sign-off by adding the following to your commit messages. Your sign-off must
 match the git user and email associated with the commit.
 
-    This is my commit message
+```text
+This is my commit message
 
-    Signed-off-by: Your Name <[email protected]>
+Signed-off-by: Your Name <[email protected]>
+```
 
 Git has a `-s` command line option to do this automatically:
 
-    git commit -s -m 'This is my commit message'
+```sh
+git commit -s -m 'This is my commit message'
+```
 
 If you forgot to do this and have not yet pushed your changes to the remote
 repository, you can amend your commit with the sign-off by running
 
-    git commit --amend -s
+```sh
+git commit --amend -s --no-edit
+```
 
 ## Pull Request Checklist
 
-When you submit your pull request, or you push new commits to it, our automated
-systems will run some checks on your new code. We require that your pull request
-passes these checks, but we also have more criteria than just that before we can
-accept and merge it. We recommend that you check the following things locally
-before you submit your code:
-
-### Build
+When you submit your pull request, or you push new commits to it, our automated systems will run some checks on your new code. We require that your pull request passes these checks, and you can run the checks locally to iterate faster (you may need to [configure the environment](#development-environment-setup) first):
 
-```make```
+```sh
+make test-unit
+make test-e2e
+make lint
+```
 
-### Lint
-```make lint```
+We also have more criteria than just that before we can accept and merge it. We recommend that you check the following things locally
+before you submit your code:
 
 ### Testing
 
@@ -207,7 +208,7 @@ Rationale:
 
 Keeping a good unit test coverage will be part of pull request review. You can run `make coverage` to self-check the coverage.
 
-#### E2E Testing
+#### E2E Testing Guidelines
 
 ```make test-e2e```
 

Makefile

@@ -186,6 +186,8 @@ download-licenses:
 	curl https://raw.githubusercontent.com/actions/setup-go/main/LICENSE --output "$(LICENSEDIR)/github.com/actions/setup-go/LICENSE"
 	mkdir -p "$(LICENSEDIR)/github.com/golangci/golangci-lint-action"
 	curl https://raw.githubusercontent.com/golangci/golangci-lint-action/master/LICENSE --output "$(LICENSEDIR)/github.com/golangci/golangci-lint-action/LICENSE"
+	mkdir -p "$(LICENSEDIR)/github.com/avto-dev/markdown-lint"
+	curl https://raw.githubusercontent.com/avto-dev/markdown-lint/master/LICENSE --output "$(LICENSEDIR)/github.com/avto-dev/markdown-lint/LICENSE"
 
     ### dependencies in ci.yaml - end ###
 
@@ -260,6 +262,17 @@ gen-code:
 lint:
 	golangci-lint run
 
+.PHONY: mdlint
+# Install it locally: https://github.com/igorshubovych/markdownlint-cli#installation
+# Or see `mdlint-ctr` below or https://github.com/DavidAnson/markdownlint#related.
+mdlint:
+	markdownlint --ignore CHANGELOG.md '**/*.md'
+
+.PHONY: mdlint-ctr
+# If markdownlint is not installed, you can run markdownlint within a container.
+mdlint-ctr:
+	finch run --rm -v "$(shell pwd):/repo:ro" -w /repo avtodev/markdown-lint:v1 --ignore CHANGELOG.md '**/*.md'
+
 .PHONY: clean
 clean:
 	-@rm -rf $(OUTDIR) 2>/dev/null || true

README.md

@@ -1,22 +1,24 @@
+<!-- markdownlint-disable first-line-h1 no-inline-html -->
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/runfinch/finch/main/contrib/logo/Finch_Horizontal_White.svg">
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/runfinch/finch/main/contrib/logo/Finch_Horizontal_Black.svg">
   <img alt="Finch logo" width=40% height=auto src="https://raw.githubusercontent.com/runfinch/finch/main/contrib/logo/Finch_Horizontal_Black.svg">
 </picture>
 
-### Hello, Finch
+## Hello, Finch
+<!-- markdownlint-restore -->
 
 Finch is an open source client for container development. Its simple installer provides a minimal native client along with an opinionated distribution of other open source components. Rather than creating even more options to reason about and choose from, Finch aims to help promote other projects by making it easy to install and use them, while offering a simple native client to tie it all together.
 
 Finch provides a simple client which is integrated with [nerdctl](https://github.com/containerd/nerdctl). For the core build/run/push/pull commands, Finch depends upon nerdctl to handle the heavy lifting. It works with [containerd](https://containerd.io) for container management, and with [BuildKit](https://github.com/moby/buildkit) to handle Open Container Initiative (OCI) image builds. These components are all pulled together and run within a virtual machine managed by [Lima](https://github.com/lima-vm/lima).
 
 With Finch, you can leverage these existing projects without chasing down all the details. Just install and start running and building your containers!
 
-### Getting Started with Finch on macOS
+## Getting Started with Finch on macOS
 
 The project will in the near future have a more full set of documentation and tutorials. For now let's get started here. As mentioned above, `finch` integrates with `nerdctl`. While Finch doesn't implement 100% of the upstream commands, the most common commands are in place and working. The [nerdctl Command Reference](https://github.com/containerd/nerdctl#command-reference) can be relied upon as a starting point for documentation.
 
-#### Installing Finch
+### Installing Finch
 
 To get started with Finch on macOS, the prerequisites are:
 
@@ -29,7 +31,7 @@ Download a release package for your architecture from the [project's GitHub rele
 #### Installing Finch via [brew](https://brew.sh/)
 
 ```sh
-$ brew install --cask finch
+brew install --cask finch
 ```
 
 Once the installation is complete, `finch vm init` is required once to set up the underlying system. This initial setup usually takes about a minute.
@@ -41,7 +43,7 @@ INFO[0000] Initializing and starting Finch virtual machine...
 INFO[0067] Finch virtual machine started successfully
 ```
 
-#### Running containers and building images
+### Running containers and building images
 
 You can now run a test container. If you're familiar with container development, you can use the `run` command as you'd expect.
 
@@ -76,19 +78,19 @@ Linux x86_64
 
 You can also use the `--platform` option with builds, making it easy to create multiplatform images.
 
-### Working with Finch
+## Working with Finch
 
 We have plans to create some more documentation and tutorials here geared toward users who are new to containers, as well as some tips and tricks for more advanced users. For now, if you're ready to kick the tires, please do! You'll find most commands and options you're familiar with from other tools to present, and as you'd expect (or, as they are [documented upstream with nerdctl](https://github.com/containerd/nerdctl#command-reference)). Most of the commands we use every day are covered, including volume and network management as well as Compose support. If Finch doesn't do something you want it to, please consider opening an Issue or a Pull Request.
 
-####  Finch and other tools
+### Finch and other tools
 
 The installer will install Finch and its dependencies in its own area of your system, and it can happily coexist with other container development tools. Finch is a new project and not meant to be a direct drop-in replacement for other tools. Therefore, we don't recommend aliasing or linking other command names to `finch`.
 
-#### A note on volume mounts
+### A note on volume mounts
 
 The `run` command has a `-v` option for volume mounts. See `Volume flags` under [nerdctl run](https://github.com/containerd/nerdctl#whale-blue_square-nerdctl-run) for more details, if you're not familiar. This allows you to mount directories from your local host into your container. One thing to note with Finch: currently, only locations within `$HOME` are supported by the volume mount `-v` option. Specifying directories outside `$HOME` may cause unexpected behavior. Support for other mount locations will be added soon.
 
-#### Configuration
+### Configuration
 
 Finch has a simple and extensible configuration. A configuration file at `${HOME}/.finch/finch.yaml` will be generated on first run. Currently, this config file has options for system resource limits for the underlying virtual machine. These default limits are generated dynamically based on the resources available on the host system, but can be changed by manually editing the config file.
 
@@ -106,7 +108,7 @@ cpus: 4
 memory: 4GiB
 ```
 
-### What's next?
+## What's next?
 
 We are excited to start this project in the open, and we'd love to hear from you. If you have ideas or find bugs please open an issue. Please feel free to start a discussion if you have something you'd like to propose or brainstorm. Pull requests are welcome, as well! See the [CONTRIBUTING](CONTRIBUTING.md) doc for more info on contributing, and the path to reviewer and maintainer roles for those interested.
 

contrib/hello-finch/README.md

@@ -1,7 +1,8 @@
-# hello, finch!
+# hello, finch
+
 Say hello to Finch :wave:
 
-```
-$ finch build . -t hello-finch
-$ finch run --rm hello-finch
+```sh
+finch build . -t hello-finch
+finch run --rm hello-finch
 ```