diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2ade8e03245..cc50380889c 100644 --- a/.github/pull_request_template.md +++ b/.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. diff --git a/docs/content/en/docs/contribution-guide/development-setup.md b/docs/content/en/docs/contribution-guide/development-setup.md index 5f3f96ebf99..020a6d788d0 100644 --- a/docs/content/en/docs/contribution-guide/development-setup.md +++ b/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) diff --git a/docs/content/en/docs/contribution-guide/making-changes.md b/docs/content/en/docs/contribution-guide/making-changes.md index 86d15e0ed8d..c0d60593084 100644 --- a/docs/content/en/docs/contribution-guide/making-changes.md +++ b/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/). - diff --git a/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md b/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md index 33dfdce34af..61b25e1291a 100644 --- a/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md +++ b/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 +``` - Signed-off-by: Djalal Harouni - ``` +## 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`.