docs: split CONTRIBUTING.md into separate pages

Split out and update CONTRIBUTING.md so it is part of the ebpf-go.dev
documentation.

Signed-off-by: Lorenz Bauer <lmb@isovalent.com>

CODEOWNERS

@@ -0,0 +1 @@
+* @cilium/ebpf-lib-maintainers

README.md

@@ -16,7 +16,7 @@ ecosystem.
 A small collection of Go and eBPF programs that serve as examples for building
 your own tools can be found under [examples/](examples/).
 
-[Contributions](CONTRIBUTING.md) are highly encouraged, as they highlight certain use cases of
+[Contributions](https://ebpf-go.dev/contributing) are highly encouraged, as they highlight certain use cases of
 eBPF and the library, and help shape the future of the project.
 
 ## Getting Help
@@ -62,17 +62,6 @@ This library includes the following packages:
 * Linux >= 4.9. CI is run against kernel.org LTS releases. 4.4 should work but is
   not tested against.
 
-## Regenerating Testdata
-
-Run `make` in the root of this repository to rebuild testdata in all
-subpackages. This requires Docker, as it relies on a standardized build
-environment to keep the build output stable.
-
-It is possible to regenerate data using Podman by overriding the `CONTAINER_*`
-variables: `CONTAINER_ENGINE=podman CONTAINER_RUN_ARGS= make`.
-
-The toolchain image build files are kept in [testdata/docker/](testdata/docker/).
-
 ## License
 
 MIT

ARCHITECTURE.md → docs/ebpf/contributing/architecture.md

@@ -1,6 +1,12 @@
 Architecture of the library
 ===
 
+The bulk of the functionality of the library split across the `ebpf`, `btf` and
+`link` packages.
+Below is a diagram how the most important types relate to each other.
+The graph is in dependecy order, so an arrow from `Links` to `Map` can be read
+as "Link depends on Map".
+
 ```mermaid
 graph RL
     Program --> ProgramSpec --> ELF
@@ -25,10 +31,10 @@ an ELF file which contains program byte code (aka BPF), but also metadata for
 maps used by the program. The metadata follows the conventions set by libbpf
 shipped with the kernel. Certain ELF sections have special meaning
 and contain structures defined by libbpf. Newer versions of clang emit
-additional metadata in [BPF Type Format](#BTF).
+additional metadata in [BPF Type Format](../btf/index.md).
 
 The library aims to be compatible with libbpf so that moving from a C toolchain
-to a Go one creates little friction. To that end, the [ELF reader](elf_reader.go)
+to a Go one creates little friction. To that end, the ELF reader
 is tested against the Linux selftests and avoids introducing custom behaviour
 if possible.
 
@@ -37,7 +43,7 @@ all of the information contained in the ELF in a form that is easy to work with
 in Go. The returned `CollectionSpec` should be deterministic: reading the same ELF
 file on different systems must produce the same output.
 As a corollary, any changes that depend on the runtime environment like the
-current kernel version must happen when creating [Objects](#Objects).
+current kernel version must happen when creating [Objects](#objects).
 
 Specifications
 ---
@@ -50,7 +56,7 @@ objects and contain everything necessary to execute the relevant `bpf(2)`
 syscalls. They refer to `btf.Spec` for type information such as `Map` key and
 value types.
 
-The [asm](asm/) package provides an assembler that can be used to generate
+The {{ godoc("asm") }} package provides an assembler that can be used to generate
 `ProgramSpec` on the fly.
 
 Objects

docs/ebpf/contributing/index.md

@@ -0,0 +1,94 @@
+# How to contribute
+
+Development happens on [GitHub](https://github.com/cilium/ebpf) and contributions in
+all forms are welcome. Please take a look at [the architecture](architecture.md) to get
+a better understanding of the high-level goals.
+
+## Running the tests
+
+Many of the tests require privileges to set resource limits and load eBPF code.
+The easiest way to obtain these is to run the tests with `sudo`.
+
+To test the current package with your local kernel you can simply run:
+```
+go test -exec sudo ./...
+```
+
+To test the current package with a different kernel version you can use the [run-tests.sh] script.
+It requires [virtme] and qemu to be installed.
+Unfortunately virtme is not well maintained at the moment, so we recommend installing
+a known working version:
+
+```shell-session
+pip3 install https://github.com/amluto/virtme/archive/beb85146cd91de37ae455eccb6ab67c393e6e290.zip
+```
+
+Once you have the dependencies you can run all tests on a different kernel:
+
+```shell-session
+./run-tests.sh 5.4
+```
+
+Or run a subset of tests:
+
+```shell-session
+./run-tests.sh 5.4 -run TCX ./link
+```
+
+## Regenerating testdata and source code
+
+The library includes some binary artifacts which are used for tests and some
+generated source code. Run `make` in the root of the repository to start
+this process.
+
+```shell-session
+make
+```
+
+This requires Docker, as it relies on a standardized build
+environment to keep the build output stable.
+It is possible to regenerate data using Podman by overriding the `CONTAINER_*`
+variables:
+
+```shell-session
+make CONTAINER_ENGINE=podman CONTAINER_RUN_ARGS=
+```
+
+### Updating kernel dependencies
+
+Syscall bindings and some parameters required to parse ELF sections are derived
+from upstream kernel versions. You can update them to the latest version by:
+
+1. Adjusting the `KERNEL_VERSION` variable in `Makefile`
+2. Running
+    ```shell-session
+    make update-kernel-deps
+    ```
+3. [Regenerating testdata and source code](#regenerating-testdata-and-source-code)
+
+## Project permissions
+
+If you'd like to contribute to the library more regularly, one of the
+[maintainers][ebpf-lib-maintainers] can add you to the appropriate team or mark
+you as a code owner. Just create an issue in the repository.
+
+* [ebpf-go-contributors]
+    * Have ["Triage"][permissions] role
+    * May be asked to review certain parts of code
+    * May be asked to help with certain issues
+* [ebpf-go-reviewers]
+    * Have ["Write"][permissions] role
+    * Can re-run failed CI tasks
+    * Can't merge to protected branches
+    * Can't create releases
+    * May be asked to become CODEOWNERS
+* [ebpf-lib-maintainers]
+    * Have ["Admin"][permissions] role
+    * CODEOWNERS of last resort
+
+[virtme]: https://github.com/amluto/virtme
+[run-tests.sh]: https://github.com/cilium/ebpf/blob/main/run-tests.sh
+[permissions]: https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role
+[ebpf-go-contributors]: https://github.com/orgs/cilium/teams/ebpf-go-contributors/members
+[ebpf-go-reviewers]: https://github.com/orgs/cilium/teams/ebpf-go-reviewers/members
+[ebpf-lib-maintainers]: https://github.com/orgs/cilium/teams/ebpf-lib-maintainers/members

docs/ebpf/contributing/new-feature.md

@@ -0,0 +1,30 @@
+# Adding a new feature
+
+We're very much looking for contributions which flesh out the functionality of
+the library.
+
+1. Have a look at the [architecture](architecture.md) of the library if you
+   haven't already.
+2. [Join](https://ebpf.io/slack) the
+   [#ebpf-go-dev](https://cilium.slack.com/messages/ebpf-go-dev) channel to
+   discuss your requirements and how the feature can be implemented.
+   Alternatively open a new Discussion if you prefer to not use Slack.
+   The most important part is figuring out how much new exported API is necessary.
+   **The less new API is required the easier it will be to land the feature.**
+   Also see [API stability](#api-stability).
+3. (*optional*) Create a draft PR if you want to discuss the implementation or have hit a problem. It's fine if this doesn't compile or contains debug statements.
+4. Create a PR that is ready to merge. This must pass CI and have tests.
+
+## API stability
+
+There is an emphasis on compatibility even though the library doesn't guarantee
+the stability of its API at the moment.
+
+1. If possible, avoid breakage by introducing new API and deprecating the old one
+   at the same time. If an API was deprecated in v0.x it can be removed in v0.x+1.
+   This is especially important if there is no straighforward way to convert
+   from the old to the new API.
+2. Breaking API in a way that causes compilation failures is acceptable but must
+   have good reasons.
+3. Changing the semantics of the API without causing compilation failures is
+   heavily discouraged.

docs/includes/glossary.md

@@ -13,3 +13,4 @@
 *[XDP]: eXpress Data Path, a high-performance eBPF-powered data path. Only has a receive hook.
 *[bpf2go]: Convenience utility to compile eBPF C using clang and generate a Go skeleton.
 *[libbpf]: A library for writing kernel- and user space BPF programs in C, developed by the upstream Linux project.
+*[qemu]: A popular virtual machine manager.

docs/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: "ebpf-go Documentation"
-site_description: Pure-Go library to read, modify and load eBPF programs and attach them to various hooks in the Linux kernel. 
+site_description: Pure-Go library to read, modify and load eBPF programs and attach them to various hooks in the Linux kernel.
 site_author: Cilium Community
 
 # Rendered in header.
@@ -74,6 +74,10 @@ nav:
     - 'Index': bpf2go/index.md
   - 'BTF':
     - btf/index.md
+  - 'Contributing':
+    - contributing/index.md
+    - contributing/architecture.md
+    - contributing/new-feature.md
   - 'Users': users.md
   - 'Go Reference': https://pkg.go.dev/github.com/cilium/ebpf
   - 'GitHub':
@@ -145,7 +149,7 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   # Content tabs for code snippets, checklists, etc.
   - pymdownx.tabbed:
-      alternate_style: true 
+      alternate_style: true
   # Emoji and icons like :fontawesome-brands-golang:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji