Merge pull request #6 from Shopify/contributing-and-linter

Contributing and linter

.github/workflows/ci.yaml

@@ -12,8 +12,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # tag=v3.0.2
-        with:
-          fetch-depth: 0
       - name: Get latest Go version
         id: gover
         run: echo ::set-output name=goversion::$(grep "AS apk" Dockerfile.test | awk -F':|-' '!/^#/ {print $2}')
@@ -22,11 +20,28 @@ jobs:
         with:
           go-version: "${{ steps.gover.outputs.goversion }}"
       - run: go test -race ./...
-  integration:
+
+  lint:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # tag=v3.0.2
+      - name: Get latest Go version
+        id: gover
+        run: echo ::set-output name=goversion::$(grep "AS apk" Dockerfile.test | awk -F':|-' '!/^#/ {print $2}')
+      - name: Set up Go
+        uses: actions/setup-go@f6164bd8c8acb4a71fb2791a8b6c4024ff038dab # tag=v3.0.0
         with:
-          fetch-depth: 0
+          go-version: "${{ steps.gover.outputs.goversion }}"
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@537aa1903e5d359d0b27dbc19ddd22c5087f3fbc # tag=v3.2.0
+        with:
+          version: v1.46.2
+          args: --timeout=5m
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # tag=v3.0.2
       - run: docker build -f Dockerfile.test .

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Development
+
+* For tests, use standard Go tooling: `go test ./...`
+* For lint, use [golangci-lint](https://golangci-lint.run/): `golangci-lint run ./...`
+* For integration tests, use Docker to provide test environments: `docker build -f Dockerfile.test .`
+* Hansel uses [goreleaser](https://goreleaser.com/), but this is not required for development.
+
+# Releasing
+
+Releases are built and published from GitHub Actions. Release versions follow semver.
+
+To trigger a release:
+1. Determine the appropriate version increment, as a rule of thumb:
+   * If removing a CLI argument, increment the major version.
+   * If adding a CLI argument, increment the minor version.
+   * Else, increment the patch version.
+1. Check the [release history](https://github.com/Shopify/hansel/releases) and increment to determine the next version. e.g. a patch increment to `v1.2.2` would be `v1.2.3`.
+1. Create a tag with the next version, push the tag:
+```bash
+git checkout main
+git pull origin main
+git log -1 # double-check the expected commit
+git tag -a v1.2.3 -m "v1.2.3 release"
+git push --tags
+```
+4. Monitor the release process from [GitHub Actions](https://github.com/Shopify/hansel/actions/workflows/release.yaml).

README.md

@@ -2,7 +2,19 @@
 
 Hansel generates empty linux packages. These packages can be installed to track dependencies manually added to a container image.
 
-You can use hansel in a multistep build:
+<!-- TODO: make a gif? -->
+
+## Usage
+
+You can add hansel to an image, and generate + install tracking packages for dependencies in a single step:
+```dockerfile
+FROM node:18-alpine
+
+COPY --from=ghcr.io/Shopify/hansel:latest /usr/bin/hansel /usr/bin/hansel
+RUN hansel --name node --version "$(node -v)" --install
+```
+
+You can use hansel in a multistep build to generate and install separately:
 ```dockerfile
 FROM ghcr.io/Shopify/hansel:latest AS crumbs
 RUN hansel --name rando-thing --version v1.2.3 --debian
@@ -14,6 +26,4 @@ RUN dpkg -i /tmp/rando-thing.deb && \
     rm /tmp/rando-thing.deb
 ```
 
-The name is inspired by:
-* [Hansel and Gretel](https://en.wikipedia.org/wiki/Hansel_and_Gretel), as the packages are breadcrumbs left for container scanners to identify.
-* [Owen Wilson's character in the 2001 movie "Zoolander"](https://www.youtube.com/watch?v=FAxJECJJG6w), as supply chain observability is "so hot right now".
+The name is inspired by [Hansel and Gretel](https://en.wikipedia.org/wiki/Hansel_and_Gretel), as the packages are breadcrumbs left for container scanners to identify.

internal/cli/app.go

@@ -7,9 +7,10 @@ import (
 
 func NewApp(log logr.Logger) *cli.App {
 	return &cli.App{
-		Name:   "hansel",
-		Usage:  "create empty packages as breadcrumbs",
-		Flags:  GenerateFlags,
-		Action: Generate(log),
+		Name:            "hansel",
+		Usage:           "create empty packages as breadcrumbs for use when auditing container contents",
+		Flags:           GenerateFlags,
+		HideHelpCommand: true,
+		Action:          Generate(log),
 	}
 }

internal/cli/generate.go

@@ -32,20 +32,37 @@ const (
 )
 
 var GenerateFlags = []cli.Flag{
-	&cli.StringFlag{Name: FlagPkgName, Usage: "package name"},
-	&cli.StringFlag{Name: FlagPkgArch, Usage: "package architecture"},
-	&cli.StringFlag{Name: FlagPkgVersion, Usage: "package version"},
-	&cli.StringFlag{Name: pkgMaintainer, Usage: "package maintainer"},
-	&cli.StringFlag{Name: pkgDescription, Usage: "package description", Value: "hansel virtual package"},
-
-	&cli.StringFlag{Name: FlagOutDirectory, Usage: "output directory", Value: "."},
-	&cli.StringFlag{Name: FlagOutFilename, Usage: "output filename, generated if not provided"},
-	&cli.BoolFlag{Name: FlagOutApk, Usage: "generate apk package", Aliases: []string{"alpine"}},
-	&cli.BoolFlag{Name: FlagOutDeb, Usage: "generate deb package", Aliases: []string{"debian", "ubuntu"}},
-	&cli.BoolFlag{Name: FlagOutRpm, Usage: "generate rpm package", Aliases: []string{"fedora", "rhel"}},
+	&cli.StringFlag{Name: FlagPkgName, Usage: "package name", Category: "Parameters"},
+	&cli.StringFlag{Name: FlagPkgArch, Usage: "package architecture", Category: "Parameters"},
+	&cli.StringFlag{Name: FlagPkgVersion, Usage: "package version", Category: "Parameters"},
+	&cli.StringFlag{Name: pkgMaintainer, Usage: "package maintainer", Category: "Parameters"},
+	&cli.StringFlag{
+		Name:     pkgDescription,
+		Usage:    "package description",
+		Value:    "hansel virtual package",
+		Category: "Parameters",
+	},
+
+	&cli.StringFlag{Name: FlagOutDirectory, Usage: "output directory", Value: ".", Category: "Output"},
+	&cli.StringFlag{Name: FlagOutFilename, Usage: "output filename, generated if not provided", Category: "Output"},
+
+	&cli.BoolFlag{Name: FlagOutApk, Usage: "generate apk package", Aliases: []string{"alpine"}, Category: "Packages"},
+	&cli.BoolFlag{
+		Name:     FlagOutDeb,
+		Usage:    "generate deb package",
+		Aliases:  []string{"debian", "ubuntu"},
+		Category: "Packages",
+	},
+	&cli.BoolFlag{
+		Name:     FlagOutRpm,
+		Usage:    "generate rpm package",
+		Aliases:  []string{"fedora", "rhel"},
+		Category: "Packages",
+	},
 	&cli.BoolFlag{
-		Name:  FlagInstall,
-		Usage: "install the package automatically and delete the file",
+		Name:     FlagInstall,
+		Usage:    "install the package automatically and delete the file",
+		Category: "Packages",
 	},
 }