diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 76% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md index 464d570d20..9137fa6b9b 100644 --- a/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -15,6 +15,20 @@ Specifically: - We perform automated testing on all changes before they get merged to `main` - We create immutable release artifacts +### Pre-Commit Hooks and Linting + +We use [pre-commit](https://pre-commit.com/) to manage our pre-commit hooks. This ensures that all code is linted and formatted before it is committed. After `pre-commit` is [installed](https://pre-commit.com/#installation): + +```bash +# install hooks +pre-commit install + +# install goimports +go install golang.org/x/tools/cmd/goimports@latest +``` + +Now every time you commit, the hooks will run and format your code, linting can be called via `make lint-go`. + ### Developer Workflow :key: == Required by automation @@ -34,30 +48,19 @@ Specifically: ## Testing -This section dives deeper into how we test Zarf - -### (Optional) Pre-Commit Hooks and Linting - -In this repo you can optionally use [pre-commit](https://pre-commit.com/) hooks for automated validation and linting, but if not CI will run these checks for you. +> A more comprehensive guide to testing can be found [here](https://docs.zarf.dev/contribute/testing). -### Code Testing +Our E2E tests can be found in the `src/test` folder and follow the journey of someone as they would use the Zarf CLI. In CI these tests run against our currently supported cluster distros and are the primary way that Zarf code is tested. -Our E2E tests can be found in the `/test` folder and follow the journey of someone as they would use the Zarf CLI. In CI these tests run against our currently supported cluster distros and are the primary way that Zarf code is tested. - -Our Unit tests can be found as `*_test.go` files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. As a general rule, we are limiting unit tests to the `src/pkg/*` folder. - -All of our tests should be able to be run locally or in CI. -You can learn more about the testing of Zarf [here](https://docs.zarf.dev/contribute/testing). +Our unit tests can be found as `*_test.go` files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. ## Documentation -### Updating Our Documentation - -Our documentation is auto-generated from the `src/types` and `src/cmd` go packages. This includes the [Zarf package jsonschema](https://github.com/defenseunicorns/zarf/blob/main/zarf.schema.json), the [Zarf schema docs](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-schema), and the [Zarf CLI docs](https://docs.zarf.dev/docs/the-zarf-cli/). When an update to types or the CLI commands is made you will need to run `make docs-and-schema` locally to regenerate the schema and documentation. CI checks if this was ran, and will fail if it wasn't. +The CLI docs (located at `site/src/content/docs/commands`), and [`zarf.schema.json`](https://github.com/defenseunicorns/zarf/blob/main/zarf.schema.json) are autogenerated from `make docs-and-schema`. Run this make target locally to regenerate the schema and documentation each time you make a change to the CLI commands or the schema, otherwise CI will fail. We do this so that there is a git commit signature from a person on the commit for better traceability, rather than a non-person entity (e.g. GitHub CI token). -### Architecture Decision Records (ADR) +## Architecture Decision Records (ADR) We've chosen to use ADRs to document architecturally significant decisions. We primarily use the guidance found in [this article by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) with a couple of tweaks: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 370d4faa9a..cee28d19f1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,4 +11,4 @@ Relates to # ## Checklist before merging - [ ] Test, docs, adr added or updated as needed -- [ ] [Contributor Guide Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow) followed +- [ ] [Contributor Guide Steps](https://github.com/defenseunicorns/zarf/blob/main/.github/CONTRIBUTING.md#developer-workflow) followed diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8c7700afb1..7b3bcc66b4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,25 +9,14 @@ repos: args: - "--allow-missing-credentials" - id: detect-private-key - exclude: | - (?x)^( - examples/big-bang/kustomization/values.yaml| - examples/istio-with-separate-cert/files/bigbangdev.key - )$ - id: end-of-file-fixer - exclude: "^examples/big-bang/template/bigbang/vendor/.*$" - id: fix-byte-order-marker - id: trailing-whitespace - exclude: "^examples/big-bang/template/bigbang/vendor/.*$" args: [--markdown-linebreak-ext=md] - - repo: https://github.com/sirosen/fix-smartquotes - rev: 0.2.0 + - repo: https://github.com/sirosen/texthooks + rev: 0.6.4 hooks: - id: fix-smartquotes - - repo: https://github.com/dnephin/pre-commit-golang - rev: v0.4.0 - hooks: - - id: go-fmt - repo: local hooks: - id: check-docs-and-schema @@ -36,9 +25,15 @@ repos: files: "src/types/types.go" types: [go] language: script - description: - "Checks if there have been changes - made to the docs and schema" + - id: goimports + name: goimports + entry: goimports + files: .go$ + args: + - -l + - -w + language: system + pass_filenames: true - repo: https://github.com/python-jsonschema/check-jsonschema rev: 0.14.0 hooks: diff --git a/examples/big-bang/config/neuvector.yaml b/examples/big-bang/config/neuvector.yaml index e7ea4f7707..d804274901 100644 --- a/examples/big-bang/config/neuvector.yaml +++ b/examples/big-bang/config/neuvector.yaml @@ -1,4 +1,4 @@ -# If running in k3s, this is needed for Neuvector to start properly +# If running in k3s, this is needed for Neuvector to start properly neuvector: values: k3s: diff --git a/examples/kiwix/zarf.yaml b/examples/kiwix/zarf.yaml index b353812d88..0ddf467086 100644 --- a/examples/kiwix/zarf.yaml +++ b/examples/kiwix/zarf.yaml @@ -50,5 +50,5 @@ x-mdx: | Data injections depend on the `tar` (and for `compress`, `gzip`) executables and their implementation across operating systems. Between macOS and Linux there is general agreement on how these utilities should function, however on Windows you may see issues enabling compression. To resolve this you can either disable compression or use the GNU core-utils version of `tar` and `gzip`. - + ::: diff --git a/netlify.toml b/netlify.toml index 3521d1663b..3c974ecbf2 100644 --- a/netlify.toml +++ b/netlify.toml @@ -2,7 +2,27 @@ base = "site/" command = "npm run build" publish = "dist/" - ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . src/content/docs ../examples/" + ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . src/content/ ../examples/" [build.environment] NODE_VERSION = "20.11.1" + +[[redirects]] +from = "/docs/the-zarf-cli/cli-commands/*" +to = "/commands/:splat" + +[[redirects]] +from = "/docs/create-a-zarf-package/*" +to = "/ref/" + +[[redirects]] +from = "/docs/deploy-a-zarf-package/*" +to = "/ref/" + +[[redirects]] +from = "/examples/*" +to = "/ref/examples/:splat" + +[[redirects]] +from = "/docs/:page" +to = "/:page" diff --git a/packages/logging-pgl/connect.yaml b/packages/logging-pgl/connect.yaml index a72eaa2883..41be9204d6 100644 --- a/packages/logging-pgl/connect.yaml +++ b/packages/logging-pgl/connect.yaml @@ -4,7 +4,7 @@ metadata: name: zarf-connect-logging labels: # Enables "zarf connect logging" - zarf.dev/connect-name: logging + zarf.dev/connect-name: logging annotations: zarf.dev/connect-description: "Zarf Cluster Logging Service (Grafana)" spec: diff --git a/site/src/components/StripH1.astro b/site/src/components/StripH1.astro new file mode 100644 index 0000000000..d39e8968e4 --- /dev/null +++ b/site/src/components/StripH1.astro @@ -0,0 +1,9 @@ +--- +let html = await Astro.slots.render("default"); + +// remove any h1 from the html +const h1 = /