Update Contributing docs #4424

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

1. Explain what the PR does

enhance documentation of the guidelines
add sections on contributing to Tracee source code
improve docs on build traces
improve docs on the build environment
refactor Tracee docs on how to contribute
enhance the issues section
enhance PR section

0a6f8cc added backport and cherry-pick labels
1ea57fb Merge branch 'main' of https://github.com/aquasecurity/tracee into contributing_docs
f63b97d Merge branch 'contributing_docs' of https://github.com/ShohamBit/tracee into contributing_docs
9f72406 add candidate label docs
6153e85 enhance backported and cherry-picked labels docs
8d70805 Update docs/contributing/overview.md
fe05d9a enhance Issues docs part, added candidate labe docs
5b9a520 Merge branch 'main' of https://github.com/aquasecurity/tracee into contributing_docs
4aae9c7 add help text
c14fbca update make help
540c8ce improve guidelines to use makefiles mostly
ab51f00 improve metrics=1 docs
a6b3995 resolve most changes
0501e58 fix minor issues
363e7b2 add checkers docsto guidelines
c61ecc5 Merge branch 'main' of https://github.com/aquasecurity/tracee into contributing_docs
3b78323 add Kubernetes, Performance and Man docs to tracee

8d70805 Update docs/contributing/overview.md

Co-authored-by: Gregório G. <[email protected]>

2. Explain how to test it

Read the docs and check if they are properly aligned with Tracee's 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

docs/contributing/building/building.md

docs/contributing/kubernetes.md

…ntributing_docs

geyslan

Put some thoughts.

docs/contributing/kubernetes.md

docs/contributing/overview.md

geyslan

LGTM when consider my last suggestions.

@yanivagman @rscampos it would be nice to have other passes from you, as it concerns different areas.

docs/contributing/overview.md

Co-authored-by: Gregório G. <[email protected]>

… into contributing_docs

…ntributing_docs

docs/contributing/overview.md

rscampos · 2025-01-13T18:22:28Z

docs/contributing/building/building.md

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


nit: only topic 9 end with a dot, should we remove?

rscampos · 2025-01-13T18:25:54Z

docs/contributing/building/building.md

@@ -163,19 +119,16 @@
        >plugin.Open("/tracee/dist/signatures/builtin.so"): Dynamic loading not supported
        >```

-8. Build a **debugable binary** with DWARF generation by setting `DEBUG=1`
+8. Build a **debuggable binary** with DWARF generation by setting `DEBUG=1`


nit: The phrase is clear enough, but I'd change to:

Build a debuggable binary with DWARF debug symbols by setting DEBUG=1

WDYT?

rscampos · 2025-01-13T19:56:53Z

docs/contributing/building/environment.md


-* Alpine
-* Ubuntu
+The reason for that is that **Alpine Linux** is based in the [musl](https://en.wikipedia.org/wiki/Musl) C standard library.


I think we can combine both:

The reason for that is that Alpine Linux is based in the musl C standard library, while the Ubuntu Linux uses glibc.

rscampos · 2025-01-13T20:05:22Z

docs/contributing/building/environment.md


-> **Note**: the generated binary must be compatible to your host (depending on
-> glibc version, for example).
+    * Show help for make file:


nit: makefile

Could you check if make sense?

rscampos · 2025-01-13T20:06:02Z

docs/contributing/building/environment.md

+
+2. Verify the executable is static
+
+    * Note: ldd print the shared libraries required by an executable file


nit: prints

rscampos · 2025-01-13T20:43:46Z

docs/contributing/guidelines.md

+
+Tracee relies on several generated files and has strict formatting requirements. Ensure you run the following commands before committing:
+
+**`NOTE:`** In order to not depend on host's libraries versions, We recommend that you always run make and other project dependencies on a virtual environment so the formatting will be align with tracee guidelines


nit: Should we replace tracee to Tracee?

rscampos · 2025-01-13T20:45:55Z

docs/contributing/guidelines.md


-!!! check-code Example
+    **`NOTE:`**  If your host machine dependencies doesn't align with tracee dependencies, This command have to run on a supported [environment](./building/environment.md)


ditto: Should we replace tracee to Tracee?

rscampos · 2025-01-13T20:46:43Z

docs/contributing/guidelines.md

+
+Tracee relies on several generated files and has strict formatting requirements. Ensure you run the following commands before committing:
+
+**`NOTE:`** In order to not depend on host's libraries versions, We recommend that you always run make and other project dependencies on a virtual environment so the formatting will be align with tracee guidelines


nit: libraries versions, we recommend

rscampos · 2025-01-13T20:49:29Z

docs/contributing/guidelines.md

+
+### Kubernetes Considerations
+
+If your contribution impacts Tracee's behavior within a Kubernetes cluster, follow the guidelines in [Kubernetes Considerations](./kubernetes.md)


nit: end with dot. Should we also end with a dot all the notes?

rscampos · 2025-01-13T21:30:19Z

docs/contributing/performance.md

+2. **Performance Dashboard:** The provided performance dashboard allows visualization of host metrics, CPU flame graphs, and other performance-related data. Follow these steps to deploy locally and see instructions on using the dasboard:
+
+    ```bash
+    make -f builder/Makefile.performance dashboard-start


When we run dashboard-start it will complains that Tracee need to be run with the flag --pprof. We can add a note under Performance Dashboard section I think or change the sudo ./dist/tracee --pyroscope to be sudo ./dist/tracee --pyroscope --pprof. WDYT?

rscampos · 2025-01-13T21:39:26Z

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

-rwxr-xr-x 1 vagrant vagrant 62619312 Mar 29 19:08 tracee
-rw-r--r-- 1 vagrant vagrant 10753624 Mar 29 19:06 tracee.bpf.o
-```
+Open a terminal and navigate to the directory containing the `Vagrantfile.builder` within the cloned Tracee repository. Rename `Vagrantfile.builder` to `Vagrantfile`.


What file Vagrantfile.builder are you referencing for?

rscampos · 2025-01-13T21:48:13Z

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

-...
-```
+  ```bash
+  export VM_TYPE=dev


I think would be good to add a note explaining about the default option (if none of the following is used).

rscampos

@ShohamBit I did a second pass... LGTM.

For simplicity, maybe only consider version 14 since (remove 12 and 13)? we use version 14 in the Vagrant file (https://github.com/aquasecurity/tracee/blame/main/Vagrantfile) and the actions (https://github.com/aquasecurity/tracee/blob/main/.github/actions/build-dependencies/action.yaml)

tracee/docs/contributing/building/building.md

Line 15 in 0a6f8cc

1. **clang** && **llvm** (12, 13 or 14)

Both links doesn't exists:

tracee/docs/contributing/building/building.md

Lines 28 to 29 in 0a6f8cc

    
               > 1. [packaging/Dockerfile.ubuntu-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.ubuntu-packaging) 
        
               > 1. [packaging/Dockerfile.fedora-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.fedora-packaging)

Maybe we can replace with:
https://github.com/aquasecurity/tracee/blob/main/builder/Dockerfile.alpine-tracee-make
https://github.com/aquasecurity/tracee/blob/main/builder/Dockerfile.ubuntu-tracee-make

Nit: add dot at the end

tracee/docs/contributing/overview.md

Line 17 in 0a6f8cc

    
           1. [Announcements](https://github.com/aquasecurity/tracee/discussions/categories/announcements): One way communication from the team to the community. Consider this like our mini blog

Personal notes (WIP topics)
It seems there are three places with some personal notes (I think) in this file.
https://github.com/aquasecurity/tracee/blob/0a6f8cc66b103d3cfd0da5cc17b2e4a9ad03129c/docs/contributing/performance.md

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

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

rscampos reviewed Dec 20, 2024

View reviewed changes

docs/contributing/kubernetes.md Show resolved Hide resolved

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

docs/contributing/kubernetes.md Show resolved Hide resolved

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

enhance Issues docs part, added candidate labe docs

fe05d9a

geyslan approved these changes Jan 7, 2025

View reviewed changes

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

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

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

ShohamBit and others added 5 commits January 8, 2025 14:50

Update docs/contributing/overview.md

8d70805

Co-authored-by: Gregório G. <[email protected]>

enhance backported and cherry-picked labels docs

6153e85

add candidate label docs

9f72406

Merge branch 'contributing_docs' of https://github.com/ShohamBit/tracee…

f63b97d

… into contributing_docs

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

1ea57fb

…ntributing_docs

geyslan reviewed Jan 8, 2025

View reviewed changes

docs/contributing/overview.md Show resolved Hide resolved

added backport and cherry-pick labels

0a6f8cc

rscampos reviewed Jan 13, 2025

View reviewed changes

rscampos approved these changes Jan 13, 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 •

edited

Loading

geyslan left a comment

rscampos commented Dec 20, 2024 •

edited

Loading

geyslan left a comment

geyslan left a comment

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025

rscampos Jan 13, 2025 •

edited

Loading

rscampos left a comment


		2. Verify the executable is static

		* Note: ldd print the shared libraries required by an executable file


		Tracee relies on several generated files and has strict formatting requirements. Ensure you run the following commands before committing:

		`NOTE:` In order to not depend on host's libraries versions, We recommend that you always run make and other project dependencies on a virtual environment so the formatting will be align with tracee guidelines


		!!! check-code Example
		`NOTE:` If your host machine dependencies doesn't align with tracee dependencies, This command have to run on a supported [environment](./building/environment.md)


		### Kubernetes Considerations

		If your contribution impacts Tracee's behavior within a Kubernetes cluster, follow the guidelines in [Kubernetes Considerations](./kubernetes.md)

	> 1. [packaging/Dockerfile.ubuntu-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.ubuntu-packaging)
	> 1. [packaging/Dockerfile.fedora-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.fedora-packaging)

Update Contributing docs #4424

Are you sure you want to change the base?

Update Contributing docs #4424

Conversation

ShohamBit commented Dec 11, 2024 • edited Loading

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

geyslan left a comment

Choose a reason for hiding this comment

geyslan left a comment

Choose a reason for hiding this comment

rscampos Jan 13, 2025 • 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

rscampos Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

rscampos Jan 13, 2025 • 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

rscampos Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

rscampos left a comment

Choose a reason for hiding this comment

ShohamBit commented Dec 11, 2024 •

edited

Loading

rscampos commented Dec 20, 2024 •

edited

Loading

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025 •

edited

Loading

rscampos Jan 13, 2025 •

edited

Loading