From daa32d01f2062b915492cb82f2ea160806065323 Mon Sep 17 00:00:00 2001 From: docktermj Date: Tue, 20 Aug 2024 17:17:30 -0400 Subject: [PATCH 1/4] #69 migrate from g2 to sz/er --- .github/coverage/README.md | 20 ++ .../coverage/testcoverage.yaml | 0 .github/dependabot.yml | 6 +- .github/linters/.checkov.yaml | 3 +- .../linters/{.golangci.yml => .golangci.yaml} | 3 +- .github/linters/.jscpd.json | 6 +- .github/linters/README.md | 54 +++++ .github/workflows/README.md | 205 ++++++++++++++++++ .../workflows/add-labels-standardized.yaml | 2 +- .../add-to-project-garage-dependabot.yaml | 2 +- .github/workflows/add-to-project-garage.yaml | 2 +- .../dependabot-approve-and-merge.yaml | 2 +- .github/workflows/go-proxy-pull.yaml | 6 +- .github/workflows/go-test-darwin.yaml | 29 ++- .github/workflows/go-test-linux.yaml | 29 ++- .github/workflows/go-test-windows.yaml | 29 ++- .github/workflows/lint-workflows.yaml | 2 +- .github/workflows/make-go-github-file.yaml | 2 +- .github/workflows/make-go-tag.yaml | 8 +- .../workflows/move-pr-to-done-dependabot.yaml | 2 +- .gitignore | 4 + CONTRIBUTING.md | 50 +++-- Makefile | 93 +++++--- README.md | 68 ++++-- cmd/cmd_test.go | 34 ++- cmd/root.go | 26 +-- docs/README.md | 7 +- docs/development.md | 147 +++++++++++-- docs/examples.md | 5 - go.mod | 10 +- go.sum | 20 +- main_test.go | 3 - makefiles/darwin.mk | 20 +- makefiles/linux.mk | 23 +- makefiles/windows.mk | 27 ++- package.Dockerfile | 72 +++--- 36 files changed, 778 insertions(+), 243 deletions(-) create mode 100644 .github/coverage/README.md rename .testcoverage.yml => .github/coverage/testcoverage.yaml (100%) rename .github/linters/{.golangci.yml => .golangci.yaml} (98%) create mode 100644 .github/linters/README.md create mode 100644 .github/workflows/README.md diff --git a/.github/coverage/README.md b/.github/coverage/README.md new file mode 100644 index 0000000..9ca939c --- /dev/null +++ b/.github/coverage/README.md @@ -0,0 +1,20 @@ +# Coverage + +## testcoverage.yaml + +- [testcoverage.yaml] +- Used by `coverage:` in + - [go-test-darwin.yaml] + - [go-test-linux.yaml] + - [go-test-windows.yaml] +- [go-test-coverage] + - [go-test-coverage configuration] + - [go-test-coverage badge] + +[go-test-darwin.yaml]: ../workflows/README.md#go-test-darwinyaml +[go-test-linux.yaml]: ../workflows/README.md#go-test-linuxyaml +[go-test-windows.yaml]: ../workflows/README.md#go-test-windowsyaml +[testcoverage.yaml]: testcoverage.yaml +[go-test-coverage]: https://github.com/vladopajic/go-test-coverage +[go-test-coverage configuration]: https://github.com/vladopajic/go-test-coverage?tab=readme-ov-file#config +[go-test-coverage badge]: https://github.com/vladopajic/go-test-coverage/blob/main/docs/badge.md diff --git a/.testcoverage.yml b/.github/coverage/testcoverage.yaml similarity index 100% rename from .testcoverage.yml rename to .github/coverage/testcoverage.yaml diff --git a/.github/dependabot.yml b/.github/dependabot.yml index e2a98a1..a95f6be 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -3,10 +3,10 @@ version: 2 updates: - - package-ecosystem: "github-actions" - directory: "/" + - package-ecosystem: github-actions + directory: / schedule: - interval: "daily" + interval: daily - package-ecosystem: gomod directory: / schedule: diff --git a/.github/linters/.checkov.yaml b/.github/linters/.checkov.yaml index e2d7c03..86c8083 100644 --- a/.github/linters/.checkov.yaml +++ b/.github/linters/.checkov.yaml @@ -1,2 +1,3 @@ quiet: true -skip-check: CKV_DOCKER_7 +skip-check: + - CKV_DOCKER_7 diff --git a/.github/linters/.golangci.yml b/.github/linters/.golangci.yaml similarity index 98% rename from .github/linters/.golangci.yml rename to .github/linters/.golangci.yaml index 389317d..8c22489 100644 --- a/.github/linters/.golangci.yml +++ b/.github/linters/.golangci.yaml @@ -1,9 +1,10 @@ run: modules-download-mode: readonly - show-stats: true + timeout: 10m output: print-linter-name: false + show-stats: true sort-results: true linters: diff --git a/.github/linters/.jscpd.json b/.github/linters/.jscpd.json index 3a60fa8..9e26dfe 100644 --- a/.github/linters/.jscpd.json +++ b/.github/linters/.jscpd.json @@ -1,5 +1 @@ -{ - "ignore": [ - "**/*.go,**/go-test*.yaml" - ] -} \ No newline at end of file +{} \ No newline at end of file diff --git a/.github/linters/README.md b/.github/linters/README.md new file mode 100644 index 0000000..7bc3d2e --- /dev/null +++ b/.github/linters/README.md @@ -0,0 +1,54 @@ +# Linters + +## .checkov.yaml + +- [.checkov.yaml] +- Used by [lint-workflows.yaml] +- [checkov] + - [checkov configuration] + +## .golangci.yaml + +- [.golangci.yaml] +- Used by [golangci-lint.yaml] +- [golangci-lint] + - [golangci-lint configuration] + +## .jscpd.json + +- [.jscpd.json] +- Used by [lint-workflows.yaml] +- [jscpd] + - [jscpd configuration] + - Example: + + ```json + { + "ignore": [ + "**/*.go,**/go-test*.yaml" + ], + "threshold": 10 + } + ``` + +## .yaml-lint.yml + +- [.yaml-lint.yml] +- Used by [lint-workflows.yaml] +- [yaml-lint] + - [yaml-lint configuration] + +[.checkov.yaml]: .checkov.yaml +[.golangci.yaml]: .golangci.yaml +[.jscpd.json]: .jscpd.json +[.yaml-lint.yml]: .yaml-lint.yml +[checkov configuration]: https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html +[checkov]: https://www.checkov.io/ +[golangci-lint configuration]: https://golangci-lint.run/usage/configuration/ +[golangci-lint.yaml]: ../workflows/README.md#golangci-lintyaml +[golangci-lint]: https://golangci-lint.run/ +[jscpd configuration]: https://github.com/kucherenko/jscpd/tree/master/apps/jscpd#options +[jscpd]: https://github.com/kucherenko/jscpd +[lint-workflows.yaml]: ../workflows/README.md#lint-workflowsyaml +[yaml-lint configuration]: https://yamllint.readthedocs.io/en/stable/configuration.html +[yaml-lint]: https://github.com/adrienverge/yamllint diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..c690e31 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,205 @@ +# Workflows + +## add-labels-standardized.yaml + +When issues are opened, +this action adds appropriate labels to the issue. +(e.g. "triage", "customer-submission") + +- [Add Labels Standardized GitHub action] + - Uses: [senzing-factory/build-resources/.../add-labels-to-issue.yaml] + +## add-to-project-garage-dependabot.yaml + +When a Dependabot Pull Request (PR) is made against `main` branch, +this action adds the PR to the "Garage" project board as "In Progress". + +- [Add to Project Garage Dependabot GitHub action] + - Uses: [senzing-factory/build-resources/.../add-to-project-dependabot.yaml] + +## add-to-project-garage.yaml + +When an issue is created, +this action adds the issue to the "Garage" board as "Backlog". + +- [Add to Project Garage GitHub action] + - Uses: [senzing-factory/build-resources/.../add-to-project.yaml] + +## dependabot-approve-and-merge.yaml + +When a Dependabot Pull Request (PR) is made against the `main` branch, +this action determines if it should be automatically approved and merged into the `main` branch. +Once this action occurs [move-pr-to-done-dependabot.yaml] moves the PR on the "Garage" project board to "Done". + +- [Dependabot Approve and Merge GitHub action] + - Uses: [senzing-factory/build-resources/.../dependabot-approve-and-merge.yaml] + +## docker-build-container.yaml + +When a Pull Request is made against the `main` branch, +this action verifies that the `Dockerfile` can be successfully built. + +*Note:* The Docker image is **not** pushed to [DockerHub]. + +- [Docker Build Container GitHub action] + - Uses: [senzing-factory/github-action-docker-buildx-build] + +## docker-push-containers-to-dockerhub.yaml + +After a [Semantic Version] release is created, +this action builds Docker images on multiple architectures and pushes the Docker images to [DockerHub]. + +- [Docker Push Containers to DockerHub GitHub action] + - Uses: [senzing-factory/github-action-docker-buildx-build] + +## golangci-lint.yaml + +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs [golangci-lint] to run multiple linters against the code. + +- [Golangci Lint GitHub action] + - Configuration: + - [.golangci.yaml] + - Uses: + - [actions/checkout] + - [senzing-factory/github-action-install-senzing-api] + - [actions/setup-go] + - [golangci/golangci-lint-action] + +## go-proxy-pull.yaml + +After a [Semantic Version] release is created, +this action expedites the Go publishing process. + +- [Go Proxy Pull GitHub action] + - Uses: [andrewslotin/go-proxy-pull-action] + +## go-test-darwin.yaml + +When a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on macOS. + +- [Go Test Darwin GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] + +## go-test-linux.yaml + +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on Linux. + +- [Go Test Linux GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] + +## go-test-windows.yaml + +When a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on Windows. + +- [Go Test Windows GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] + +## lint-workflows.yaml + +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs [super-linter] to run multiple linters against the code. + +- [Lint Workflows GitHub action] + - Configuration: + - [.checkov.yaml] + - [.jscpd.json] + - [.yaml-lint.yml] + - Uses: [senzing-factory/build-resources/.../lint-workflows.yaml] + +## make-go-github-file.yaml + +After a [Semantic Version] release is created, +this action creates a Pull Request for an updated [github.go] file +for the **next** Semantic Version release by increasing the Semantic Version's Patch value. + +- [Make Go GitHub File GitHub action] + - Uses: [senzing-factory/build-resources/.../make-go-github-file.yaml] + +## make-go-tag.yaml + +After a [Semantic Version] release is created, +this action creates a tag in the form `vM.m.P` using the SHA of the `M.m.P` release. +The `v` prefix is standard usage in [Go]. + +- [Make Go Tag GitHub action] + - Uses: + - [actions/checkout] + - [senzing-factory/github-action-make-go-tag] + +## move-pr-to-done-dependabot.yaml + +When a Pull Request is merged into the `main` branch, +this action moves the PR on the "Garage" project board to "Done". + +- [Move PR to Done Dependabot GitHub action] + - Uses: [senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml] + +[.checkov.yaml]: ../linters/README.md#checkovyaml +[.golangci.yaml]: ../linters/README.md#golangciyaml +[.jscpd.json]: ../linters/README.md#jscpdjson +[.yaml-lint.yml]: ../linters/README.md#yaml-lintyml +[actions/checkout]: https://github.com/actions/checkout +[actions/setup-go]: https://github.com/actions/setup-go +[actions/upload-artifact]: https://github.com/actions/upload-artifact +[Add Labels Standardized GitHub action]: add-labels-standardized.yaml +[Add to Project Garage Dependabot GitHub action]: add-to-project-garage-dependabot.yaml +[Add to Project Garage GitHub action]: add-to-project-garage.yaml +[andrewslotin/go-proxy-pull-action]: https://github.com/andrewslotin/go-proxy-pull-action +[Dependabot Approve and Merge GitHub action]: dependabot-approve-and-merge.yaml +[Docker Build Container GitHub action]: docker-build-container.yaml +[Docker Push Containers to DockerHub GitHub action]: docker-push-containers-to-dockerhub.yaml +[DockerHub]: https://hub.docker.com/ +[github.go]: ../../cmd/github.go +[Go Proxy Pull GitHub action]: go-proxy-pull.yaml +[Go Test Darwin GitHub action]: go-test-darwin.yaml +[Go Test Linux GitHub action]: go-test-linux.yaml +[Go Test Windows GitHub action]: go-test-windows.yaml +[Go]: https://go.dev/ +[Golangci Lint GitHub action]: golangci-lint.yaml +[golangci-lint]: https://github.com/golangci/golangci-lint +[golangci/golangci-lint-action]: https://github.com/golangci/golangci-lint-action +[gotesttools/gotestfmt-action]: https://github.com/gotesttools/gotestfmt-action +[Lint Workflows GitHub action]: lint-workflows.yaml +[Make Go GitHub File GitHub action]: make-go-github-file.yaml +[Make Go Tag GitHub action]: make-go-tag.yaml +[Move PR to Done Dependabot GitHub action]: move-pr-to-done-dependabot.yaml +[move-pr-to-done-dependabot.yaml]: move-pr-to-done-dependabotyaml +[Semantic Version]: https://semver.org/ +[senzing-factory/build-resources/.../add-labels-to-issue.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-labels-to-issue.yaml +[senzing-factory/build-resources/.../add-to-project-dependabot.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project-dependabot.yaml +[senzing-factory/build-resources/.../add-to-project.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project.yaml +[senzing-factory/build-resources/.../dependabot-approve-and-merge.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/dependabot-approve-and-merge.yaml +[senzing-factory/build-resources/.../go-coverage.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/go-coverage.yaml +[senzing-factory/build-resources/.../lint-workflows.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/lint-workflows.yaml +[senzing-factory/build-resources/.../make-go-github-file.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/make-go-github-file.yaml +[senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/move-pr-to-done-dependabot.yaml +[senzing-factory/github-action-docker-buildx-build]: https://github.com/senzing-factory/github-action-docker-buildx-build +[senzing-factory/github-action-install-senzing-api]: https://github.com/senzing-factory/github-action-install-senzing-api +[senzing-factory/github-action-make-go-tag]: https://github.com/senzing-factory/github-action-make-go-tag +[super-linter]: https://github.com/super-linter/super-linter +[testcoverage.yaml]: ../coverage/README.md#testcoverageyaml diff --git a/.github/workflows/add-labels-standardized.yaml b/.github/workflows/add-labels-standardized.yaml index 01aa8a1..59ca6b2 100644 --- a/.github/workflows/add-labels-standardized.yaml +++ b/.github/workflows/add-labels-standardized.yaml @@ -1,4 +1,4 @@ -name: add labels standardized +name: Add labels standardized on: issues: diff --git a/.github/workflows/add-to-project-garage-dependabot.yaml b/.github/workflows/add-to-project-garage-dependabot.yaml index 19cc672..125bc58 100644 --- a/.github/workflows/add-to-project-garage-dependabot.yaml +++ b/.github/workflows/add-to-project-garage-dependabot.yaml @@ -1,4 +1,4 @@ -name: add to project garage dependabot +name: Add to project garage dependabot on: pull_request: diff --git a/.github/workflows/add-to-project-garage.yaml b/.github/workflows/add-to-project-garage.yaml index 53c0744..8397880 100644 --- a/.github/workflows/add-to-project-garage.yaml +++ b/.github/workflows/add-to-project-garage.yaml @@ -1,4 +1,4 @@ -name: add to project garage +name: Add to project garage on: issues: diff --git a/.github/workflows/dependabot-approve-and-merge.yaml b/.github/workflows/dependabot-approve-and-merge.yaml index 0aad27e..326edea 100644 --- a/.github/workflows/dependabot-approve-and-merge.yaml +++ b/.github/workflows/dependabot-approve-and-merge.yaml @@ -1,4 +1,4 @@ -name: dependabot approve and merge +name: Dependabot approve and merge on: pull_request: diff --git a/.github/workflows/go-proxy-pull.yaml b/.github/workflows/go-proxy-pull.yaml index 639c8d6..607520d 100644 --- a/.github/workflows/go-proxy-pull.yaml +++ b/.github/workflows/go-proxy-pull.yaml @@ -1,4 +1,4 @@ -name: go proxy pull +name: Go proxy pull on: push: @@ -13,7 +13,7 @@ jobs: runs-on: ubuntu-latest steps: - - name: pull new module version + - name: Pull new module version uses: andrewslotin/go-proxy-pull-action@v1.2.0 with: - import_path: github.com/senzing-garage/explain + import_path: github.com/${{ github.repository }} diff --git a/.github/workflows/go-test-darwin.yaml b/.github/workflows/go-test-darwin.yaml index fc156ba..5468eea 100644 --- a/.github/workflows/go-test-darwin.yaml +++ b/.github/workflows/go-test-darwin.yaml @@ -1,4 +1,4 @@ -name: go test darwin +name: Go test darwin on: [pull_request, workflow_dispatch] @@ -7,7 +7,7 @@ permissions: jobs: go-test-darwin: - name: "go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" + name: "Go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" runs-on: ${{ matrix.os }} strategy: matrix: @@ -15,18 +15,23 @@ jobs: os: [macos-13] steps: - - name: checkout repository + - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - - name: setup go + - name: Setup go uses: actions/setup-go@v5 with: go-version: ${{ matrix.go }} - - name: run go test - run: go test -v -p 1 -coverprofile=./cover.out -covermode=atomic -coverpkg=./... ./... + - name: Set up gotestfmt + uses: gotesttools/gotestfmt-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Run go test + run: go test -json -v -p 1 -coverprofile=./cover.out -covermode=atomic -coverpkg=./... ./... 2>&1 | tee /tmp/gotest.log | gotestfmt - name: Store coverage file uses: actions/upload-artifact@v4 @@ -34,7 +39,17 @@ jobs: name: cover.out path: ./cover.out + - name: Upload test log + uses: actions/upload-artifact@v4 + if: always() + with: + name: test-log + path: /tmp/gotest.log + if-no-files-found: error + coverage: - name: coverage + name: Coverage needs: go-test-darwin uses: senzing-factory/build-resources/.github/workflows/go-coverage.yaml@v2 + with: + coverage-config: ./.github/coverage/testcoverage.yaml diff --git a/.github/workflows/go-test-linux.yaml b/.github/workflows/go-test-linux.yaml index a016aa1..8328bbc 100644 --- a/.github/workflows/go-test-linux.yaml +++ b/.github/workflows/go-test-linux.yaml @@ -1,4 +1,4 @@ -name: go test linux +name: Go test linux on: [push] @@ -7,7 +7,7 @@ permissions: jobs: go-test-linux: - name: "go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" + name: "Go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" runs-on: ${{ matrix.os }} strategy: matrix: @@ -15,18 +15,23 @@ jobs: os: [ubuntu-latest] steps: - - name: checkout repository + - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - - name: setup go + - name: Setup go uses: actions/setup-go@v5 with: go-version: ${{ matrix.go }} - - name: run go test - run: go test -v -p 1 -coverprofile=./cover.out -covermode=atomic -coverpkg=./... ./... + - name: Set up gotestfmt + uses: gotesttools/gotestfmt-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Run go test + run: go test -json -v -p 1 -coverprofile=./cover.out -covermode=atomic -coverpkg=./... ./... 2>&1 | tee /tmp/gotest.log | gotestfmt - name: Store coverage file uses: actions/upload-artifact@v4 @@ -34,7 +39,17 @@ jobs: name: cover.out path: ./cover.out + - name: Upload test log + uses: actions/upload-artifact@v4 + if: always() + with: + name: test-log + path: /tmp/gotest.log + if-no-files-found: error + coverage: - name: coverage + name: Coverage needs: go-test-linux uses: senzing-factory/build-resources/.github/workflows/go-coverage.yaml@v2 + with: + coverage-config: ./.github/coverage/testcoverage.yaml diff --git a/.github/workflows/go-test-windows.yaml b/.github/workflows/go-test-windows.yaml index 0b0a01d..5022428 100644 --- a/.github/workflows/go-test-windows.yaml +++ b/.github/workflows/go-test-windows.yaml @@ -1,4 +1,4 @@ -name: go test windows +name: Go test windows on: [pull_request, workflow_dispatch] @@ -7,7 +7,7 @@ permissions: jobs: go-test-windows: - name: "go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" + name: "Go test with OS: ${{ matrix.os }}; Go: ${{ matrix.go }}" runs-on: ${{ matrix.os }} strategy: matrix: @@ -15,19 +15,24 @@ jobs: os: [windows-latest] steps: - - name: checkout repository + - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 0 - - name: setup go + - name: Setup go uses: actions/setup-go@v5 with: go-version: ${{ matrix.go }} - - name: run go test + - name: Set up gotestfmt + uses: gotesttools/gotestfmt-action@v2 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Run go test run: | - go test -v -p 1 -coverprofile=cover -covermode=atomic -coverpkg=./... ./... + go test -json -v -p 1 -coverprofile=cover -covermode=atomic -coverpkg=./... ./... 2>&1 | tee "C:\Temp\gotest.log" | gotestfmt cp cover cover.out - name: Store coverage file @@ -36,7 +41,17 @@ jobs: name: cover.out path: cover.out + - name: Upload test log + uses: actions/upload-artifact@v4 + if: always() + with: + name: test-log + path: "C:\\Temp\\gotest.log" + if-no-files-found: error + coverage: - name: coverage + name: Coverage needs: go-test-windows uses: senzing-factory/build-resources/.github/workflows/go-coverage.yaml@v2 + with: + coverage-config: ./.github/coverage/testcoverage.yaml diff --git a/.github/workflows/lint-workflows.yaml b/.github/workflows/lint-workflows.yaml index c471330..e19c3f8 100644 --- a/.github/workflows/lint-workflows.yaml +++ b/.github/workflows/lint-workflows.yaml @@ -1,4 +1,4 @@ -name: lint workflows +name: Lint workflows on: push: diff --git a/.github/workflows/make-go-github-file.yaml b/.github/workflows/make-go-github-file.yaml index 6aadd14..339959e 100644 --- a/.github/workflows/make-go-github-file.yaml +++ b/.github/workflows/make-go-github-file.yaml @@ -1,4 +1,4 @@ -name: make go github file +name: Make go github file on: push: diff --git a/.github/workflows/make-go-tag.yaml b/.github/workflows/make-go-tag.yaml index 5a25899..a4e0646 100644 --- a/.github/workflows/make-go-tag.yaml +++ b/.github/workflows/make-go-tag.yaml @@ -1,4 +1,4 @@ -name: make go tag +name: Make go tag on: push: @@ -10,12 +10,12 @@ permissions: jobs: make-go-tag: - name: make a vM.m.P tag + name: Make a vM.m.P tag runs-on: ubuntu-latest steps: - - name: checkout repository + - name: Checkout repository uses: actions/checkout@v4 - - name: make go version tag + - name: Make go version tag uses: senzing-factory/github-action-make-go-tag@v1 diff --git a/.github/workflows/move-pr-to-done-dependabot.yaml b/.github/workflows/move-pr-to-done-dependabot.yaml index b59571b..c5e0e87 100644 --- a/.github/workflows/move-pr-to-done-dependabot.yaml +++ b/.github/workflows/move-pr-to-done-dependabot.yaml @@ -1,4 +1,4 @@ -name: move pr to done dependabot +name: Move pr to done dependabot on: pull_request: diff --git a/.gitignore b/.gitignore index a7bf099..950a688 100644 --- a/.gitignore +++ b/.gitignore @@ -30,4 +30,8 @@ go.work # Makefile target/ + +.coverage +cover.out coverage.html +coverage.out diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18b3ecd..0a7eef9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,15 +2,15 @@ Welcome to the project! -We encourage contribution in a manner consistent with the [Code of Conduct](CODE_OF_CONDUCT.md). +We encourage contribution in a manner consistent with the [Code of Conduct]. The following will guide you through the process. There are a number of ways you can contribute: -1. [Asking questions](#questions) -1. [Requesting features](#feature-requests) -1. [Reporting bugs](#bug-reporting) -1. [Contributing code or documentation](#contributing-code-or-documentation) +1. [Asking questions] +1. [Requesting features] +1. [Reporting bugs] +1. [Contributing code or documentation] ## License Agreements @@ -23,19 +23,19 @@ A license agreement is not needed for submitting feature request, bug reporting, ### Individual Contributor License Agreement In order to contribute to this repository, an -[Individual Contributor License Agreement (ICLA)](.github/senzing-individual-contributor-license-agreement.pdf) +[Individual Contributor License Agreement (ICLA)] must be completed, submitted and accepted. ### Corporate Contributor License Agreement If the contribution to this repository is on behalf of a company, a -[Corporate Contributor License Agreement (CCLA)](.github/senzing-corporate-contributor-license-agreement.pdf) +[Corporate Contributor License Agreement (CCLA)] must also be completed, submitted and accepted. ### Project License Agreement The license agreement for this repository is stated in the -[LICENSE](LICENSE) file. +[LICENSE] file. ## Questions @@ -50,7 +50,7 @@ TODO: Instead, use ??? All feature requests are "GitHub issues". To request a feature, create a -[GitHub issue](https://help.github.com/articles/creating-an-issue/) +[GitHub issue] in this repository. When creating an issue, there will be a choice to create a "Bug report" or a "Feature request". @@ -59,11 +59,8 @@ Choose "Feature request". ## Bug Reporting All bug reports are "GitHub issues". -Before reporting on a bug, check to see if it has -[already been reported](https://github.com/search?q=+is%3Aissue+user%3Asenzing). -To report a bug, create a -[GitHub issue](https://help.github.com/articles/creating-an-issue/) -in this repository. +Before reporting on a bug, check to see if it has [already been reported]. +To report a bug, create a [GitHub issue] in this repository. When creating an issue, there will be a choice to create a "Bug report" or a "Feature request". Choose "Bug report". @@ -71,8 +68,8 @@ Choose "Bug report". ## Contributing code or documentation To contribute code or documentation to the repository, you must have -[License Agreements](#license-agreements) in place. -This needs to be complete before a [Pull Request](#pull-requests) can be accepted. +[License Agreements] in place. +This needs to be complete before a [Pull Request] can be accepted. ### Setting up a development environment @@ -116,9 +113,22 @@ TODO: ### Pull Requests Code in the main branch is modified via GitHub pull request. -Follow GitHub's -[Creating a pull request from a branch](https://help.github.com/articles/creating-a-pull-request/) -or -[Creating a pull request from a fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) instructions. +Follow GitHub's [Creating a pull request from a branch] or +[Creating a pull request from a fork] instructions. Accepting pull requests will be at the discretion of Senzing, Inc. and the repository owner(s). + +[already been reported]: https://github.com/search?q=+is%3Aissue+user%3Asenzing +[Asking questions]: #questions +[Code of Conduct]: CODE_OF_CONDUCT.md +[Contributing code or documentation]: #contributing-code-or-documentation +[Corporate Contributor License Agreement (CCLA)]: .github/senzing-corporate-contributor-license-agreement.pdf +[Creating a pull request from a branch]: https://help.github.com/articles/creating-a-pull-request/ +[Creating a pull request from a fork]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/ +[GitHub issue]: https://help.github.com/articles/creating-an-issue/ +[Individual Contributor License Agreement (ICLA)]: .github/senzing-individual-contributor-license-agreement.pdf +[LICENSE]: LICENSE +[License Agreements]: #license-agreements +[Pull Request]: #pull-requests +[Reporting bugs]: #bug-reporting +[Requesting features]: #feature-requests diff --git a/Makefile b/Makefile index 2e3ed1e..ad62ae4 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# Makefile for explain. +# Makefile for Go project # Detect the operating system and architecture. @@ -15,14 +15,18 @@ PROGRAM_NAME := $(shell basename `git rev-parse --show-toplevel`) MAKEFILE_PATH := $(abspath $(firstword $(MAKEFILE_LIST))) MAKEFILE_DIRECTORY := $(shell dirname $(MAKEFILE_PATH)) TARGET_DIRECTORY := $(MAKEFILE_DIRECTORY)/target +DIST_DIRECTORY := $(MAKEFILE_DIRECTORY)/dist +BUILD_TAG := $(shell git describe --always --tags --abbrev=0 | sed 's/v//') +BUILD_ITERATION := $(shell git log $(BUILD_TAG)..HEAD --oneline | wc -l | sed 's/^ *//') +BUILD_VERSION := $(shell git describe --always --tags --abbrev=0 --dirty | sed 's/v//') DOCKER_CONTAINER_NAME := $(PROGRAM_NAME) DOCKER_IMAGE_NAME := senzing/$(PROGRAM_NAME) DOCKER_BUILD_IMAGE_NAME := $(DOCKER_IMAGE_NAME)-build -BUILD_VERSION := $(shell git describe --always --tags --abbrev=0 --dirty | sed 's/v//') -BUILD_TAG := $(shell git describe --always --tags --abbrev=0 | sed 's/v//') -BUILD_ITERATION := $(shell git log $(BUILD_TAG)..HEAD --oneline | wc -l | sed 's/^ *//') GIT_REMOTE_URL := $(shell git config --get remote.origin.url) +GIT_REPOSITORY_NAME := $(shell basename `git rev-parse --show-toplevel`) +GIT_VERSION := $(shell git describe --always --tags --long --dirty | sed -e 's/\-0//' -e 's/\-g.......//') GO_PACKAGE_NAME := $(shell echo $(GIT_REMOTE_URL) | sed -e 's|^git@github.com:|github.com/|' -e 's|\.git$$||' -e 's|Senzing|senzing|') +PATH := $(MAKEFILE_DIRECTORY)/bin:$(PATH) # Recursive assignment ('=') @@ -32,10 +36,10 @@ GO_ARCH = $(word 2, $(GO_OSARCH)) # Conditional assignment. ('?=') # Can be overridden with "export" -# Example: "export LD_LIBRARY_PATH=/path/to/my/senzing-garage/g2/lib" +# Example: "export LD_LIBRARY_PATH=/path/to/my/senzing/er/lib" -LD_LIBRARY_PATH ?= /opt/senzing/g2/lib GOBIN ?= $(shell go env GOPATH)/bin +LD_LIBRARY_PATH ?= /opt/senzing/er/lib # Export environment variables. @@ -63,9 +67,11 @@ hello-world: hello-world-osarch-specific # Dependency management # ----------------------------------------------------------------------------- -.PHONY: make-dependencies -make-dependencies: +.PHONY: dependencies-for-development +dependencies-for-development: + @go install github.com/gotesttools/gotestfmt/v2/cmd/gotestfmt@latest @go install github.com/vladopajic/go-test-coverage/v2@latest + @go install golang.org/x/tools/cmd/godoc@latest @curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell go env GOPATH)/bin v1.58.1 @@ -75,20 +81,40 @@ dependencies: @go get -t -u ./... @go mod tidy +# ----------------------------------------------------------------------------- +# Setup +# ----------------------------------------------------------------------------- + +.PHONY: setup +setup: setup-osarch-specific + +# ----------------------------------------------------------------------------- +# Lint +# ----------------------------------------------------------------------------- + +.PHONY: lint +lint: golangci-lint + # ----------------------------------------------------------------------------- # Build -# - docker-build: https://docs.docker.com/engine/reference/commandline/build/ # ----------------------------------------------------------------------------- PLATFORMS := darwin/amd64 darwin/arm64 linux/amd64 linux/arm64 windows/amd64 windows/arm64 $(PLATFORMS): - @echo Building $(TARGET_DIRECTORY)/$(GO_OS)-$(GO_ARCH)/$(PROGRAM_NAME) + $(info Building $(TARGET_DIRECTORY)/$(GO_OS)-$(GO_ARCH)/$(PROGRAM_NAME)) @GOOS=$(GO_OS) GOARCH=$(GO_ARCH) go build -o $(TARGET_DIRECTORY)/$(GO_OS)-$(GO_ARCH)/$(PROGRAM_NAME) .PHONY: build build: build-osarch-specific +# ----------------------------------------------------------------------------- +# Run +# ----------------------------------------------------------------------------- + +.PHONY: run +run: run-osarch-specific + # ----------------------------------------------------------------------------- # Test # ----------------------------------------------------------------------------- @@ -107,27 +133,23 @@ coverage: coverage-osarch-specific .PHONY: check-coverage check-coverage: export SENZING_LOG_LEVEL=TRACE check-coverage: - go test ./... -coverprofile=./cover.out -covermode=atomic -coverpkg=./... - ${GOBIN}/go-test-coverage --config=./.testcoverage.yml + @go test ./... -coverprofile=./cover.out -covermode=atomic -coverpkg=./... + @${GOBIN}/go-test-coverage --config=.github/coverage/testcoverage.yaml # ----------------------------------------------------------------------------- -# Lint +# Documentation # ----------------------------------------------------------------------------- -.PHONY: run-golangci-lint -run-golangci-lint: - ${GOBIN}/golangci-lint run --config=.github/linters/.golangci.yml +.PHONY: documentation +documentation: documentation-osarch-specific # ----------------------------------------------------------------------------- -# Run +# Package # ----------------------------------------------------------------------------- -.PHONY: run -run: run-osarch-specific +.PHONY: package +package: clean package-osarch-specific -# ----------------------------------------------------------------------------- -# Package -# ----------------------------------------------------------------------------- .PHONY: docker-build-package docker-build-package: @@ -141,12 +163,8 @@ docker-build-package: --tag $(DOCKER_BUILD_IMAGE_NAME) \ . - -.PHONY: package -package: package-osarch-specific - # ----------------------------------------------------------------------------- -# Utility targets +# Clean # ----------------------------------------------------------------------------- .PHONY: clean @@ -154,11 +172,14 @@ clean: clean-osarch-specific @go clean -cache @go clean -testcache +# ----------------------------------------------------------------------------- +# Utility targets +# ----------------------------------------------------------------------------- .PHONY: help help: - @echo "Build $(PROGRAM_NAME) version $(BUILD_VERSION)-$(BUILD_ITERATION)". - @echo "Makefile targets:" + $(info Build $(PROGRAM_NAME) version $(BUILD_VERSION)-$(BUILD_ITERATION)) + $(info Makefile targets:) @$(MAKE) -pRrq -f $(firstword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | egrep -v -e '^[^[:alnum:]]' -e '^$@$$' | xargs @@ -166,14 +187,18 @@ help: print-make-variables: @$(foreach V,$(sort $(.VARIABLES)), \ $(if $(filter-out environment% default automatic, \ - $(origin $V)),$(warning $V=$($V) ($(value $V))))) - - -.PHONY: setup -setup: setup-osarch-specific + $(origin $V)),$(info $V=$($V) ($(value $V))))) .PHONY: update-pkg-cache update-pkg-cache: @GOPROXY=https://proxy.golang.org GO111MODULE=on \ go get $(GO_PACKAGE_NAME)@$(BUILD_TAG) + +# ----------------------------------------------------------------------------- +# Specific programs +# ----------------------------------------------------------------------------- + +.PHONY: golangci-lint +golangci-lint: + @${GOBIN}/golangci-lint run --config=.github/linters/.golangci.yaml diff --git a/README.md b/README.md index 83b60b0..685b836 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,9 @@ # explain -If you are beginning your journey with -[Senzing](https://senzing.com/), -please start with -[Senzing Quick Start guides](https://docs.senzing.com/quickstart/). - -You are in the -[Senzing Garage](https://github.com/senzing-garage) -where projects are "tinkered" on. +If you are beginning your journey with [Senzing], +please start with [Senzing Quick Start guides]. + +You are in the [Senzing Garage] where projects are "tinkered" on. Although this GitHub repository may help you understand an approach to using Senzing, it's not considered to be "production ready" and is not considered to be part of the Senzing product. Heck, it may not even be appropriate for your application of Senzing! @@ -25,14 +21,14 @@ the recommendation is not to use it yet. suite of tools. It is used to explain aspects of `senzing-tools`. -[![Go Reference](https://pkg.go.dev/badge/github.com/senzing-garage/explain.svg)](https://pkg.go.dev/github.com/senzing-garage/explain) -[![Go Report Card](https://goreportcard.com/badge/github.com/senzing-garage/explain)](https://goreportcard.com/report/github.com/senzing-garage/explain) -[![License](https://img.shields.io/badge/License-Apache2-brightgreen.svg)](https://github.com/senzing-garage/explain/blob/main/LICENSE) +[![Go Reference Badge]][Package reference] +[![Go Report Card Badge]][Go Report Card] +[![License Badge]][License] +[![go-test-linux.yaml Badge]][go-test-linux.yaml] +[![go-test-darwin.yaml Badge]][go-test-darwin.yaml] +[![go-test-windows.yaml Badge]][go-test-windows.yaml] -[![gosec.yaml](https://github.com/senzing-garage/explain/actions/workflows/gosec.yaml/badge.svg)](https://github.com/senzing-garage/explain/actions/workflows/gosec.yaml) -[![go-test-linux.yaml](https://github.com/senzing-garage/explain/actions/workflows/go-test-linux.yaml/badge.svg)](https://github.com/senzing-garage/explain/actions/workflows/go-test-linux.yaml) -[![go-test-darwin.yaml](https://github.com/senzing-garage/explain/actions/workflows/go-test-darwin.yaml/badge.svg)](https://github.com/senzing-garage/explain/actions/workflows/go-test-darwin.yaml) -[![go-test-windows.yaml](https://github.com/senzing-garage/explain/actions/workflows/go-test-windows.yaml/badge.svg)](https://github.com/senzing-garage/explain/actions/workflows/go-test-windows.yaml) +[![golangci-lint.yaml Badge]][golangci-lint.yaml] ## Overview @@ -55,7 +51,7 @@ It is used to explain aspects of `senzing-tools`. ## Use ```console -export LD_LIBRARY_PATH=/opt/senzing/g2/lib/ +export LD_LIBRARY_PATH=/opt/senzing/er/lib/ senzing-tools explain [flags] ``` @@ -64,7 +60,7 @@ senzing-tools explain [flags] 1. Runtime documentation: ```console - export LD_LIBRARY_PATH=/opt/senzing/g2/lib/ + export LD_LIBRARY_PATH=/opt/senzing/er/lib/ senzing-tools explain --help ``` @@ -76,7 +72,7 @@ senzing-tools explain [flags] Example: ```console - export LD_LIBRARY_PATH=/opt/senzing/g2/lib/ + export LD_LIBRARY_PATH=/opt/senzing/er/lib/ senzing-tools explain ``` @@ -89,7 +85,7 @@ senzing-tools explain [flags] ```console export SENZING_TOOLS_MESSAGE_ID=senzing-60010032 - export LD_LIBRARY_PATH=/opt/senzing/g2/lib/ + export LD_LIBRARY_PATH=/opt/senzing/er/lib/ senzing-tools explain ``` @@ -104,7 +100,33 @@ senzing-tools explain [flags] ## References -- [Command reference](https://hub.senzing.com/senzing-tools/senzing-tools_explain.html) -- [Development](docs/development.md) -- [Errors](docs/errors.md) -- [Examples](docs/examples.md) +1. [API documentation] +1. [Development] +1. [Errors] +1. [Examples] +1. [Package reference] +1. Related artifacts: + 1. [DockerHub] + +[API documentation]: https://pkg.go.dev/github.com/senzing-garage/template-go +[Development]: docs/development.md +[DockerHub]: https://hub.docker.com/r/senzing/template-go +[Errors]: docs/errors.md +[Examples]: docs/examples.md +[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg +[Go Report Card Badge]: https://goreportcard.com/badge/github.com/senzing-garage/template-go +[Go Report Card]: https://goreportcard.com/report/github.com/senzing-garage/template-go +[go-test-darwin.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml/badge.svg +[go-test-darwin.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml +[go-test-linux.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml/badge.svg +[go-test-linux.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml +[go-test-windows.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml/badge.svg +[go-test-windows.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml +[golangci-lint.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml/badge.svg +[golangci-lint.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml +[License Badge]: https://img.shields.io/badge/License-Apache2-brightgreen.svg +[License]: https://github.com/senzing-garage/template-go/blob/main/LICENSE +[Package reference]: https://pkg.go.dev/github.com/senzing-garage/template-go +[Senzing Garage]: https://github.com/senzing-garage +[Senzing Quick Start guides]: https://docs.senzing.com/quickstart/ +[Senzing]: https://senzing.com/ diff --git a/cmd/cmd_test.go b/cmd/cmd_test.go index a53bc5c..10fb3ea 100644 --- a/cmd/cmd_test.go +++ b/cmd/cmd_test.go @@ -12,9 +12,6 @@ import ( // Test public functions // ---------------------------------------------------------------------------- -/* - * The unit tests in this file simulate command line invocation. - */ func Test_Execute(test *testing.T) { _ = test os.Args = []string{"command-name", "--message-id", "SZSDK60010000", "--tty-only"} @@ -33,6 +30,12 @@ func Test_Execute_docs(test *testing.T) { Execute() } +func Test_Execute_help(test *testing.T) { + _ = test + os.Args = []string{"command-name", "--help"} + Execute() +} + func Test_PreRun(test *testing.T) { _ = test args := []string{"command-name", "--message-id", "SZSDK60010000", "--tty-only"} @@ -40,10 +43,35 @@ func Test_PreRun(test *testing.T) { } func Test_RunE(test *testing.T) { + test.Setenv("SENZING_TOOLS_AVOID_SERVING", "true") err := RunE(RootCmd, []string{}) require.NoError(test, err) } +func Test_RootCmd(test *testing.T) { + _ = test + err := RootCmd.Execute() + require.NoError(test, err) + err = RootCmd.RunE(RootCmd, []string{}) + require.NoError(test, err) +} + +func Test_completionCmd(test *testing.T) { + _ = test + err := completionCmd.Execute() + require.NoError(test, err) + err = completionCmd.RunE(completionCmd, []string{}) + require.NoError(test, err) +} + +func Test_docsCmd(test *testing.T) { + _ = test + err := docsCmd.Execute() + require.NoError(test, err) + err = docsCmd.RunE(docsCmd, []string{}) + require.NoError(test, err) +} + // ---------------------------------------------------------------------------- // Test private functions // ---------------------------------------------------------------------------- diff --git a/cmd/root.go b/cmd/root.go index fc5b80c..7c7a710 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -33,12 +33,17 @@ var ContextVariablesForMultiPlatform = []option.ContextVariable{ var ContextVariables = append(ContextVariablesForMultiPlatform, ContextVariablesForOsArch...) // ---------------------------------------------------------------------------- -// Private functions +// Command // ---------------------------------------------------------------------------- -// Since init() is always invoked, define command line parameters. -func init() { - cmdhelper.Init(RootCmd, ContextVariables) +// RootCmd represents the command. +var RootCmd = &cobra.Command{ + Use: Use, + Short: Short, + Long: Long, + PreRun: PreRun, + RunE: RunE, + Version: Version(), } // ---------------------------------------------------------------------------- @@ -83,15 +88,10 @@ func Version() string { } // ---------------------------------------------------------------------------- -// Command +// Private functions // ---------------------------------------------------------------------------- -// RootCmd represents the command. -var RootCmd = &cobra.Command{ - Use: Use, - Short: Short, - Long: Long, - PreRun: PreRun, - RunE: RunE, - Version: Version(), +// Since init() is always invoked, define command line parameters. +func init() { + cmdhelper.Init(RootCmd, ContextVariables) } diff --git a/docs/README.md b/docs/README.md index d678a6c..7c52ef3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,8 @@ # explain -Placeholder for [GitHub pages](https://pages.github.com/). +Placeholder for [GitHub pages]. -See [https://hub.senzing.com/explain](https://hub.senzing.com/explain). +See [GitHub page]. + +[GitHub page]: https://garage.senzing.com/explain +[GitHub pages]: https://pages.github.com/ diff --git a/docs/development.md b/docs/development.md index d885ace..2c2ada3 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,63 +1,123 @@ # explain development -## Install Go +The following instructions are useful during development. -1. See Go's [Download and install](https://go.dev/doc/install) +**Note:** This has been tested on Linux and Darwin/macOS. +It has not been tested on Windows. + +## Prerequisites for development + +:thinking: The following tasks need to be complete before proceeding. +These are "one-time tasks" which may already have been completed. + +1. The following software programs need to be installed: + 1. [git] + 1. [make] + 1. [docker] + 1. [go] ## Install Senzing C library Since the Senzing library is a prerequisite, it must be installed first. 1. Verify Senzing C shared objects, configuration, and SDK header files are installed. - 1. `/opt/senzing/g2/lib` - 1. `/opt/senzing/g2/sdk/c` + 1. `/opt/senzing/er/lib` + 1. `/opt/senzing/er/sdk/c` 1. `/etc/opt/senzing` -1. If not installed, see - [How to Install Senzing for Go Development](https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md). +1. If not installed, see [How to Install Senzing for Go Development]. ## Install Git repository 1. Identify git repository. ```console - export GIT_ACCOUNT=senzing + export GIT_ACCOUNT=senzing-garage export GIT_REPOSITORY=explain export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}" ``` -1. Using the environment variables values just set, follow steps in - [clone-repository](https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md) to install the Git repository. +1. Using the environment variables values just set, follow + steps in [clone-repository] to install the Git repository. -## Build +## Dependencies -1. Build the binaries. +1. A one-time command to install dependencies needed for `make` targets. Example: ```console cd ${GIT_REPOSITORY_DIR} - make build + make dependencies-for-development ``` -1. The binaries will be found in ${GIT_REPOSITORY_DIR}/target. +1. Install dependencies needed for [Go] code. Example: ```console - tree ${GIT_REPOSITORY_DIR}/target + cd ${GIT_REPOSITORY_DIR} + make dependencies + + ``` + +## Lint + +1. Run linting. + Example: + + ```console + cd ${GIT_REPOSITORY_DIR} + make lint + + ``` + +## Build + +1. Build the binaries. + Example: + + ```console + cd ${GIT_REPOSITORY_DIR} + make clean build ``` -1. Run the binary. +1. The binaries will be found in the `${GIT_REPOSITORY_DIR}/target` directory. Example: ```console - ${GIT_REPOSITORY_DIR}/target/linux-amd64/explain + tree ${GIT_REPOSITORY_DIR}/target ``` +## Run + +1. Run program. + Examples: + + 1. Linux + + ```console + ${GIT_REPOSITORY_DIR}/target/linux-amd64/explain + + ``` + + 1. macOS + + ```console + ${GIT_REPOSITORY_DIR}/target/darwin-amd64/explain + + ``` + + 1. Windows + + ```console + ${GIT_REPOSITORY_DIR}/target/windows-amd64/explain + + ``` + 1. Clean up. Example: @@ -69,34 +129,60 @@ Since the Senzing library is a prerequisite, it must be installed first. ## Test +1. Run tests. + Example: + + ```console + cd ${GIT_REPOSITORY_DIR} + make clean setup test + + ``` + +## Coverage + +Create a code coverage map. + 1. Run Go tests. Example: ```console cd ${GIT_REPOSITORY_DIR} - make test + make clean setup coverage ``` + A web-browser will show the results of the coverage. + The goal is to have over 80% coverage. + Anything less needs to be reflected in [testcoverage.yaml]. + ## Documentation -1. Start `godoc` documentation server. +1. View documentation. Example: ```console - cd ${GIT_REPOSITORY_DIR} - godoc + cd ${GIT_REPOSITORY_DIR} + make clean documentation ``` -1. Visit [localhost:6060](http://localhost:6060) +1. If a web page doesn't appear, visit [localhost:6060]. 1. Senzing documentation will be in the "Third party" section. - `github.com` > `senzing` > `explain` + `github.com` > `senzing` > `go-cmdhelping` 1. When a versioned release is published with a `v0.0.0` format tag, -the reference can be found by clicking on the following badge at the top of the README.md page: -[![Go Reference](https://pkg.go.dev/badge/github.com/senzing-garage/explain.svg)](https://pkg.go.dev/github.com/senzing-garage/explain) +the reference can be found by clicking on the following badge at the top of the README.md page. +Example: + + [![Go Reference Badge]][Go Reference] +1. To stop the `godoc` server, run + + ```console + cd ${GIT_REPOSITORY_DIR} + make clean + + ``` ## Package ### Package RPM and DEB files @@ -152,3 +238,16 @@ the reference can be found by clicking on the following badge at the top of the sudo apt-get remove explain ``` + +## References + +[clone-repository]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md +[docker]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/docker.md +[git]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/git.md +[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg +[Go Reference]: https://pkg.go.dev/github.com/senzing-garage/template-go +[go]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/go.md +[How to Install Senzing for Go Development]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md +[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/template-go/ +[make]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/make.md +[testcoverage.yaml]: ../.github/coverage/testcoverage.yaml diff --git a/docs/examples.md b/docs/examples.md index d663a7a..1daa793 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,6 +1 @@ # explain examples - -## Examples of CLI - -The following examples require initialization described in -[Demonstrate using Command Line Interface](../README.md#demonstrate-using-command-line-interface). diff --git a/go.mod b/go.mod index f3fa39d..51aed5d 100644 --- a/go.mod +++ b/go.mod @@ -4,7 +4,7 @@ go 1.21 require ( github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c - github.com/senzing-garage/go-cmdhelping v0.2.3 + github.com/senzing-garage/go-cmdhelping v0.3.0 github.com/spf13/cobra v1.8.1 github.com/spf13/viper v1.19.0 github.com/stretchr/testify v1.9.0 @@ -25,13 +25,13 @@ require ( github.com/sagikazarmark/slog-shim v0.1.0 // indirect github.com/sourcegraph/conc v0.3.0 // indirect github.com/spf13/afero v1.11.0 // indirect - github.com/spf13/cast v1.6.0 // indirect + github.com/spf13/cast v1.7.0 // indirect github.com/spf13/pflag v1.0.5 // indirect github.com/subosito/gotenv v1.6.0 // indirect go.uber.org/multierr v1.11.0 // indirect - golang.org/x/exp v0.0.0-20240707233637-46b078467d37 // indirect - golang.org/x/sys v0.22.0 // indirect - golang.org/x/text v0.16.0 // indirect + golang.org/x/exp v0.0.0-20240808152545-0cdaa3abc0fa // indirect + golang.org/x/sys v0.24.0 // indirect + golang.org/x/text v0.17.0 // indirect gopkg.in/ini.v1 v1.67.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/go.sum b/go.sum index d403a66..cfe386b 100644 --- a/go.sum +++ b/go.sum @@ -37,14 +37,14 @@ github.com/sagikazarmark/locafero v0.6.0 h1:ON7AQg37yzcRPU69mt7gwhFEBwxI6P9T4Qu3 github.com/sagikazarmark/locafero v0.6.0/go.mod h1:77OmuIc6VTraTXKXIs/uvUxKGUXjE1GbemJYHqdNjX0= github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE= github.com/sagikazarmark/slog-shim v0.1.0/go.mod h1:SrcSrq8aKtyuqEI1uvTDTK1arOWRIczQRv+GVI1AkeQ= -github.com/senzing-garage/go-cmdhelping v0.2.3 h1:Jrmi9MO5IXCRQJNJfrT997NyKJBWhLYqceuLL4ihJ2U= -github.com/senzing-garage/go-cmdhelping v0.2.3/go.mod h1:hbiwmnektgCEJ155QYjGxlTOHZbV1eMcOyU9a/qzAS8= +github.com/senzing-garage/go-cmdhelping v0.3.0 h1:6Yo6tYdYXrCuMwsOKdAErwPGvCi8y9PAFV2UVPOffi0= +github.com/senzing-garage/go-cmdhelping v0.3.0/go.mod h1:J6M/yRqP9ZrwuEQFyxZ9JwkvMis8lZeR4Ot4G0u5YMc= github.com/sourcegraph/conc v0.3.0 h1:OQTbbt6P72L20UqAkXXuLOj79LfEanQ+YQFNpLA9ySo= github.com/sourcegraph/conc v0.3.0/go.mod h1:Sdozi7LEKbFPqYX2/J+iBAM6HpqSLTASQIKqDmF7Mt0= github.com/spf13/afero v1.11.0 h1:WJQKhtpdm3v2IzqG8VMqrr6Rf3UYpEF239Jy9wNepM8= github.com/spf13/afero v1.11.0/go.mod h1:GH9Y3pIexgf1MTIWtNGyogA5MwRIDXGUr+hbWNoBjkY= -github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0= -github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo= +github.com/spf13/cast v1.7.0 h1:ntdiHjuueXFgm5nzDRdOS4yfT43P5Fnud6DH50rz/7w= +github.com/spf13/cast v1.7.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo= github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM= github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= @@ -64,13 +64,13 @@ github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= -golang.org/x/exp v0.0.0-20240707233637-46b078467d37 h1:uLDX+AfeFCct3a2C7uIWBKMJIR3CJMhcgfrUAqjRK6w= -golang.org/x/exp v0.0.0-20240707233637-46b078467d37/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY= +golang.org/x/exp v0.0.0-20240808152545-0cdaa3abc0fa h1:ELnwvuAXPNtPk1TJRuGkI9fDTwym6AYBu0qzT8AcHdI= +golang.org/x/exp v0.0.0-20240808152545-0cdaa3abc0fa/go.mod h1:akd2r19cwCdwSwWeIdzYQGa/EZZyqcOdwWiwj5L5eKQ= golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.22.0 h1:RI27ohtqKCnwULzJLqkv897zojh5/DwS/ENaMzUOaWI= -golang.org/x/sys v0.22.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= -golang.org/x/text v0.16.0 h1:a94ExnEXNtEwYLGJSIUxnWoxoRz/ZcCsV63ROupILh4= -golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI= +golang.org/x/sys v0.24.0 h1:Twjiwq9dn6R1fQcyiK+wQyHWfaz/BJB+YIpzU/Cv3Xg= +golang.org/x/sys v0.24.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/text v0.17.0 h1:XtiM5bkSOt+ewxlOE/aE/AKEHibwj/6gvWMl9Rsh0Qc= +golang.org/x/text v0.17.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= diff --git a/main_test.go b/main_test.go index 3568726..edcfc1d 100644 --- a/main_test.go +++ b/main_test.go @@ -5,9 +5,6 @@ import ( "testing" ) -/* - * The unit tests in this file simulate command line invocation. - */ func TestMain(test *testing.T) { _ = test os.Args = []string{"command-name", "--message-id", "SZSDK60010000", "--tty-only"} diff --git a/makefiles/darwin.mk b/makefiles/darwin.mk index df469d9..ce801b4 100644 --- a/makefiles/darwin.mk +++ b/makefiles/darwin.mk @@ -16,9 +16,13 @@ build-osarch-specific: darwin/amd64 .PHONY: clean-osarch-specific clean-osarch-specific: @rm -f $(GOPATH)/bin/$(PROGRAM_NAME) || true + @rm -f $(MAKEFILE_DIRECTORY)/.coverage || true @rm -f $(MAKEFILE_DIRECTORY)/coverage.html || true @rm -f $(MAKEFILE_DIRECTORY)/coverage.out || true + @rm -f $(MAKEFILE_DIRECTORY)/cover.out || true @rm -fr $(TARGET_DIRECTORY) || true + @rm -fr /tmp/sqlite || true + @pkill godoc || true .PHONY: coverage-osarch-specific @@ -28,14 +32,20 @@ coverage-osarch-specific: @open file://$(MAKEFILE_DIRECTORY)/coverage.html +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + @godoc & + @open http://localhost:6060 + + .PHONY: hello-world-osarch-specific hello-world-osarch-specific: - @echo "Hello World, from darwin." + $(info Hello World, from darwin.) .PHONY: package-osarch-specific package-osarch-specific: - @echo No packaging for darwin. + $(info No packaging for darwin.) .PHONY: run-osarch-specific @@ -45,12 +55,12 @@ run-osarch-specific: .PHONY: setup-osarch-specific setup-osarch-specific: - @echo "No setup required." + $(info No setup required.) .PHONY: test-osarch-specific test-osarch-specific: - @go test -exec macos_exec_dyld.sh -v -p 1 ./... + @go test -json -v -p 1 ./... 2>&1 | tee /tmp/gotest.log | gotestfmt # ----------------------------------------------------------------------------- # Makefile targets supported only by this platform. @@ -58,4 +68,4 @@ test-osarch-specific: .PHONY: only-darwin only-darwin: - @echo "Only darwin has this Makefile target." + $(info Only darwin has this Makefile target.) diff --git a/makefiles/linux.mk b/makefiles/linux.mk index 96892fb..800641e 100644 --- a/makefiles/linux.mk +++ b/makefiles/linux.mk @@ -16,30 +16,39 @@ build-osarch-specific: linux/amd64 .PHONY: clean-osarch-specific clean-osarch-specific: @rm -f $(GOPATH)/bin/$(PROGRAM_NAME) || true + @rm -f $(MAKEFILE_DIRECTORY)/.coverage || true @rm -f $(MAKEFILE_DIRECTORY)/coverage.html || true @rm -f $(MAKEFILE_DIRECTORY)/coverage.out || true + @rm -f $(MAKEFILE_DIRECTORY)/cover.out || true @rm -fr $(TARGET_DIRECTORY) || true + @rm -fr /tmp/sqlite || true + @pkill godoc || true .PHONY: coverage-osarch-specific -coverage-osarch-specific: export SENZING_LOG_LEVEL=TRACE coverage-osarch-specific: @go test -v -coverprofile=coverage.out -p 1 ./... @go tool cover -html="coverage.out" -o coverage.html @xdg-open $(MAKEFILE_DIRECTORY)/coverage.html +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + @godoc & + @xdg-open http://localhost:6060 + + .PHONY: hello-world-osarch-specific hello-world-osarch-specific: - @echo "Hello World, from linux." + $(info Hello World, from linux.) .PHONY: package-osarch-specific package-osarch-specific: docker-build-package @mkdir -p $(TARGET_DIRECTORY) || true @CONTAINER_ID=$$(docker create $(DOCKER_BUILD_IMAGE_NAME)); \ - docker cp $$CONTAINER_ID:/output/. $(TARGET_DIRECTORY)/; \ - docker rm -v $$CONTAINER_ID + @docker cp $$CONTAINER_ID:/output/. $(TARGET_DIRECTORY)/; \ + @docker rm -v $$CONTAINER_ID .PHONY: run-osarch-specific @@ -49,12 +58,12 @@ run-osarch-specific: .PHONY: setup-osarch-specific setup-osarch-specific: - @echo "No setup required." + $(info No setup required.) .PHONY: test-osarch-specific test-osarch-specific: - @go test -v -p 1 ./... + @go test -json -v -p 1 ./... 2>&1 | tee /tmp/gotest.log | gotestfmt # ----------------------------------------------------------------------------- # Makefile targets supported only by this platform. @@ -62,4 +71,4 @@ test-osarch-specific: .PHONY: only-linux only-linux: - @echo "Only linux has this Makefile target." + $(info Only linux has this Makefile target.) diff --git a/makefiles/windows.mk b/makefiles/windows.mk index 9ae4416..b677498 100644 --- a/makefiles/windows.mk +++ b/makefiles/windows.mk @@ -16,27 +16,36 @@ build-osarch-specific: windows/amd64 .PHONY: clean-osarch-specific clean-osarch-specific: - del /F /S /Q $(GOPATH)/bin/$(PROGRAM_NAME) - del /F /S /Q $(MAKEFILE_DIRECTORY)/coverage.html - del /F /S /Q $(MAKEFILE_DIRECTORY)/coverage.out - del /F /S /Q $(TARGET_DIRECTORY) + @del /F /S /Q $(GOPATH)/bin/$(PROGRAM_NAME) + @del /F /S /Q $(MAKEFILE_DIRECTORY)/coverage.html + @del /F /S /Q $(MAKEFILE_DIRECTORY)/coverage.out + @del /F /S /Q $(MAKEFILE_DIRECTORY)/cover.out + @del /F /S /Q $(TARGET_DIRECTORY) + @del /F /S /Q C:\Temp\sqlite + @taskkill /f /t/im godoc .PHONY: coverage-osarch-specific coverage-osarch-specific: @go test -v -coverprofile=coverage.out -p 1 ./... @go tool cover -html="coverage.out" -o coverage.html - @xdg-open file://$(MAKEFILE_DIRECTORY)/coverage.html + @explorer file://$(MAKEFILE_DIRECTORY)/coverage.html + + +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + @start /b godoc + @explorer http://localhost:6060 .PHONY: hello-world-osarch-specific hello-world-osarch-specific: - @echo "Hello World, from windows." + $(info Hello World, from windows.) .PHONY: package-osarch-specific package-osarch-specific: - @echo No packaging for windows. + $(info No packaging for windows) .PHONY: run-osarch-specific @@ -51,7 +60,7 @@ setup-osarch-specific: .PHONY: test-osarch-specific test-osarch-specific: - @go test -v -p 1 ./... + @go test -json -v -p 1 ./... 2>&1 | tee /tmp/gotest.log | gotestfmt # ----------------------------------------------------------------------------- # Makefile targets supported only by this platform. @@ -59,4 +68,4 @@ test-osarch-specific: .PHONY: only-windows only-windows: - @echo "Only windows has this Makefile target." + $(info Only windows has this Makefile target.) diff --git a/package.Dockerfile b/package.Dockerfile index 23118f2..cb6543f 100755 --- a/package.Dockerfile +++ b/package.Dockerfile @@ -2,7 +2,7 @@ # Stages # ----------------------------------------------------------------------------- -ARG IMAGE_GO_BUILDER=golang:1.21.4-bullseye +ARG IMAGE_GO_BUILDER=golang:1.22.3-bullseye ARG IMAGE_FPM_BUILDER=dockter/fpm:latest ARG IMAGE_FINAL=alpine @@ -10,11 +10,11 @@ ARG IMAGE_FINAL=alpine # Stage: go_builder # ----------------------------------------------------------------------------- -FROM ${IMAGE_GO_BUILDER} as go_builder -ENV REFRESHED_AT=2023-08-01 -LABEL Name="senzing/explain-builder" \ - Maintainer="support@senzing.com" \ - Version="0.2.0" +FROM ${IMAGE_GO_BUILDER} AS go_builder +ENV REFRESHED_AT=2024-07-01 +LABEL Name="senzing/go-builder" \ + Maintainer="support@senzing.com" \ + Version="0.1.0" # Build arguments. @@ -28,8 +28,6 @@ ARG GO_PACKAGE_NAME="unknown" COPY ./rootfs / COPY . ${GOPATH}/src/${GO_PACKAGE_NAME} -HEALTHCHECK CMD ["/healthcheck.sh"] - # Build go program. WORKDIR ${GOPATH}/src/${GO_PACKAGE_NAME} @@ -38,7 +36,7 @@ RUN make linux/amd64 # Copy binaries to /output. RUN mkdir -p /output \ - && cp -R ${GOPATH}/src/${GO_PACKAGE_NAME}/target/* /output/ + && cp -R ${GOPATH}/src/${GO_PACKAGE_NAME}/target/* /output/ # ----------------------------------------------------------------------------- # Stage: fpm_builder @@ -46,11 +44,11 @@ RUN mkdir -p /output \ # - FPM: https://fpm.readthedocs.io/en/latest/cli-reference.html # ----------------------------------------------------------------------------- -FROM ${IMAGE_FPM_BUILDER} as fpm_builder -ENV REFRESHED_AT=2023-08-01 -LABEL Name="senzing/explain-fpm-builder" \ - Maintainer="support@senzing.com" \ - Version="0.2.0" +FROM ${IMAGE_FPM_BUILDER} AS fpm_builder +ENV REFRESHED_AT=2024-07-01 +LABEL Name="senzing/fpm-builder" \ + Maintainer="support@senzing.com" \ + Version="0.1.0" # Use arguments from prior stage. @@ -66,35 +64,40 @@ COPY --from=go_builder "/output/linux-amd64/*" "/output/linux-amd64/" # Create Linux RPM package. RUN fpm \ - --input-type dir \ - --output-type rpm \ - --name ${PROGRAM_NAME} \ - --package /output/${PROGRAM_NAME}-${BUILD_VERSION}.rpm \ - --version ${BUILD_VERSION} \ - --iteration ${BUILD_ITERATION} \ - /output/linux-amd64/=/usr/bin + --input-type dir \ + --output-type rpm \ + --name ${PROGRAM_NAME} \ + --package /output/${PROGRAM_NAME}-${BUILD_VERSION}.rpm \ + --version ${BUILD_VERSION} \ + --iteration ${BUILD_ITERATION} \ + /output/linux-amd64/=/usr/bin # Create Linux DEB package. RUN fpm \ - --deb-no-default-config-files \ - --input-type dir \ - --iteration ${BUILD_ITERATION} \ - --name ${PROGRAM_NAME} \ - --output-type deb \ - --package /output/${PROGRAM_NAME}-${BUILD_VERSION}.deb \ - --version ${BUILD_VERSION} \ - /output/linux-amd64/=/usr/bin + --deb-no-default-config-files \ + --input-type dir \ + --iteration ${BUILD_ITERATION} \ + --name ${PROGRAM_NAME} \ + --output-type deb \ + --package /output/${PROGRAM_NAME}-${BUILD_VERSION}.deb \ + --version ${BUILD_VERSION} \ + /output/linux-amd64/=/usr/bin # ----------------------------------------------------------------------------- # Stage: final # ----------------------------------------------------------------------------- -FROM ${IMAGE_FINAL} as final -ENV REFRESHED_AT=2023-08-01 -LABEL Name="senzing/explain" \ - Maintainer="support@senzing.com" \ - Version="0.2.0" +FROM ${IMAGE_FINAL} AS final +ENV REFRESHED_AT=2024-07-01 +LABEL Name="senzing/final-stage" \ + Maintainer="support@senzing.com" \ + Version="0.1.0" +HEALTHCHECK CMD ["/app/healthcheck.sh"] + +# Copy files from repository. + +COPY ./rootfs / # Use arguments from prior stage. @@ -106,5 +109,4 @@ COPY --from=fpm_builder "/output/*" "/output/" COPY --from=fpm_builder "/output/linux-amd64/${PROGRAM_NAME}" "/output/linux-amd64/${PROGRAM_NAME}" USER 1001 - CMD ["/bin/bash"] From 41465768afa15ed084b7a5c67cc6e1455539adb7 Mon Sep 17 00:00:00 2001 From: docktermj Date: Tue, 20 Aug 2024 17:38:29 -0400 Subject: [PATCH 2/4] #69 migrate from g2 to sz/er --- CHANGELOG.md | 6 +++++ README.md | 65 +++++++++++++++++++++++---------------------- doc.go | 48 --------------------------------- docs/development.md | 7 ++--- 4 files changed, 43 insertions(+), 83 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5564116..b902fbc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.0] - 2024-08-20 + +### Changed in 0.3.0 + +- Change from `g2` to `sz`/`er` + ## [0.2.2] - 2024-06-12 ### Changed in 0.2.2 diff --git a/README.md b/README.md index 685b836..c980d8e 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,7 @@ the recommendation is not to use it yet. ## Synopsis -`explain` is a command in the -[senzing-tools](https://github.com/senzing-garage/senzing-tools) -suite of tools. +`explain` is a command in the [senzing-tools] suite of tools. It is used to explain aspects of `senzing-tools`. [![Go Reference Badge]][Package reference] @@ -43,10 +41,8 @@ It is used to explain aspects of `senzing-tools`. ## Install -1. The `explain` command is installed with the - [senzing-tools](https://github.com/senzing-garage/senzing-tools) - suite of tools. - See senzing-tools [install](https://github.com/senzing-garage/senzing-tools#install). +1. The `explain` command is installed with the [senzing-tools] suite of tools. + See [senzing-tools install]. ## Use @@ -56,7 +52,7 @@ senzing-tools explain [flags] ``` 1. For options and flags: - 1. [Online documentation](https://hub.senzing.com/senzing-tools/senzing-tools_explain.html) + 1. [Online documentation] 1. Runtime documentation: ```console @@ -64,7 +60,7 @@ senzing-tools explain [flags] senzing-tools explain --help ``` -1. In addition to the following simple usage examples, there are additional [Examples](docs/examples.md). +1. In addition to the following simple usage examples, there are additional [Examples]. ### Using command line options @@ -76,7 +72,7 @@ senzing-tools explain [flags] senzing-tools explain ``` -1. See [Parameters](#parameters) for additional parameters. +1. See [Parameters] for additional parameters. ### Using environment variables @@ -89,14 +85,14 @@ senzing-tools explain [flags] senzing-tools explain ``` -1. See [Parameters](#parameters) for additional parameters. +1. See [Parameters] for additional parameters. ### Parameters -- **[LD_LIBRARY_PATH](https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#ld_library_path)** -- **[SENZING_TOOLS_COMMAND](https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_command)** -- **[SENZING_TOOLS_MESSAGE_ID](https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_message_id)** -- **[SENZING_TOOLS_TTY_ONLY](https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_tty_only)** +- **[LD_LIBRARY_PATH]** +- **[SENZING_TOOLS_COMMAND]** +- **[SENZING_TOOLS_MESSAGE_ID]** +- **[SENZING_TOOLS_TTY_ONLY]** ## References @@ -105,28 +101,33 @@ senzing-tools explain [flags] 1. [Errors] 1. [Examples] 1. [Package reference] -1. Related artifacts: - 1. [DockerHub] -[API documentation]: https://pkg.go.dev/github.com/senzing-garage/template-go +[API documentation]: https://pkg.go.dev/github.com/senzing-garage/explain [Development]: docs/development.md -[DockerHub]: https://hub.docker.com/r/senzing/template-go [Errors]: docs/errors.md [Examples]: docs/examples.md -[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg -[Go Report Card Badge]: https://goreportcard.com/badge/github.com/senzing-garage/template-go -[Go Report Card]: https://goreportcard.com/report/github.com/senzing-garage/template-go -[go-test-darwin.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml/badge.svg -[go-test-darwin.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml -[go-test-linux.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml/badge.svg -[go-test-linux.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml -[go-test-windows.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml/badge.svg -[go-test-windows.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml -[golangci-lint.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml/badge.svg -[golangci-lint.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml +[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/explain.svg +[Go Report Card Badge]: https://goreportcard.com/badge/github.com/senzing-garage/explain +[Go Report Card]: https://goreportcard.com/report/github.com/senzing-garage/explain +[go-test-darwin.yaml Badge]: https://github.com/senzing-garage/explain/actions/workflows/go-test-darwin.yaml/badge.svg +[go-test-darwin.yaml]: https://github.com/senzing-garage/explain/actions/workflows/go-test-darwin.yaml +[go-test-linux.yaml Badge]: https://github.com/senzing-garage/explain/actions/workflows/go-test-linux.yaml/badge.svg +[go-test-linux.yaml]: https://github.com/senzing-garage/explain/actions/workflows/go-test-linux.yaml +[go-test-windows.yaml Badge]: https://github.com/senzing-garage/explain/actions/workflows/go-test-windows.yaml/badge.svg +[go-test-windows.yaml]: https://github.com/senzing-garage/explain/actions/workflows/go-test-windows.yaml +[golangci-lint.yaml Badge]: https://github.com/senzing-garage/explain/actions/workflows/golangci-lint.yaml/badge.svg +[golangci-lint.yaml]: https://github.com/senzing-garage/explain/actions/workflows/golangci-lint.yaml +[LD_LIBRARY_PATH]: https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#ld_library_path [License Badge]: https://img.shields.io/badge/License-Apache2-brightgreen.svg -[License]: https://github.com/senzing-garage/template-go/blob/main/LICENSE -[Package reference]: https://pkg.go.dev/github.com/senzing-garage/template-go +[License]: https://github.com/senzing-garage/explain/blob/main/LICENSE +[Online documentation]: https://hub.senzing.com/senzing-tools/senzing-tools_explain.html +[Package reference]: https://pkg.go.dev/github.com/senzing-garage/explain +[Parameters]: #parameters [Senzing Garage]: https://github.com/senzing-garage [Senzing Quick Start guides]: https://docs.senzing.com/quickstart/ +[SENZING_TOOLS_COMMAND]: https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_command +[SENZING_TOOLS_MESSAGE_ID]: https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_message_id +[SENZING_TOOLS_TTY_ONLY]: https://github.com/senzing-garage/knowledge-base/blob/main/lists/environment-variables.md#senzing_tools_tty_only +[senzing-tools install]: https://github.com/senzing-garage/senzing-tools#install +[senzing-tools]: https://github.com/senzing-garage/senzing-tools [Senzing]: https://senzing.com/ diff --git a/doc.go b/doc.go index 45eaefa..044fa0d 100644 --- a/doc.go +++ b/doc.go @@ -1,52 +1,4 @@ /* One or two sentence synopsys of the module. The Senzing XXXX module is... - -# Overview - -One or two paragraph overview of this module... - -(This page describes the nature of the entire Go module or the top-level command, not an individual package.) - -More information at https://github.com/senzing-garage/explain - -# Example Package - -The example package gives an example layout for a package. This includes how -documentation, tests, and examples should be done. This paragraph (or two) -should provide a brief overview while linking the reader to the documentation -included in the package itself. - -More information can be found in the [pkg/github.com/senzing-garage/explain/examplepackage] documentation. - -# Another Header: Package or other module features... - -More details about the module... -Lorem ipsum dolor sit amet, consectetur adipiscing elit... - -# Examples - -The examples given here should show a holistic view of the module, if appropriate. - -Examples of use can be seen in the main_test.go files. - - package main - import ( - fmt - - "github.com/senzing-garage/explain/examplepackage" - "github.com/senzing-garage/explain/anotherpackage" - ) - - func main() { - ctx := context.TODO() - testObject := &ExamplePackageImpl{ - Something: "I'm here", - } - err := testObject.SaySomething(ctx) - if err != nil { - fmt.Println("whoops") - } - anotherpackage.DoSomething(ctx)... - } */ package main diff --git a/docs/development.md b/docs/development.md index 2c2ada3..6ff5155 100644 --- a/docs/development.md +++ b/docs/development.md @@ -183,6 +183,7 @@ Example: make clean ``` + ## Package ### Package RPM and DEB files @@ -244,10 +245,10 @@ Example: [clone-repository]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md [docker]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/docker.md [git]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/git.md -[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg -[Go Reference]: https://pkg.go.dev/github.com/senzing-garage/template-go +[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/explain.svg +[Go Reference]: https://pkg.go.dev/github.com/senzing-garage/explain [go]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/go.md [How to Install Senzing for Go Development]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md -[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/template-go/ +[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/explain/ [make]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/make.md [testcoverage.yaml]: ../.github/coverage/testcoverage.yaml From c2cbdd67122664a139813a7a71f21b7d75c96c72 Mon Sep 17 00:00:00 2001 From: docktermj Date: Wed, 21 Aug 2024 10:14:24 -0400 Subject: [PATCH 3/4] #69 Normalize to template --- .github/workflows/golangci-lint.yaml | 59 ++++++++++++++++++++++++++++ Makefile | 1 + cmd/doc.go | 2 +- doc.go | 2 +- docs/development.md | 4 +- explainer/doc.go | 38 +----------------- makefiles/linux.mk | 4 +- package.Dockerfile | 4 +- rootfs/.dummy.txt | 0 rootfs/app/container-test.sh | 12 ++++++ rootfs/{ => app}/healthcheck.sh | 0 11 files changed, 80 insertions(+), 46 deletions(-) create mode 100644 .github/workflows/golangci-lint.yaml delete mode 100644 rootfs/.dummy.txt create mode 100644 rootfs/app/container-test.sh rename rootfs/{ => app}/healthcheck.sh (100%) diff --git a/.github/workflows/golangci-lint.yaml b/.github/workflows/golangci-lint.yaml new file mode 100644 index 0000000..444b398 --- /dev/null +++ b/.github/workflows/golangci-lint.yaml @@ -0,0 +1,59 @@ +name: Golangci lint + +on: + push: + branches-ignore: [main] + pull_request: + branches: [main] + +permissions: + # Required: allow read access to the content for analysis. + contents: read + # Optional: allow read access to pull request. Use with `only-new-issues` option. + pull-requests: read + +jobs: + golangci: + name: lint + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install Senzing API + uses: senzing-factory/github-action-install-senzing-api@v3 + with: + senzingapi-runtime-version: staging-v4 + + - name: Copy Senzing headers + run: | + mkdir --parents ./szconfig/gohelpers + cp /opt/senzing/er/sdk/c/*.h ./szconfig/ + cp /opt/senzing/er/sdk/c/gohelpers/*.h ./szconfig/gohelpers + mkdir --parents ./szconfigmanager/gohelpers + cp /opt/senzing/er/sdk/c/*.h ./szconfigmanager/ + cp /opt/senzing/er/sdk/c/gohelpers/*.h ./szconfigmanager/gohelpers + mkdir --parents ./szdiagnostic/gohelpers + cp /opt/senzing/er/sdk/c/*.h ./szdiagnostic/ + cp /opt/senzing/er/sdk/c/gohelpers/*.h ./szdiagnostic/gohelpers + mkdir --parents ./szengine/gohelpers + cp /opt/senzing/er/sdk/c/*.h ./szengine/ + cp /opt/senzing/er/sdk/c/gohelpers/*.h ./szengine/gohelpers + mkdir --parents ./szproduct/gohelpers + cp /opt/senzing/er/sdk/c/*.h ./szproduct/ + cp /opt/senzing/er/sdk/c/gohelpers/*.h ./szproduct/gohelpers + + - name: Setup go + uses: actions/setup-go@v5 + with: + go-version: 1.21 + + - name: Perform linting + uses: golangci/golangci-lint-action@v6 + with: + args: --config=${{ github.workspace }}/.github/linters/.golangci.yaml + only-new-issues: false + version: latest diff --git a/Makefile b/Makefile index ad62ae4..9576d5b 100644 --- a/Makefile +++ b/Makefile @@ -38,6 +38,7 @@ GO_ARCH = $(word 2, $(GO_OSARCH)) # Can be overridden with "export" # Example: "export LD_LIBRARY_PATH=/path/to/my/senzing/er/lib" +DOCKER_IMAGE_TAG ?= $(GIT_REPOSITORY_NAME):$(GIT_VERSION) GOBIN ?= $(shell go env GOPATH)/bin LD_LIBRARY_PATH ?= /opt/senzing/er/lib diff --git a/cmd/doc.go b/cmd/doc.go index 631a207..b78ad9e 100644 --- a/cmd/doc.go +++ b/cmd/doc.go @@ -1,4 +1,4 @@ /* -The cmd package is used for Cobra integration. +Package cmd is used for Cobra and Viper integration. */ package cmd diff --git a/doc.go b/doc.go index 044fa0d..ed6e2ed 100644 --- a/doc.go +++ b/doc.go @@ -1,4 +1,4 @@ /* -One or two sentence synopsys of the module. The Senzing XXXX module is... +Module explain is the implementation of the "senzing-tools explain" command. */ package main diff --git a/docs/development.md b/docs/development.md index 6ff5155..eca91bf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -13,7 +13,6 @@ These are "one-time tasks" which may already have been completed. 1. The following software programs need to be installed: 1. [git] 1. [make] - 1. [docker] 1. [go] ## Install Senzing C library @@ -168,7 +167,7 @@ Create a code coverage map. 1. If a web page doesn't appear, visit [localhost:6060]. 1. Senzing documentation will be in the "Third party" section. - `github.com` > `senzing` > `go-cmdhelping` + `github.com` > `senzing` > `explain` 1. When a versioned release is published with a `v0.0.0` format tag, the reference can be found by clicking on the following badge at the top of the README.md page. @@ -243,7 +242,6 @@ Example: ## References [clone-repository]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md -[docker]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/docker.md [git]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/git.md [Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/explain.svg [Go Reference]: https://pkg.go.dev/github.com/senzing-garage/explain diff --git a/explainer/doc.go b/explainer/doc.go index 107ba9e..52d7b53 100644 --- a/explainer/doc.go +++ b/explainer/doc.go @@ -1,40 +1,4 @@ /* -One or two sentence synopsis of the package... - -# Overview - -One or two paragraph overview of the package... -(This page describes the nature of the individual package.) - -More information at https://github.com/senzing-garage/explain - -# Another Header - -Details of the package... -Lorem ipsum dolor sit amet, consectetur adipiscing elit... - -# Examples - -The examples given here should be specific to the package. - -Examples of use can be seen in the examplepackage_test.go files. - - package main - import ( - fmt - - "github.com/senzing-garage/explain/examplepackage" - ) - - func main() { - ctx := context.TODO() - testObject := &ExamplePackageImpl{ - Something: "I'm here", - } - err := testObject.SaySomething(ctx) - if err != nil { - fmt.Println("whoops") - } - } +Package explainer implements the "explainer" command. */ package explainer diff --git a/makefiles/linux.mk b/makefiles/linux.mk index 800641e..9896ffa 100644 --- a/makefiles/linux.mk +++ b/makefiles/linux.mk @@ -47,8 +47,8 @@ hello-world-osarch-specific: package-osarch-specific: docker-build-package @mkdir -p $(TARGET_DIRECTORY) || true @CONTAINER_ID=$$(docker create $(DOCKER_BUILD_IMAGE_NAME)); \ - @docker cp $$CONTAINER_ID:/output/. $(TARGET_DIRECTORY)/; \ - @docker rm -v $$CONTAINER_ID + docker cp $$CONTAINER_ID:/output/. $(TARGET_DIRECTORY)/; \ + docker rm -v $$CONTAINER_ID .PHONY: run-osarch-specific diff --git a/package.Dockerfile b/package.Dockerfile index cb6543f..e1c8f17 100755 --- a/package.Dockerfile +++ b/package.Dockerfile @@ -105,8 +105,8 @@ ARG PROGRAM_NAME # Copy files from prior step. -COPY --from=fpm_builder "/output/*" "/output/" -COPY --from=fpm_builder "/output/linux-amd64/${PROGRAM_NAME}" "/output/linux-amd64/${PROGRAM_NAME}" +COPY --from=fpm_builder "/output/*" "/output/" +COPY --from=fpm_builder "/output/linux-amd64/${PROGRAM_NAME}" "/output/linux-amd64/${PROGRAM_NAME}" USER 1001 CMD ["/bin/bash"] diff --git a/rootfs/.dummy.txt b/rootfs/.dummy.txt deleted file mode 100644 index e69de29..0000000 diff --git a/rootfs/app/container-test.sh b/rootfs/app/container-test.sh new file mode 100644 index 0000000..9f72897 --- /dev/null +++ b/rootfs/app/container-test.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +# Return codes. + +OK=0 +NOT_OK=1 + +# Tests. + +echo "Doing testing." + +exit ${OK} diff --git a/rootfs/healthcheck.sh b/rootfs/app/healthcheck.sh similarity index 100% rename from rootfs/healthcheck.sh rename to rootfs/app/healthcheck.sh From f421f80ef17e2cb08edb1f5e9bffceaf4f3a32b1 Mon Sep 17 00:00:00 2001 From: docktermj Date: Wed, 21 Aug 2024 10:22:49 -0400 Subject: [PATCH 4/4] #69 Prepare for versioned release --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b902fbc..7f6b9cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [0.3.0] - 2024-08-20 +## [0.3.0] - 2024-08-21 ### Changed in 0.3.0