docs: update contributing and pre-commit

CONTRIBUTING.md → .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:
 

.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

.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:

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:

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`.
-  
+
   :::

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:

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[^>]*>.*?<\/h1>/g;
+html = html.replace(h1, "");
+---
+
+<Fragment set:html={html} />

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";
 
+<StripH1>
 <Contributing />
+</StripH1>

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
 

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.
 

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
 ---
 

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.