From 72e1e597f04f5c871f68feae1f0f5044cb3e0b50 Mon Sep 17 00:00:00 2001 From: "Hsing-Yu (David) Chen" Date: Fri, 9 Dec 2022 04:53:27 +0800 Subject: [PATCH] ci: add mdlint (#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 --- .github/workflows/ci-docs.yaml | 9 +++++ .github/workflows/ci.yaml | 9 +++++ .markdownlint.yaml | 2 + CONTRIBUTING.md | 67 +++++++++++++++++----------------- Makefile | 13 +++++++ README.md | 22 ++++++----- contrib/hello-finch/README.md | 9 +++-- 7 files changed, 84 insertions(+), 47 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.github/workflows/ci-docs.yaml b/.github/workflows/ci-docs.yaml index b583b4eda..4b174fed0 100644 --- a/.github/workflows/ci-docs.yaml +++ b/.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' diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 93b2587c0..5b2d30f7c 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -107,3 +107,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' diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 000000000..71a801501 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,2 @@ +# Modern IDEs usually automatically wrap long lines in *.md files, so this may be unnecessary. +line-length: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e7ac993e..a2e876f8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,11 +17,9 @@ - [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! 💖 @@ -29,9 +27,9 @@ 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,12 +132,12 @@ 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 @@ -148,10 +145,10 @@ VM instance is not expected to exist before running e2e tests, please make sure 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 +Signed-off-by: Your Name +``` 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``` diff --git a/Makefile b/Makefile index f28c4ec74..26fab18fa 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index fe5d9a635..aa63da6d3 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ + Finch logo -### Hello, Finch +## Hello, Finch + 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. @@ -12,11 +14,11 @@ Finch provides a simple client which is integrated with [nerdctl](https://github 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. diff --git a/contrib/hello-finch/README.md b/contrib/hello-finch/README.md index 900b3b990..e3f8b2847 100644 --- a/contrib/hello-finch/README.md +++ b/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 ```