docs: improve contribution guide and add a running test page

Signed-off-by: Mahe Tardy <[email protected]>

docs/content/en/docs/contribution-guide/_index.md

@@ -5,40 +5,50 @@ description: >
   How to contribute to the project
 ---
 
+Welcome to Tetragon :) !
+
 We're happy you're interested in contributing to the Tetragon project.
 
 This section of the Tetragon documentation will help you make sure you
 have an environment capable of testing changes to the Tetragon source code,
 and that you understand the workflow of getting these changes reviewed and
 merged upstream.
 
-### Clone and provision an environment
+## Clone and provision an environment
 
 1. Make sure you have a [GitHub account](https://github.com/join).
 
-2. Fork the Tetragon repository to your GitHub user or organization.
-
-3. Turn off GitHub actions for your fork as described in the
-   [GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>).
+2. [Fork the Tetragon repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+   to your GitHub user or organization. The repository is available under
+   [github.com/cilium/tetragon](https://github.com/cilium/tetragon).
 
-   This is recommended to avoid unnecessary CI notification failures on the fork.
+3. (Optional) [Turn off GitHub actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#about-github-actions-permissions-for-your-repository)
+   for your fork. This is recommended to avoid unnecessary CI notification
+   failures on the fork.
 
-4. Clone your `${YOUR_GITHUB_USERNAME_OR_ORG}/tetragon` fork into your
-   `GOPATH`, and set up the base repository as `upstream` remote:
+4. [Clone your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+   and set up the base repository as `upstream` remote:
 
    ```shell
-   mkdir -p "${GOPATH}/src/github.com/cilium"
-   cd "${GOPATH}/src/github.com/cilium"
    git clone https://github.com/${YOUR_GITHUB_USERNAME_OR_ORG}/tetragon.git
    cd tetragon
    git remote add upstream https://github.com/cilium/tetragon.git
    ```
 
-5. Prepare your [Development setup](/docs/contribution-guide/development-setup),
-   see section below.
+5. Prepare your [development setup]({{< ref "/docs/contribution-guide/development-setup" >}}).
+
+6. Check out GitHub [good first issues](https://github.com/cilium/tetragon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+   to find something to work on. If this is your first Tetragon issue, try to
+   start with something small that you think you can do without too much
+   external help. Also avoid assigning too many issues to yourself (see [Don't
+   Lick the Cookie!](https://www.redhat.com/en/blog/dont-lick-cookie)).
+
+7. Follow the steps in [making changes]({{< ref "/docs/contribution-guide/making-changes" >}})
+   to start contributing.
 
-6. Check the GitHub issues for [good tasks to get
-   started](https://github.com/cilium/tetragon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
+8. Learn how to [run the tests]({{< ref "/docs/contribution-guide/running-tests" >}}).
 
-7. Follow the steps in [Making changes](/docs/contribution-guide/making-changes) to start contributing. Welcome :)!
+9. Learn how to [submit a pull request]({{< ref "/docs/contribution-guide/submitting-a-pull-request" >}})
+   to the project.
 
+10. Please accept our gratitude for taking the time to improve Tetragon! :)

docs/content/en/docs/contribution-guide/development-setup.md

@@ -4,18 +4,22 @@ weight: 1
 description: "This will help you getting started with your development setup to build Tetragon"
 ---
 
-### Building and Running Tetragon
+## Building and running Tetragon
 
 For local development, you will likely want to build and run bare-metal Tetragon.
 
-Requirements:
-- go 1.18
-- GNU make
-- A running docker service
-- `libcap` and `libelf` (in Debian systems, e.g., install `libelf-dev` and
-  `libcap-dev`)
+### Requirements
 
-You can build Tetragon as follows:
+- A Go toolchain with the [version specified in the main `go.mod`](https://github.com/cilium/tetragon/blob/main/go.mod#L4);
+- GNU make;
+- A running Docker service (you can use Podman as well);
+- For building tests, `libcap` and `libelf` (in Debian systems, e.g., install
+  `libelf-dev` and `libcap-dev`).
+
+### Build everything
+
+You can build most Tetragon targets as follows (this can take time as it builds
+all the targets needed for testing, see [minimal build](#minimal-build)):
 
 ```shell
 make
@@ -34,10 +38,19 @@ To build using the local clang, you can use:
 CONTAINER_ENGINE='sudo podman' LOCAL_CLANG=1 LOCAL_CLANG_FORMAT=1 make
 ```
 
-See
-[Dockerfile.clang](https://github.com/cilium/tetragon/blob/main/Dockerfile.clang)
+See [Dockerfile.clang](https://github.com/cilium/tetragon/blob/main/Dockerfile.clang)
 for the minimal required version of `clang`.
 
+### Minimal build
+
+To build the `tetragon` binary, the BPF programs and the `tetra` CLI binary you
+can use:
+```shell
+make tetragon tetragon-bpf tetra
+```
+
+### Run Tetragon
+
 You should now have a `./tetragon` binary, which can be run as follows:
 
 ```shell
@@ -52,9 +65,10 @@ Notes:
 2. If Tetragon fails with an error `"BTF discovery: candidate btf file does not
    exist"`, then make sure that your kernel support [BTF](#btf-requirement),
    otherwise place a BTF file where Tetragon can read it and specify its path
-   with the `--btf` flag.
+   with the `--btf` flag. See more about that
+   [in the FAQ]({{< ref "/docs/faq/#tetragon-failed-to-start-complaining-about-a-missing-btf-file" >}}).
 
-### Running Code Generation
+## Running code generation
 
 Tetragon uses code generation based on protoc to generate large amounts of
 boilerplate code based on our protobuf API. We similarly use automatic
@@ -76,7 +90,20 @@ Finally, should you wish to modify any of the resulting codegen files (ending
 in` .pb.go`), do not modify them directly. Instead, you can edit the files in
 `cmd/protoc-gen-go-tetragon` and then re-run `make codegen`.
 
-### Building and running a Docker image
+## Running vendor
+
+Tetragon uses multiple modules to separate the main module, from `api` from
+`pkg/k8s`. Depending on your changes you might need to vendor those changes,
+you can use:
+
+```shell
+make vendor
+```
+
+Note that the `make codegen` and `make generate` commands already vendor
+changes automatically.
+
+## Building and running a Docker image
 
 The base kernel should support [BTF](https://github.com/cilium/tetragon#btf-requirement)
 or a BTF file should be bind mounted on top of `/var/lib/tetragon/btf` inside
@@ -103,14 +130,14 @@ docker exec -it tetragon \
    bash -c "/usr/bin/tetra getevents -o compact"
 ```
 
-### Building and running as a systemd service
+## Building and running as a systemd service
 
 To build Tetragon tarball:
 ```shell
 make tarball
 ```
 
-### Running Tetragon in kind
+## Running Tetragon in kind
 
 This command will setup tetragon, kind cluster and install tetragon in it. Ensure docker, kind, kubectl, and helm are installed.
 
@@ -124,9 +151,9 @@ Verify that Tetragon is installed by running:
 kubectl get pods -n kube-system
 ```
 
-### Local Development in Vagrant Box
+## Local Development in Vagrant Box
 
-If you are on a Mac, use Vagrant to create a dev VM:
+If you are on an intel Mac, use Vagrant to create a dev VM:
 
 ```shell
 vagrant up
@@ -138,7 +165,7 @@ If you are getting an error, you can try to run `sudo launchctl load
 /Library/LaunchDaemons/org.virtualbox.startup.plist` (from [a Stackoverflow
 answer](https://stackoverflow.com/questions/18149546/macos-vagrant-up-failed-dev-vboxnetctl-no-such-file-or-directory)).
 
-### What's next
+## What's next
 
 - See how to [make your first changes](/docs/contribution-guide/making-changes).
 

docs/content/en/docs/contribution-guide/making-changes.md

@@ -13,7 +13,7 @@ description: "Learn how to make your first changes to the project"
    ```
 
    For further reference read
-   [github syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
+   [GitHub syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
    documentation.
 
 2. Create a PR branch with a descriptive name, branching from main:
@@ -33,7 +33,7 @@ description: "Learn how to make your first changes to the project"
      instructions should be code comments instead of statements in the commit
      description.
    - For submitting PRs, all commits need to be signed off `(git commit -s)`.
-     See the section [Developer's Certificate of Origin](/docs/contribution-guide/developer-certificate-of-origin/)
+     See the section [Developer's Certificate of Origin]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}})
 
 5. Make sure your changes meet the following criteria:
 
@@ -48,7 +48,7 @@ description: "Learn how to make your first changes to the project"
 
 7. Build Tetragon with your changes included.
 
-### What's next
+## What's next
 
 - See how to [run the tests of the project](/docs/contribution-guide/running-tests/).
 - See how to [submit your first pull request](/docs/contribution-guide/submitting-a-pull-request/).

docs/content/en/docs/contribution-guide/running-tests.md

@@ -1,13 +1,66 @@
 ---
 title: "Running tests"
 weight: 3
-manualLink: "https://github.com/cilium/tetragon/tree/main/tests/vmtests"
-manualLinkTarget: "_blank"
 description: "Learn how to run the tests of the project"
 ---
 
-See https://github.com/cilium/tetragon/tree/main/tests/vmtests.
+Tetragon has several types of tests:
+- Go tests, composed of unit tests for userspace Go code and Go and BPF code.
+- BPF unit tests, testing specifing BPF functions.
+- E2E tests, for end-to-end tests, installing Tetragon in Kubernetes clusters
+  and checking for specific features.
 
-### What's next
+Those tests are running in the Tetragon CI on various kernels[^1] and various
+architectures (amd64 and arm64).
+
+[^1]: For the detailed list, search for `jobs.test.strategy.matrix.kernel` in
+[github.com/cilium/tetragon/.github/workflows/vmtests.yml](https://github.com/cilium/tetragon/blob/main/.github/workflows/vmtests.yml)
+
+## Go tests
+
+To run the Go tests locally, you can use:
+
+```shell
+make test
+```
+
+Use `EXTRA_TESTFLAGS` to add flags to the `go test` command.
+
+### Test specific kernels
+
+To run the Go tests on various kernel versions, we use vmtests with
+[cilium/little-vm-helper](https://github.com/cilium/little-vm-helper) in the
+CI, you can also use it locally for testing specific kernels. See documentation
+[github.com/cilium/tetragon/tests/vmtests](https://github.com/cilium/tetragon/tree/main/tests/vmtests).
+
+## BPF unit tests
+
+To run BPF unit tests, you can use:
+
+```shell
+make bpf-test
+```
+
+Those tests can be found under
+[github.com/cilium/tetragon/bpf/tests](https://github.com/cilium/tetragon/tree/main/bpf/tests).
+The framework uses Go tests with `cilium/ebpf` to run those tests, you can use
+`BPFGOTESTFLAGS` to add `go test` flags, like `make BPFGOTESTFLAGS="-v"
+bpf-test`.
+
+## E2E tests
+
+To run E2E tests, you can use:
+
+```shell
+make e2e-test
+```
+
+This will build the Tetragon image and use the e2e framework to create a kind
+cluster, install Tetragon and run the tests. To not rebuild the image before
+running the test, use `E2E_BUILD_IMAGES=0`. You can use `EXTRA_TESTFLAGS` to
+add flags to the `go test` command.
+
+
+## What's next
 
 - See how to [submit your first pull request](/docs/contribution-guide/submitting-a-pull-request/).

docs/content/en/docs/contribution-guide/submitting-a-pull-request.md

@@ -53,7 +53,7 @@ requirements have been met:
    Note: Make sure to include a blank line in between commit title and commit description.
 
 5. All commits are signed off. See the section [Developer’s Certificate of
-   Origin](/docs/contribution-guide/developer-certificate-of-origin/).
+   Origin]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}}).
 
-6. All important steps in [Making changes](/docs/contribution-guide/making-changes/) have been followed.
+6. All important steps in [Making changes]({{< ref "/docs/contribution-guide/making-changes" >}}) have been followed.