From b1bf72309184bb22fea5476a778fadd3a76b3903 Mon Sep 17 00:00:00 2001 From: Anna Kapuscinska Date: Wed, 29 May 2024 18:03:39 +0100 Subject: [PATCH 1/2] docs: Add "making changes" instructions for specific code areas Adding initial contribution guides for specific areas. Mainly instructions for generating files, some of which I moved from the "development setup" page. Signed-off-by: Anna Kapuscinska --- .../contribution-guide/development-setup.md | 35 ------------ .../docs/contribution-guide/making-changes.md | 57 ++++++++++++++++++- 2 files changed, 56 insertions(+), 36 deletions(-) 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..ceb45808d8e 100644 --- a/docs/content/en/docs/contribution-guide/making-changes.md +++ b/docs/content/en/docs/contribution-guide/making-changes.md @@ -48,8 +48,63 @@ description: "Learn how to make your first changes to the project" 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/). - From dcf001015e8c9230b5558b9b867d847ba213baab Mon Sep 17 00:00:00 2001 From: Anna Kapuscinska Date: Wed, 29 May 2024 21:32:50 +0100 Subject: [PATCH 2/2] docs: Refactor Contribution Guide Tetragon contribution guide consists of a few docs pages and a PR template, each one containing a list of steps. Many of the steps (e.g. testing or commit message guidelines) are duplicated between lists. This is hard to follow and hard to maintain (different pages can easily become conflicting). I refactored the contribution guide so that it's (hopefully) easier to follow: * "Making changes" page has simplified build & test instructions. I added a step about code generation and removed a step about commits. * "Submitting a pull request" page covers everything related to commits (in a dedicated section) and basic info about pull request review. I added a link to the main contribution guide and removed other steps, which were duplicating the previous guides * Checklist in the PR template is simplified and links to docs pages. Signed-off-by: Anna Kapuscinska --- .github/pull_request_template.md | 14 ++-- .../docs/contribution-guide/making-changes.md | 29 +++---- .../submitting-a-pull-request.md | 78 ++++++++++--------- 3 files changed, 56 insertions(+), 65 deletions(-) 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/making-changes.md b/docs/content/en/docs/contribution-guide/making-changes.md index ceb45808d8e..c0d60593084 100644 --- a/docs/content/en/docs/contribution-guide/making-changes.md +++ b/docs/content/en/docs/contribution-guide/making-changes.md @@ -24,29 +24,20 @@ 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. Build Tetragon with your changes included. +7. Follow [Submitting a pull request](/docs/contribution-guide/submitting-a-pull-request) guide to commit your changes + and open a pull request. ## Making changes to documentation 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`.