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/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 = /]*>.*?<\/h1>/g; +html = html.replace(h1, ""); +--- + + diff --git a/site/src/content/docs/contribute/contributor-guide.mdx b/site/src/content/docs/contribute/contributor-guide.mdx index f263929b06..02277d13d4 100644 --- a/site/src/content/docs/contribute/contributor-guide.mdx +++ b/site/src/content/docs/contribute/contributor-guide.mdx @@ -1,7 +1,12 @@ --- title: Contributing Guide +# MDX is unable to render TOC from imported markdown file +tableOfContents: false --- -import Contributing from '../../../../../CONTRIBUTING.md'; +import StripH1 from "@components/StripH1.astro"; +import Contributing from "../../../../../.github/CONTRIBUTING.md"; + + diff --git a/site/src/content/docs/contribute/testing.mdx b/site/src/content/docs/contribute/testing.mdx index 776869a058..1fa09ec997 100644 --- a/site/src/content/docs/contribute/testing.mdx +++ b/site/src/content/docs/contribute/testing.mdx @@ -2,17 +2,17 @@ title: Running Tests --- -Currently, we primarily test Zarf through a series of end-to-end tests located in the [e2e directory](https://github.com/defenseunicorns/zarf/tree/main/src/test/e2e) of the project. This directory houses all of the e2e tests that we use to verify Zarf's functionality in an environment that replicates a live setting. The tests in this directory undergo automatic execution against several K8s distros whenever a pull request is created or updated. Through this testing, we ensure that Zarf performs consistently across a range of K8s environments, ensuring its reliability for users. +Currently, we primarily test Zarf through a series of [end-to-end tests](https://github.com/defenseunicorns/zarf/tree/main/src/test/e2e). These tests are called in the `test-*.yml` workflows and undergo automatic execution against several K8s distros whenever a pull request is created or updated. -In addition, Zarf undergoes a series of unit tests for specific functions where edge cases prove difficult to cover through end-to-end testing alone. You can locate these tests in the [src/pkg directory](https://github.com/defenseunicorns/zarf/tree/main/src/pkg), where they are identified by `*_test.go` files. +In addition, Zarf implements unit tests for specific functions where edge cases prove difficult to cover through end-to-end testing alone. Unit tests follow standard Go convention and are `*_test.go` files. ## Dependencies To run the end-to-end tests locally, you must meet the same prerequisites as those required for building and running Zarf, which include: -1. GoLang >= 1.21.x. -2. Make. -3. Any clean K8s cluster (local or remote) or Linux with sudo if you want to use the Zarf-installed K3s cluster. +1. GoLang >= 1.21.x +2. Make +3. Any clean K8s cluster (local or remote) or Linux with `root` if you want to use the Zarf-installed K3s cluster ### CLI End-to-End Tests diff --git a/site/src/content/docs/faq.mdx b/site/src/content/docs/faq.mdx index 008a2ab650..024399c23e 100644 --- a/site/src/content/docs/faq.mdx +++ b/site/src/content/docs/faq.mdx @@ -38,9 +38,9 @@ The Agent does not need to create any secrets in the cluster. Instead, during `z Resources can be excluded at the namespace or resources level by adding the `zarf.dev/agent: ignore` label. -## What happens to resources that exist in the cluster before [`zarf init`](/commands/zarf_init/)? +## What happens to resources that exist in the cluster before `zarf init`? -During the `zarf init` operation, the Zarf Agent will patch any existing namespaces with the `zarf.dev/agent: ignore` label to prevent the Agent from modifying any resources in that namespace. This is done because there is no way to guarantee the images used by pods in existing namespaces are available in the Zarf Registry. +During the [`zarf init`](/commands/zarf_init) operation, the Zarf Agent will patch any existing namespaces with the `zarf.dev/agent: ignore` label to prevent the Agent from modifying any resources in that namespace. This is done because there is no way to guarantee the images used by pods in existing namespaces are available in the Zarf Registry. If you would like to adopt pre-existing resources into a Zarf deployment you can use the `--adopt-existing-resources` flag on [`zarf package deploy`](/commands/zarf_package_deploy/) to adopt those resources into the Helm Releases that Zarf manages (including namespaces). This will add the requisite annotations and labels to those resources and drop the `zarf.dev/agent: ignore` label from any namespaces specified by those resources. diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx index a0b2e13aa6..ebceb10ace 100644 --- a/site/src/content/docs/index.mdx +++ b/site/src/content/docs/index.mdx @@ -1,5 +1,6 @@ --- title: What is Zarf? +description: Zarf is a free and open-source tool that enables declarative creation & distribution of software into air-gapped/constrained/standalone environments. tableOfContents: false --- diff --git a/site/src/content/docs/ref/index.mdx b/site/src/content/docs/ref/index.mdx index 23ada376e5..b1320f9c9d 100644 --- a/site/src/content/docs/ref/index.mdx +++ b/site/src/content/docs/ref/index.mdx @@ -18,11 +18,15 @@ Zarf provides a suite of commands that streamline the creation, deployment, and As previously mentioned, Zarf was specifically designed to facilitate the deployment of applications in disconnected environments with ease. As a result, the most commonly utilized commands are `zarf init`, `zarf package create`, and `zarf package deploy`. Detailed information on all commands can be found in the [CLI Commands](/commands/zarf) section. However, brief descriptions of the most frequently used commands are provided below. It's worth noting that these three commands are closely linked to what we refer to as a "Zarf Package". Additional information on Zarf Packages can be found on the [Zarf Packages](/ref/packages/) page. -### [`zarf init`](/commands/zarf_init) +### Init + +> [`zarf init`](/commands/zarf_init/) Used to configure a K8s cluster in preparation for the deployment of future Zarf Packages. The init command uses a specialized 'init' package to operate which may be located in your current working directory, the directory where the Zarf CLI binary is located, or downloaded from the GitHub Container Registry during command execution. For further details regarding the init-package, please refer to the [init-package](/ref/init-package/) page. -### [`zarf package create`](/commands/zarf_package_create) +### Create + +> [`zarf package create`](/commands/zarf_package_create/) Used to create a Zarf package from a `zarf.yaml` package definition. This command will pull all of the defined resources into a single package you can take with you to a disconnected environment. You can learn more about creating Zarf packages on the [Create a Zarf Package](/ref/create/) page. @@ -32,7 +36,9 @@ When developing packages you may find the sub-commands under `zarf dev` useful t ::: -### [`zarf package deploy`](/commands/zarf_package_deploy) +### Deploy + +> [`zarf package deploy`](/commands/zarf_package_deploy/) Used to deploy an already created Zarf package onto a machine, typically to a K8s cluster. Generally, it is presumed that the `zarf init` command has already been executed on the target machine, however, there are a few exceptional cases where this assumption does not apply. You can learn more about deploying Zarf packages on the [Deploy a Zarf Package](/ref/deploy/) page.