Add coverall CI pipeline, add doc about testing approach, replace md …

…file formatter (#54) * Use prettier instead of mdox, re-format docs, respect 2 space indents
mszostok · Oct 1, 2022 · d6a27bc · d6a27bc
1 parent 81dd88a
commit d6a27bc
Show file tree

Hide file tree

Showing 23 changed files with 323 additions and 174 deletions.
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,19 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+  categories:
+    - title: Breaking Changes 🛠
+      labels:
+        - Semver-Major
+        - breaking-change
+    - title: Enhancements 🚀
+      labels:
+        - Semver-Minor
+        - enhancement
+    - title: Fixed Bugs 🐛
+      labels:
+        - bug
+    - title: Other Changes ✨
+      labels:
+        - "*"
diff --git a/.github/workflows/coverall.yml b/.github/workflows/coverall.yml
@@ -0,0 +1,41 @@
+name: Coverall
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+
+jobs:
+  test:
+    name: Test with Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Set git to use LF"
+        run: |
+          git config --global core.autocrlf false
+          git config --global core.eol lf
+      - name: "Checkout code"
+        uses: actions/checkout@v3
+      - name: "Set up Go"
+        uses: actions/setup-go@v3
+        with:
+          go-version: '1.19.1' # must be hardcoded as it's expected in tests
+          cache: true
+      - uses: szenius/set-timezone@a5c1676bd4e141779a42a699cc086f3c5ddd1a6c
+        with:
+          timezoneLinux: "Europe/Warsaw"
+          timezoneMacos: "Europe/Warsaw"
+          timezoneWindows: "Central European Standard Time"
+      - name: "Unit tests"
+        uses: magefile/mage-action@5f7a9a23cfef763949ca41834b868167adbd1b59 # v2.0.0
+        with:
+          version: latest
+          args: test:unit
+
+      - name: "Install goveralls"
+        run: go install github.com/mattn/goveralls@latest
+      - name: "Send coverage"
+        env:
+          COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: goveralls -coverprofile=coverage.out -service=github
diff --git a/docs/community/testing.md b/docs/community/testing.md
@@ -0,0 +1,41 @@
+# Package testing
+
+The `version` package is tested both via unit and e2e tests.
+
+## Unit tests
+
+Unit tests focus more on the corner cases that are hard to reproduce using e2e testing. Unit tests are executed on CI via [**Testing**](https://github.com/mszostok/version/actions/workflows/testing.yml) workflow.
+
+- All tests are executed with the latest Go version on all platforms, using GitHub Action job strategy:
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-latest, macos-latest, windows-latest]
+  ```
+- All tests are run both on pull-requests and the `main` branch
+- The tests' coverage is uploaded to [coveralls.io/github/mszostok/version](https://coveralls.io/github/mszostok/version)
+
+## E2E tests
+
+The e2e tests build a Go binary, run it, and compare with [golden files](https://github.com/mszostok/version/tree/main/tests/e2e/testdata). E2E tests are executed on CI via [**Testing**](https://github.com/mszostok/version/actions/workflows/testing.yml) workflow.
+
+As a result, e2e test focus on:
+
+- Building Go binaries
+- Overriding version information via `ldflags`
+- Running binary on operating system
+- Testing if color output for non-tty output streams is disabled automatically
+- Ensuring that all [examples](https://github.com/mszostok/version/tree/main/examples) are runnable
+- Executing a real call against GitHub API
+- Executing binaries on all platforms, using GitHub Action job strategy:
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-latest, macos-latest, windows-latest]
+  ```
+
+Each time a new functionality is implemented, a dedicated [test case](https://github.com/mszostok/version/blob/main/tests/e2e/e2e_test.go#L31) is added.
+
+!!! note
+
+    Currently, there is no easy way to calculate the coverage based on the e2e tests (built and executed binaries). However, this will be enabled once the [golang#51430](https://github.com/golang/go/issues/51430) issue will be implemented.
diff --git a/docs/customization/extra-fields.md b/docs/customization/extra-fields.md
@@ -3,6 +3,7 @@
 The `version` package supports most popular version fields natively.
 
 ??? example "Native fields"
+
      | Key           | Description                                                                                                     |
      |---------------|-----------------------------------------------------------------------------------------------------------------|
      | `.Version`    | Binary version value set via `-ldflags`, otherwise taken from `go install url/tool@version`.                    |
@@ -28,7 +29,7 @@ Steps:
 
 1. Assign your custom struct to `Info.ExtraFields`.
 
-      Go struct with nested fields are not properly supported in Pretty mode.
+   Go struct with nested fields are not properly supported in Pretty mode.
 
 2. Use `json`, `yaml` and `pretty` field tags to define the field name for a given output format.
 3. In the Pretty mode, fields are printed in the same order as defined in struct.

diff --git a/docs/customization/omit-unset.md b/docs/customization/omit-unset.md
@@ -6,21 +6,21 @@
 
 - Explicitly exclude a given set of version fields:
 
-    ```go
-    // excludedFields defines preset for fields that should be excluded in output.
-    const excludedFields = printer.FieldCompiler | printer.FieldPlatform
+  ```go
+  // excludedFields defines preset for fields that should be excluded in output.
+  const excludedFields = printer.FieldCompiler | printer.FieldPlatform
 
-    p := printer.New(printer.WithExcludedFields(excludedFields))
-    if err := p.Print(os.Stdout); err != nil {
-    	log.Fatal(err)
-    }
-    ```
+  p := printer.New(printer.WithExcludedFields(excludedFields))
+  if err := p.Print(os.Stdout); err != nil {
+  	log.Fatal(err)
+  }
+  ```
 
 - Don't display empty(`""`) and unset(`N/A`) version fields:
 
-    ```go
-    p := printer.New(printer.WithOmitUnset(excludedFields))
-    if err := p.Print(os.Stdout); err != nil {
-    	log.Fatal(err)
-    }
-    ```
+  ```go
+  p := printer.New(printer.WithOmitUnset(excludedFields))
+  if err := p.Print(os.Stdout); err != nil {
+  	log.Fatal(err)
+  }
+  ```
diff --git a/docs/customization/pretty/format.md b/docs/customization/pretty/format.md
@@ -1,6 +1,7 @@
 # Format
 
 !!! note ""
+
     Formatting focuses on the style of your displayed pretty version data.
 
 Format lets you define your own theme and adjust the output to your branding colors. In general, you can add underscores, bold and italic formatting, text, and background colors.

diff --git a/docs/customization/pretty/layout.md b/docs/customization/pretty/layout.md
@@ -1,14 +1,15 @@
 # Layout
 
 !!! note ""
+
     Layout focuses on structured arrangement of pretty version data.
 
 To define the layout, use [Go templating](https://pkg.go.dev/html/template). You can also use the [`version` package's built-in functions](https://github.com/mszostok/version/blob/main/style/go-tpl-funcs.go) that respect the [formatting settings](./format.md). All helper functions defined by the [Sprig template library](https://masterminds.github.io/sprig/) are also available.
 
 These are the fields that you can access in your Go template definition:
 
 | Key           | Description                                                                                                     |
-|---------------|-----------------------------------------------------------------------------------------------------------------|
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
 | `.Version`    | Binary version value set via `-ldflags`, otherwise taken from `go install url/tool@version`.                    |
 | `.GitCommit`  | Git commit value set via `-ldfags`, otherwise taken from `debug.ReadBuildInfo()` - the `vcs.revision` tag.      |
 | `.BuildDate`  | Build date value set via `-ldflags`, otherwise empty.                                                           |
@@ -18,7 +19,6 @@ These are the fields that you can access in your Go template definition:
 | `.Compiler`   | Go compiler taken from `runtime.Compiler`.                                                                      |
 | `.Platform`   | Build platform, passed in the following format: `runtime.GOOS/runtime.GOARCH`.                                  |
 
-
 ## Go
 
 !!! tip
@@ -50,7 +50,6 @@ func main() {
 }
 ```
 
-
 ## Config file
 
 !!! coming-soon "Coming soon"
@@ -70,7 +69,7 @@ To load the config file, you can:
       goTemplate: |
         {{ AdjustKeyWidth .ExtraFields }}
         {{ Header .Meta.CLIName }}
-    
+
           {{ Key "Version"     }}    {{ .Version                     | Val }}
           {{ Key "Git Commit"  }}    {{ .GitCommit  | Commit         | Val }}
           {{ Key "Build Date"  }}    {{ .BuildDate  | FmtDate        | Val }}
@@ -100,4 +99,3 @@ To load the config file, you can:
     }
     ```
     <!-- JSONLayout end -->
-
diff --git a/docs/customization/upgrade-notice/custom-renderer.md b/docs/customization/upgrade-notice/custom-renderer.md
@@ -23,7 +23,8 @@ func NewRoot() *cobra.Command {
 		// 1. Register the 'version' command
 		extension.NewVersionCobraCmd(
 			// 2. Explicitly enable the upgrade notice
-			extension.WithUpgradeNotice("mszostok", "codeowners-validator", opts...)),
+			extension.WithUpgradeNotice("mszostok", "codeowners-validator", opts...),
+		),
 	)
 
 	return cmd