From b0f7b63e8d6bc8a9199ac6740510c9873710605a Mon Sep 17 00:00:00 2001 From: Hayato Kiwata Date: Tue, 14 May 2024 01:16:16 +0900 Subject: [PATCH] ci: Add a CI to check documentation changes This fix introduces a new CI to check whether the command reference documentations need to be updated. When new commands or options are added, the `finch gen-docs generate -p cmd/finch/` command should be run locally to update the documentation. However, it's easy to forget this step. An issue has also been created that proposes to detect these differences. - https://github.com/runfinch/finch/issues/942 Therefore, in this fix, the new CI step will generate the documentation and compare it with the existing files. If there are differences, the CI will fail, prompting contributors to update the documentations. Signed-off-by: Hayato Kiwata --- .github/workflows/ci-gen-docs.yaml | 58 ++++++++++++++++++ Makefile | 5 ++ docs/gen-docs.go | 96 ++++++++++++++++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 .github/workflows/ci-gen-docs.yaml create mode 100644 docs/gen-docs.go diff --git a/.github/workflows/ci-gen-docs.yaml b/.github/workflows/ci-gen-docs.yaml new file mode 100644 index 000000000..930d856aa --- /dev/null +++ b/.github/workflows/ci-gen-docs.yaml @@ -0,0 +1,58 @@ +# This file is used to make sure that contributors did not forget to generate the documentations for the finch commands. +name: CI +on: + push: + branches: + - main + paths-ignore: + - 'contrib/**' + - '.github/CODEOWNERS' + pull_request: + branches: + - main + paths-ignore: + - 'contrib/**' + - '.github/CODEOWNERS' + +jobs: + check-documentation-changes: + runs-on: macos-latest + steps: + - uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5 + with: + # We need to get all the git tags to make version injection work. See VERSION in Makefile for more detail. + fetch-depth: 0 + persist-credentials: false + submodules: recursive + - uses: actions/setup-go@cdcb36043654635271a94b9a6d1392de5bb323a7 # v5.0.1 + with: + go-version-file: go.mod + cache: true + - name: Clean up previous files + run: | + sudo rm -rf /opt/finch + sudo rm -rf ~/.finch + sudo rm -rf ./_output + if pgrep '^qemu-system'; then + sudo pkill '^qemu-system' + fi + if pgrep '^socket_vmnet'; then + sudo pkill '^socket_vmnet' + fi + - name: Install Rosetta 2 + run: echo "A" | softwareupdate --install-rosetta || true + - run: brew install lz4 automake autoconf libtool yq + shell: zsh {0} + - name: Build project + run: | + export PATH="/opt/homebrew/opt/libtool/libexec/gnubin:$PATH" + make + shell: zsh {0} + - name: Generate docs + run: | + make gen-docs + shell: zsh {0} + - name: Check to generate docs + run: | + git add -N docs/cmd + git diff --exit-code docs/cmd diff --git a/Makefile b/Makefile index a720b778d..670ecc318 100644 --- a/Makefile +++ b/Makefile @@ -374,6 +374,11 @@ else PATH=$(GOBIN):$(PATH) go generate ./... endif +# Generate documentations for the finch commands +.PHONY: gen-docs +gen-docs: + $(GO) run docs/gen-docs.go + .PHONY: lint # To run golangci-lint locally: https://golangci-lint.run/usage/install/#local-installation lint: diff --git a/docs/gen-docs.go b/docs/gen-docs.go new file mode 100644 index 000000000..cb4b5891f --- /dev/null +++ b/docs/gen-docs.go @@ -0,0 +1,96 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +// This program generates documentations for the finch commands. +package main + +import ( + "fmt" + "os" + "os/exec" + "path/filepath" +) + +const ( + virtualMachineRootCmd = "vm" +) + +// Docs is a struct for creating documentations for the finch commands. +type Docs struct { + subject string +} + +// InitVM initializes the VM. +func (d *Docs) InitVM() error { + return exec.Command(d.subject, virtualMachineRootCmd, "init").Run() // #nosec G204 +} + +// StartVM starts the VM. +func (d *Docs) StartVM() error { + return exec.Command(d.subject, virtualMachineRootCmd, "start", "-f").Run() // #nosec G204 +} + +// StopVM stops the VM. +func (d *Docs) StopVM() error { + return exec.Command(d.subject, virtualMachineRootCmd, "stop", "-f").Run() // #nosec G204 +} + +// RemoveVM removes the VM. +func (d *Docs) RemoveVM() error { + return exec.Command(d.subject, virtualMachineRootCmd, "remove", "-f").Run() // #nosec G204 +} + +// CreateDocs create documentations for the finch commands. +func (d *Docs) CreateDocs() error { + return exec.Command(d.subject, "gen-docs", "generate", "-p", "docs/cmd/").Run() // #nosec G204 +} + +// GetSubject returns the subjects for the finch command. +func GetSubject() (string, error) { + wd, err := os.Getwd() + if err != nil { + return "", fmt.Errorf("failed to get the current working directory: %w", err) + } + + subject := filepath.Join(wd, "_output", "bin", "finch") + + return subject, nil +} + +// NewDocs creates an object of type Docs. +func NewDocs() (*Docs, error) { + d := Docs{} + + subject, err := GetSubject() + if err != nil { + return &d, err + } + d.subject = subject + + return &d, nil +} + +func main() { + d, err := NewDocs() + if err != nil { + fmt.Printf("NewDocs Error: %s\n", err.Error()) + return + } + + err = d.StopVM() + if err != nil { + fmt.Printf("Stopping the VM Error: %s\n", err.Error()) + } + err = d.RemoveVM() + if err != nil { + fmt.Printf("Removing the VM Error: %s\n", err.Error()) + } + err = d.InitVM() + if err != nil { + fmt.Printf("Init the VM Error: %s\n", err.Error()) + } + err = d.CreateDocs() + if err != nil { + fmt.Printf("Creating Docs Error: %s\n", err.Error()) + } +}