Update Contributing docs #4424

ShohamBit · 2024-12-11T17:16:53Z

1. Explain what the PR does

This PR is about #4406

remove and add the documentation to the guidelines
add sections on how to contribute to tracee source code
improve docs on how to build tracee
improve docs on how to build environment

"Replace me with make check-pr output"

2. Explain how to test it

Read the docs and check if its properly align with tracee design

3. Other comments

Close #4406

…ntributing_docs

geyslan

First pass.

docs/contributing/building/building.md

docs/contributing/building/environment.md

docs/contributing/setup-development-machine-with-vagrant.md

docs/contributing/guidelines.md

docs/contributing/building/building.md

rscampos · 2024-12-20T13:02:23Z

First pass

Need to update the result of make help

tracee/docs/contributing/building/building.md

Line 42 in 540c8ce

make help

The difference:

need to add: make tracee-operator and make clean-tracee-operator
need to remove: make test-signatures

rscampos · 2024-12-20T13:20:27Z

docs/contributing/building/building.md

-        -v -o dist/tracee \
-       ./cmd/tracee
+
+9. Build enabling BPF metrics by setting `METRICS=1`.


Shouldn't we also add the following line in the make help?

$ METRICS=1 make ... # build enabling BPF metrics

rscampos · 2024-12-20T14:18:08Z

docs/contributing/kubernetes.md

+    Tracee's Makefile provides convenient targets for setting up MicroK8s:
+
+    ```bash
+    make -f builder/Makefile.k8s help


Some considerations:

maybe would be good to add the help output;

I think we should add some instructions do setup the cluster or point to a link with those instructions;

Please check the manifests and generate, it seems to not be working (maybe we need to open an issue).

@rscampos, I'm having trouble building Tracee with the Kubernetes Makefile. I tried updating the Go version in the Dockerfile and running make from Ubuntu shell, but I'm still hitting errors. Could you offer some guidance?

Which errors? Would you give us a reproducible?

well this is the output of what I run:

computer@computer:~/computer/tracee$ make -f ./builder/Makefile.k8s make -f ./builder/Makefile.k8s build make -f ./builder/Makefile.k8s manifests make -f ./builder/Makefile.k8s generate docker build \ -f builder/Dockerfile.k8s \ -t tracee-k8s:latest \ . [+] Building 2.1s (7/7) FINISHED docker:default => [internal] load build definition from Dockerfile.k8s 0.1s => => transferring dockerfile: 149B 0.0s => [internal] load metadata for docker.io/library/golang:1.22.3 1.6s => [internal] load .dockerignore 0.0s => => transferring context: 153B 0.0s => [1/3] FROM docker.io/library/golang:1.22.3@sha256:f43c6f049f04cbbaeb28f0aad3eea15274a7d0a7899a617d0037aec48d7ab010 0.0s => CACHED [2/3] RUN go install sigs.k8s.io/controller-tools/cmd/[email protected] 0.0s => CACHED [3/3] WORKDIR /tracee 0.0s => exporting to image 0.1s => => exporting layers 0.0s => => writing image sha256:15ac283c15e64fef2cd3c7776787b26a9cfb62cddf1e3fbb5ddb17b0c4630297 0.1s => => naming to docker.io/library/tracee-k8s:latest 0.0s docker run --rm \ -v /home/computer/computer/tracee:/tracee \ tracee-k8s:latest make k8s-manifests controller-gen rbac:roleName=tracee crd webhook paths="./pkg/k8s/..." output:crd:artifacts:config=deploy/helm/tracee/crds output:rbac:artifacts:config=deploy/helm/tracee/templates/ panic: runtime error: invalid memory address or nil pointer dereference [recovered] panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0xa0de6f] goroutine 66 [running]: go/types.(*Checker).handleBailout(0xc0000fc600, 0xc000ec1d40) /usr/local/go/src/go/types/check.go:367 +0x88 panic({0xbc7860?, 0x12b2880?}) /usr/local/go/src/runtime/panic.go:770 +0x132 go/types.(*StdSizes).Sizeof(0x0, {0xdc3678, 0x12bb060}) /usr/local/go/src/go/types/sizes.go:228 +0x30f go/types.(*Config).sizeof(...) /usr/local/go/src/go/types/sizes.go:333 go/types.representableConst.func1({0xdc3678?, 0x12bb060?}) /usr/local/go/src/go/types/const.go:76 +0x9e go/types.representableConst({0xdc9a50, 0x1285f60}, 0xc0000fc600, 0x12bb060, 0xc000ec14b0) /usr/local/go/src/go/types/const.go:92 +0x192 go/types.(*Checker).representation(0xc0000fc600, 0xc000b8cf40, 0x12bb060) /usr/local/go/src/go/types/const.go:256 +0x65 go/types.(*Checker).implicitTypeAndValue(0xc0000fc600, 0xc000b8cf40, {0xdc36a0, 0xc0000b6770}) /usr/local/go/src/go/types/expr.go:375 +0x2d7 go/types.(*Checker).assignment(0xc0000fc600, 0xc000b8cf40, {0xdc36a0, 0xc0000b6770}, {0xc95293, 0x14}) /usr/local/go/src/go/types/assignments.go:52 +0x2e5 go/types.(*Checker).initConst(0xc0000fc600, 0xc00084f0e0, 0xc000b8cf40) /usr/local/go/src/go/types/assignments.go:126 +0x2c5 go/types.(*Checker).constDecl(0xc0000fc600, 0xc00084f0e0, {0xdc62c0, 0xc000a343e0}, {0xdc62c0, 0xc000a34400}, 0x0) /usr/local/go/src/go/types/decl.go:490 +0x311 go/types.(*Checker).objDecl(0xc0000fc600, {0xdcf1e0, 0xc00084f0e0}, 0x0) /usr/local/go/src/go/types/decl.go:191 +0xa49 go/types.(*Checker).packageObjects(0xc0000fc600) /usr/local/go/src/go/types/resolver.go:693 +0x4dd go/types.(*Checker).checkFiles(0xc0000fc600, {0xc000780750, 0x5, 0x5}) /usr/local/go/src/go/types/check.go:408 +0x1a5 go/types.(*Checker).Files(...) /usr/local/go/src/go/types/check.go:372 sigs.k8s.io/controller-tools/pkg/loader.(*loader).typeCheck(0xc000308c60, 0xc0008101c0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/loader.go:286 +0x36a sigs.k8s.io/controller-tools/pkg/loader.(*Package).NeedTypesInfo(0xc0008101c0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/loader.go:99 +0x39 sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check(0xc0003cb2f0, 0xc0008101c0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:268 +0x2b7 sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check.func1(0x16?) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:262 +0x53 created by sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check in goroutine 11 /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:260 +0x1c5 make: *** [Makefile:1046: k8s-manifests] Error 2 make[1]: *** [builder/Makefile.k8s:87: manifests] Error 2 docker run --rm \ -v /home/computer/computer/tracee:/tracee \ tracee-k8s:latest make k8s-generate controller-gen object:headerFile="deploy/boilerplate.go.txt" paths="./pkg/k8s/..." panic: runtime error: invalid memory address or nil pointer dereference [recovered] panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0xa0de6f] goroutine 130 [running]: go/types.(*Checker).handleBailout(0xc0004f2200, 0xc000767d40) /usr/local/go/src/go/types/check.go:367 +0x88 panic({0xbc7860?, 0x12b2880?}) /usr/local/go/src/runtime/panic.go:770 +0x132 go/types.(*StdSizes).Sizeof(0x0, {0xdc3678, 0x12bb060}) /usr/local/go/src/go/types/sizes.go:228 +0x30f go/types.(*Config).sizeof(...) /usr/local/go/src/go/types/sizes.go:333 go/types.representableConst.func1({0xdc3678?, 0x12bb060?}) /usr/local/go/src/go/types/const.go:76 +0x9e go/types.representableConst({0xdc9a50, 0x1285f60}, 0xc0004f2200, 0x12bb060, 0x0) /usr/local/go/src/go/types/const.go:92 +0x192 go/types.(*Checker).arrayLength(0xc0004f2200, {0xdc7d00, 0xc0010c2440?}) /usr/local/go/src/go/types/typexpr.go:510 +0x2d3 go/types.(*Checker).typInternal(0xc0004f2200, {0xdc6320, 0xc0010b5590}, 0x0) /usr/local/go/src/go/types/typexpr.go:299 +0x49d go/types.(*Checker).definedType(0xc0004f2200, {0xdc6320, 0xc0010b5590}, 0xc000767328?) /usr/local/go/src/go/types/typexpr.go:180 +0x37 go/types.(*Checker).varType(0xc0004f2200, {0xdc6320, 0xc0010b5590}) /usr/local/go/src/go/types/typexpr.go:145 +0x25 go/types.(*Checker).structType(0xc0004f2200, 0xc001120450, 0xc001120450?) /usr/local/go/src/go/types/struct.go:113 +0x19f go/types.(*Checker).typInternal(0xc0004f2200, {0xdc6290, 0xc0010c01e0}, 0xc000ef9680) /usr/local/go/src/go/types/typexpr.go:316 +0x1345 go/types.(*Checker).definedType(0xc0004f2200, {0xdc6290, 0xc0010c01e0}, 0xc91787?) /usr/local/go/src/go/types/typexpr.go:180 +0x37 go/types.(*Checker).typeDecl(0xc0004f2200, 0xc000ef9680, 0xc0010b8880, 0x0) /usr/local/go/src/go/types/decl.go:615 +0x44d go/types.(*Checker).objDecl(0xc0004f2200, {0xdcf000, 0xc000ef9680}, 0x0) /usr/local/go/src/go/types/decl.go:197 +0xa7f go/types.(*Checker).packageObjects(0xc0004f2200) /usr/local/go/src/go/types/resolver.go:681 +0x425 go/types.(*Checker).checkFiles(0xc0004f2200, {0xc001100a50, 0x3, 0x3}) /usr/local/go/src/go/types/check.go:408 +0x1a5 go/types.(*Checker).Files(...) /usr/local/go/src/go/types/check.go:372 sigs.k8s.io/controller-tools/pkg/loader.(*loader).typeCheck(0xc000271380, 0xc00078e4a0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/loader.go:286 +0x36a sigs.k8s.io/controller-tools/pkg/loader.(*Package).NeedTypesInfo(0xc00078e4a0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/loader.go:99 +0x39 sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check(0xc000888ba0, 0xc00078e4a0) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:268 +0x2b7 sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check.func1(0x1f?) /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:262 +0x53 created by sigs.k8s.io/controller-tools/pkg/loader.(*TypeChecker).check in goroutine 42 /go/pkg/mod/sigs.k8s.io/[email protected]/pkg/loader/refs.go:260 +0x1c5 make: *** [Makefile:1050: k8s-generate] Error 2 make[1]: *** [builder/Makefile.k8s:96: generate] Error 2 make: *** [builder/Makefile.k8s:3: all] Error 2

Ok, I was able to reproduce it. Gonna open an issue as we discussed.

thank you good luck

…ntributing_docs

geyslan

Put some thoughts.

geyslan · 2025-01-02T17:35:58Z

docs/contributing/kubernetes.md

+    Tracee's Makefile provides convenient targets for setting up MicroK8s:
+
+    ```bash
+    make -f builder/Makefile.k8s help


I suppose this would be under a 'k8s operator' topic.

geyslan · 2025-01-02T17:48:33Z

docs/contributing/overview.md

+    6. `backported/...`
+    7. `cherry-picked/...`


These two above are used in PRs to main when they've already be accomplished and based on the approach took (simple cherry-pick or a more complicated backport). Meanwhile, they must be labelled as candidate/vX.X.X.

For instance, when pushing patch PRs (incorporating already candidate merged ones into the release branches), those specific PRs should be labelled with backport or cherry-pick as they are indeed. And after that merge, the original PRs should have the candidate label removed and, based on the required approach, to have set the respective label as backported/vX.X.X or cherry-picked/vX.X.X.

ShohamBit added 11 commits December 9, 2024 21:18

add first changes to guidelines

bcc39f7

improve docs of guidelines and overview in contributing

55663e1

combine documentation and code guidelines

95e86cc

improve docs for setup development machine

2b29f81

improve building tracee docs

0dbe799

improve environment building docs

482c107

change console to bash

4bfe816

add Kubernetes, Performance and Man docs to tracee

3b78323

Merge branch 'main' of https://github.com/aquasecurity/tracee into co…

c61ecc5

…ntributing_docs

add checkers docsto guidelines

363e7b2

fix minor issues

0501e58

github-actions bot added the kind/documentation label Dec 11, 2024

github-actions bot assigned ShohamBit Dec 11, 2024

ShohamBit requested a review from geyslan December 12, 2024 13:08

geyslan reviewed Dec 12, 2024

View reviewed changes

resolve most changes

a6b3995

ShohamBit requested a review from geyslan December 16, 2024 15:13

geyslan reviewed Dec 16, 2024

View reviewed changes

docs/contributing/building/building.md Outdated Show resolved Hide resolved

ShohamBit added 2 commits December 17, 2024 20:54

improve metrics=1 docs

ab51f00

improve guidelines to use makefiles mostly

540c8ce

ShohamBit requested a review from geyslan December 17, 2024 20:59

rscampos reviewed Dec 20, 2024

View reviewed changes

ShohamBit added 2 commits December 22, 2024 11:41

update make help

c14fbca

add help text

4aae9c7

github-actions bot added the area/build label Dec 22, 2024

Merge branch 'main' of https://github.com/aquasecurity/tracee into co…

5b9a520

…ntributing_docs

geyslan reviewed Jan 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Contributing docs #4424

Update Contributing docs #4424

ShohamBit commented Dec 11, 2024

geyslan left a comment

rscampos commented Dec 20, 2024 •

edited

Loading

rscampos Dec 20, 2024

rscampos Dec 20, 2024 •

edited

Loading

ShohamBit Dec 22, 2024

geyslan Jan 2, 2025

ShohamBit Jan 2, 2025

geyslan Jan 2, 2025

ShohamBit Jan 2, 2025

geyslan Jan 2, 2025

geyslan left a comment

geyslan Jan 2, 2025

geyslan Jan 2, 2025

Update Contributing docs #4424

Are you sure you want to change the base?

Update Contributing docs #4424

Conversation

ShohamBit commented Dec 11, 2024

1. Explain what the PR does

2. Explain how to test it

3. Other comments

geyslan left a comment

Choose a reason for hiding this comment

rscampos commented Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

rscampos Dec 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

geyslan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rscampos commented Dec 20, 2024 •

edited

Loading

rscampos Dec 20, 2024 •

edited

Loading