docs: Improve contribution guide & PR template

.github/pull_request_template.md

@@ -1,14 +1,10 @@
-Please ensure your pull request adheres to the following guidelines:
+Thanks for contributing! Please ensure your pull request adheres to the following guidelines:
 
-- [ ] For first time contributors, read [Submitting a pull request](https://tetragon.io/docs/contribution-guide/submitting-a-pull-request/).
-- [ ] All code is covered by unit and/or end-to-end tests tests where feasible.
-- [ ] All commits contain a well written commit message including a title,
-      description and a `Fixes: #XXX` line if the commit addresses a particular
-      GitHub issue.
-- [ ] All commits are signed off. See the section [Developer’s Certificate of Origin](https://docs.cilium.io/en/stable/contributing/development/contributing_guide/#dev-coo)
+- [ ] All commits contain a well written commit message and are signed-off (see [Submitting a pull request](https://tetragon.io/docs/contribution-guide/submitting-a-pull-request/)).
+- [ ] All code is covered by unit and/or end-to-end tests where feasible.
+- [ ] All generated files are updated if needed (see [Making changes](https://tetragon.io/docs/contribution-guide/making-changes/)).
 - [ ] Provide a title or release-note blurb suitable for the release notes.
-- [ ] Are you a user of Tetragon? Please add yourself to the [Users doc](https://github.com/cilium/cilium/blob/main/USERS.md) in the Cilium repository. 
-- [ ] Thanks for contributing!
+- [ ] Are you a user of Tetragon? Please add yourself to the [Users doc](https://github.com/cilium/cilium/blob/main/USERS.md) in the Cilium repository.
 
 <!-- Description of change -->
 

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

@@ -68,41 +68,6 @@ Notes:
    with the `--btf` flag. See more about that
    [in the FAQ]({{< ref "/docs/installation/faq#tetragon-failed-to-start-complaining-about-a-missing-btf-file" >}}).
 
-## 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
-generation to maintain our k8s CRDs. Whenever you make changes to these files,
-you will be required to re-run code generation before your PR can be accepted.
-
-To run codegen from protoc, run the following command from the root of the
-repository:
-```shell
-make protogen
-```
-
-And to run k8s CRD generation, run the following command from the root of the repository:
-```shell
-make crds
-```
-
-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 protogen`.
-
-## 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 protogen` and `make crds` commands already vendor
-changes automatically.
-
 ## Building and running a Docker image
 
 The base kernel should support [BTF](https://github.com/cilium/tetragon#btf-requirement)

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

@@ -24,32 +24,78 @@ description: "Learn how to make your first changes to the project"
 
 3. Make the changes you want.
 
-4. Separate the changes into logical commits.
+4. Test your changes. Follow [Development setup](/contribution-guide/development-setup) and
+   [Running tests](/docs/contribution-guide/running-tests) guides to build and test Tetragon.
 
-   - Describe the changes in the commit messages. Focus on answering the
-     question why the change is required and document anything that might be
-     unexpected.
-   - If any description is required to understand your code changes, then those
-     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]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}})
+   - Make sure that all new code is covered by unit and/or end-to-end tests where feasible.
+   - Run Tetragon locally to validate everything works as expected.
+   - If adding/extending tests is not required, mention in the commit message what existing test covers the new code
+     or how you validated the change.
 
-5. Make sure your changes meet the following criteria:
+5. Run code/docs generation commands if needed (see the sections below for specific code areas).
 
-   - New code is covered by Integration Testing.
-   - End to end integration / runtime tests have been extended or added. If not
-     required, mention in the commit message what existing test covers the new
-     code.
-   - Follow-up commits are squashed together nicely. Commits should separate
-     logical chunks of code and not represent a chronological list of changes.
+6. Run `git diff --check` to catch obvious white space violations.
 
-6. Run `git diff --check` to catch obvious white space violations
+7. Follow [Submitting a pull request](/docs/contribution-guide/submitting-a-pull-request) guide to commit your changes
+   and open a pull request.
 
-7. Build Tetragon with your changes included.
+## Making changes to documentation
+
+To improve Tetragon documentation ([https://tetragon.io/](https://tetragon.io/)), please follow the
+[documentation contribution guide](/docs/contribution-guide/documentation).
+
+## Adding dependencies
+
+Tetragon vendors Go dependencies. If you add a new Go dependency (`go.mod`), run:
+
+```shell
+make vendor
+```
+
+Most dependencies are updated automatically using Renovate. If this is not the desired behavior, you will need to
+update the Renovate configuration (`.github/renovate.json5`).
+
+## Making changes to protobuf API
+
+Tetragon contains a protobuf API and uses code generation based on protoc to generate large amounts of boilerplate
+code. Whenever you make changes to these files (`api/`) you need to run code generation:
+
+```shell
+make protogen
+```
+
+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 `tools/protoc-gen-go-tetragon/` and then re-run `make protogen`.
+
+## Making changes to CRDs
+
+Kubernetes Custom Resource Definitions (CRDs) are defined using Kubebuilder framework and shipped with generated Go
+client and helpers code. They are also included in the Helm chart for easy installation. Whenever you make changes to
+these files (`pkg/k8s/`), you need to run code generation:
+
+```shell
+make crds
+make -C install/kubernetes tetragon/crds-yaml
+```
+
+## Making changes to Helm chart
+
+If you make changes to the Helm values (`install/kubernetes/tetragon/values.yaml`), you need to update the generated
+Helm values reference:
+
+```shell
+make -C install/kubernetes docs
+```
+
+## Making changes to Prometheus metrics
+
+If you add, change or delete metrics, you need to update the generated metrics reference:
+
+```shell
+make metrics-docs
+```
 
 ## 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/submitting-a-pull-request.md

@@ -4,66 +4,70 @@ weight: 5
 description: "Learn how to submit a pull request to the project"
 ---
 
-### Submitting a pull request
+{{< note >}}
+This guide assumes that you have already made and tested changes you want to contribute. If you have not,
+please follow the steps from the [Contribution Guide]({{< ref "/docs/contribution-guide#guide-for-code-and-docs-contribution" >}}).
+{{< /note >}}
 
-Contributions must be submitted in the form of pull requests against the
-upstream GitHub repository at https://github.com/cilium/tetragon.
-
-1. Fork the Tetragon repository.
+## Commit changes
 
-2. Push your changes to the topic branch in your fork of the repository.
+Save your changes in one or more commits. Commits should separate logical chunks of code and not represent
+a chronological list of changes. Ideally, each commit compiles and is functional on its own to allow for bisecting.
 
-3. Submit a pull request on https://github.com/cilium/tetragon.
+If in code review you are requested to make changes, squash the follow-up changes into the existing commits.
+If you are not comfortable with Git yet (in particular with `git rebase`), refer to the [GitHub documentation](https://docs.github.com/en/get-started/using-git/using-git-rebase-on-the-command-line).
 
-Before hitting the submit button, please make sure that the following
-requirements have been met:
+### Write a commit message
 
-1. Each commit compiles and is functional on its own to allow for bisecting of
-   commits.
+All commits must contain a well-written commit message:
 
-2. All code is covered by unit and/or runtime tests where feasible.
+1. Write a title, **no longer than 75 characters**. If the commit covers one specific area, start the title with
+   a prefix like `helm:` or `metrics:`.
+2. Describe the changes in the commit description. Focus on answering the question why the change is required and
+   document anything that might be unexpected. If any explanation is required to understand your code, then it should
+   be written in the code comments instead of the commit description.
+3. Add a `Fixes: #XXX` line if the commit addresses a particular GitHub issue identified by its number. Note that the
+   GitHub issue will be automatically closed when the commit is merged.
+4. All commits **must be signed off** `(git commit -s)`.
+   See the section [Developer's Certificate of Origin]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}}).
 
-3. All changes have been tested and checked for regressions by running the
-   existing testsuite against your changes.
+### Example commit message
 
-4. All commits contain a well written commit description including a title,
-   description and a `Fixes: #XXX` line if the commit addresses a particular
-   GitHub issue identified by its number. Note that the GitHub issue will be
-   automatically closed when the commit is merged.
+```
+doc: add contribution guideline and how to submit pull requests
 
-   ```
-   doc: add contribution guideline and how to submit pull requests
+Tetragon Open Source project was just released and it does not include
+default contributing guidelines.
 
-   Tetragon Open Source project was just released and it does not include
-   default contributing guidelines.
+This patch fixes this by adding:
 
-   This patch fixes this by adding:
+1. CONTRIBUTING.md file in the root directory as suggested by github documentation: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
 
-   1. CONTRIBUTING.md file in the root directory as suggested by github documentation: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
+2. Development guide under docs directory with a section on how to submit pull requests.
 
-   2. Development guide under docs directory with a section on how to submit pull requests.
+3. Moves the DEVELOP.md file from root directory to the `docs/contributing/development/` one.
 
-   3. Moves the DEVELOP.md file from root directory to the `docs/contributing/development/` one.
+Fixes: #33
 
-   Fixes: #33
+Signed-off-by: Djalal Harouni <[email protected]>
+```
 
-   Signed-off-by: Djalal Harouni <[email protected]>
-   ```
+## Submit a pull request
 
-   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]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}}).
+Contributions must be submitted in the form of pull requests against the
+upstream GitHub repository at https://github.com/cilium/tetragon.
 
-6. All important steps in [Making changes]({{< ref "/docs/contribution-guide/making-changes" >}}) have been followed.
+Please follow the checklist in the pull request template and write anything that reviewers should be aware of in the
+pull request description. After you create a pull request, a reviewer will be automatically assigned. They will provide
+feedback, add relevant labels and run the CI workflows if needed.
 
-### Frequently Asked Questions
+## Frequently Asked Questions
 
-#### CI is complaining about Go module vendoring, what do I do?
+### CI is complaining about Go module vendoring, what do I do?
 
 You can run `make vendor` then add and commit your changes.
 
-#### CI is complaining about a missing "signed-off-by" line. What do I do?
+### CI is complaining about a missing "signed-off-by" line. What do I do?
 
 You need to add a signed-off-by line to your commit messages. The easiest way
 to do this is with `git fetch origin/main && git rebase --signoff origin/main`.