Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update contributing and pre-commit #2439

Merged
merged 3 commits into from
Apr 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 19 additions & 16 deletions CONTRIBUTING.md → .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
27 changes: 11 additions & 16 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion examples/big-bang/config/neuvector.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
2 changes: 1 addition & 1 deletion examples/kiwix/zarf.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

:::
2 changes: 1 addition & 1 deletion packages/logging-pgl/connect.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
9 changes: 9 additions & 0 deletions site/src/components/StripH1.astro
Original file line number Diff line number Diff line change
@@ -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} />
7 changes: 6 additions & 1 deletion site/src/content/docs/contribute/contributor-guide.mdx
Original file line number Diff line number Diff line change
@@ -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>
10 changes: 5 additions & 5 deletions site/src/content/docs/contribute/testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions site/src/content/docs/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
1 change: 1 addition & 0 deletions site/src/content/docs/index.mdx
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down
12 changes: 9 additions & 3 deletions site/src/content/docs/ref/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand Down
Loading