Documentation: Fix broken links, move deep dive section (#2322)

* Move Deep Dive to docs rather than Contributing section * Fix broken links * Move contributing guide Signed-off-by: grantseltzer <grantseltzer@gmail.com>
aquasecurity · Nov 3, 2022 · 20daa29 · 20daa29
1 parent 430c073
commit 20daa29
Show file tree

Hide file tree

Showing 17 changed files with 93 additions and 93 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/Readme.md b/Readme.md
@@ -70,8 +70,8 @@ Tracee is an [Aqua Security] open source project.
 Learn about our open source work and portfolio [Here].
 Join the community, and talk to us about any matter in [GitHub Discussion] or [Slack].
 
-[Tracee-eBPF]: https://github.com/aquasecurity/tracee/tree/main/cmd/tracee-ebpf
-[Tracee-Rules]: https://github.com/aquasecurity/tracee/tree/main/cmd/tracee-rules
+[Tracee-eBPF]: https://aquasecurity.github.io/tracee/dev/docs/tracing/
+[Tracee-Rules]: https://aquasecurity.github.io/tracee/dev/docs/detecting/
 
 [Aqua Security]: https://aquasec.com
 [GitHub Discussion]: https://github.com/aquasecurity/tracee/discussions

diff --git a/cmd/tracee-ebpf/readme.md b/cmd/tracee-ebpf/readme.md
@@ -1,7 +1,6 @@
 # Documentation
 
 The full documentation of Tracee-eBPF is available at
-[https://aquasecurity.github.io/tracee/dev/tracee-ebpf/](https://aquasecurity.github.io/tracee/dev/tracee-ebpf/).
+[https://aquasecurity.github.io/tracee/dev/docs/tracing/](https://aquasecurity.github.io/tracee/dev/docs/tracing/).
 You can use the version selector on top to view documentation for a specific
 version of Tracee.
-
diff --git a/cmd/tracee-rules/readme.md b/cmd/tracee-rules/readme.md
@@ -1,7 +1,6 @@
 # Documentation
 
 The full documentation of Tracee-Rules is available at
-[https://aquasecurity.github.io/tracee/dev/tracee-rules/](https://aquasecurity.github.io/tracee/dev/tracee-rules/).
+[https://aquasecurity.github.io/tracee/dev/docs/detecting/](https://aquasecurity.github.io/tracee/dev/docs/detecting/).
 You can use the version selector on top to view documentation for a specific
 version of Tracee.
-
diff --git a/docs/contributing/overview.md b/docs/contributing/overview.md
@@ -1 +1,52 @@
-This section goes deep explaning Tracee's internals, and how to build Tracee on different platforms for the users interested in contributing.
+## Contributing
+
+Thank you for taking interest in contributing to Tracee! This document covers our working practices and conventions.
+
+## Issues and Discussions
+
+We encourage open discussion and collaboration using both GitHub Issues and Discussions.  
+
+- [Discussions](https://github.com/aquasecurity/tracee/discussions) are free-style conversational tool, we use them for conversations.
+- [Issues](https://github.com/aquasecurity/tracee/issues) are project management tool, we use them to keep track on who's working on what and plan ahead.
+
+If you have a suggestion, question, or a general comment - please use Discussions. If there's a clear work item (including bugs) - you can open an Issue.
+
+### Discussions:
+
+- We have the following discussion topics: 
+    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
+    1. [Questions and Help](https://github.com/aquasecurity/tracee/discussions/categories/questions-and-help): For help and support. Consider this similar to StackOverflow.
+    1. [Development](https://github.com/aquasecurity/tracee/discussions/categories/development): For discussing potential features, and collaborating on their design.
+
+### Issues:
+
+1. Every issue needs to be actionable and assignable. Consider the scope of the issue if assigned to one person, and break down if necessary.
+1. Be clear and definitive when composing issues. For bug reports, include detailed error messages and environment description. For features, include a clear scope and acceptance criteria.
+1. Since we have different projects under the same monorepo, use labels to denote areas that the issue relates to:
+    1. `tracee-ebpf`
+    1. `tracee-rules`
+    1. `signatures`
+    1.  If non of the labels is relevant don't add any (usually for top-level issues)
+1. We use the following labels to describe the type of issue:
+    1. `bug`
+    1. `good-first-issue`
+1. Self-assign or request assignment for issues you intend to work on. Don't work on an issue assigned to someone else without checking with them first and reassigning.
+
+## Pull Requests
+
+1. Every Pull Request should have an associated Issue unless it is a trivial fix.
+1. When adding a flag option or other UX related change, make sure the design is explicitly described in the associated issue, and a maintainer approved it.
+1. Commit subject should succinctly describe the change:
+    1. Max 50 chars.
+    1. Written in imperative mood: begin with a verb like "fix", "add", "improve", or "refactor"; Think "once applied, this commit will...".
+    1. If ambiguous, mention the area that this commit affects (see area labels above).
+1. Optional commit body (separated by empty line from subject) may explain why the change was made and not how. Wrap at 72 chars.
+1. Code related information should be in commit message, review related information should be in PR description.
+1. For changes that span different areas please try to make each change self contained and independent.
+
+
+## Code
+
+1. Follow Golang's code review standards: https://github.com/golang/go/wiki/CodeReviewComments.
+1. Follow `gofmt` + `govet` + `goimports` formatting.
+1. Tests should be included alongside code changes wherever applicable, except for parts that are harder to test and are not currently tested (e.g. eBPF). When modifying already tested code, your changes must be represented in the existing tests.
diff --git a/docs/contributing/architecture.md → docs/docs/deep-dive/architecture.md b/docs/contributing/architecture.md → docs/docs/deep-dive/architecture.md
@@ -2,7 +2,7 @@
 
 ## Tracee Architecture Overview
 
-![Architecture](../images/architecture.png)
+![Architecture](../../images/architecture.png)
 
 !!! Overview Note
 
@@ -17,26 +17,26 @@
         1. Derived (from other) Events
         1. Network Events
 
-    [COLLECTED]:./../docs/tracing/index.md
+    [COLLECTED]:./../tracing/index.md
 
     1. **[DETECT]** patterns based on existing signatures:
-        1. [OPA/Rego signatures](./../docs/detecting/rego.md)
-        1. [Golang signatures](./../docs/detecting/golang.md)
-        1. [Go-CEL signatures](./../docs/detecting/go-cel.md) (Proof-of-Concept / Experimental)
+        1. [OPA/Rego signatures](../detecting/rego.md)
+        1. [Golang signatures](../detecting/golang.md)
+        1. [Go-CEL signatures](../detecting/go-cel.md) (Proof-of-Concept / Experimental)
 
-    [DETECT]: ./../docs/detecting/index.md
+    [DETECT]: ./../detecting/index.md
 
     1. Let other tools to **CONSUME** detection events:
-        1. [Capture Artifacts](./../docs/capturing/index.md)
-        1. [Postee](./../docs/integrating/postee.md)
-        1. [Falco Sidekick](./../docs/integrating/falcosidekick.md)
+        1. [Capture Artifacts](./../capturing/index.md)
+        1. [Postee](./../integrating/postee.md)
+        1. [Falco Sidekick](./../integrating/falcosidekick.md)
 
     1. **ENFORCE**
         1. Work in Progress
 
 ## Tracee Pipeline Concept
 
-![Tracee Pipeline](../images/tracee-pipeline-overview.png)
+![Tracee Pipeline](../../images/tracee-pipeline-overview.png)
 
 !!! Pipeline Warning
 
@@ -79,11 +79,12 @@
     > those events and to submit them to **tracee-rules** for it to evaluate
     > them looking for detection patterns described as **signatures**.
 
-[shared memory ring buffer]: ./../contributing/deep-dive/performance.md
-[parse events for argument type]: ./../docs/tracing/output-options.md
-[enriches the events]: ./../docs/integrating/container-engines.md
-[capture artifacts]: ./../docs/capturing/index.md
-[golang]: ./../docs/detecting/golang.md
-[rego]: ./../docs/detecting/rego.md
-[go-cel]: ./../docs/detecting/go-cel.md
-[spit out]: ./../docs/integrating/webhook.md
+[shared memory ring buffer]: ./performance.md
+[parse events for argument type]: ./../tracing/output-options.md
+[enriches the events]: ./../integrating/container-engines.md
+[capture artifacts]: ./../capturing/index.md
+[golang]: ./../detecting/golang.md
+[rego]: ./../detecting/rego.md
+[go-cel]: ./../detecting/go-cel.md
+[spit out]: ./../integrating/webhook.md
+
diff --git a/.../contributing/deep-dive/caching-events.md → docs/docs/deep-dive/caching-events.md b/.../contributing/deep-dive/caching-events.md → docs/docs/deep-dive/caching-events.md
@@ -12,9 +12,9 @@ $ ./dist/tracee-ebpf --cache help
     understand the [tracee pipeline] concept, AND the [performance page], to
     understand possible pain points.
 
-[architecture page]: ../architecture.md
+[architecture page]: ./architecture.md
 [performance page]: ./performance.md
-[tracee pipeline]: ../architecture.md#tracee-pipeline-concept
+[tracee pipeline]: ./architecture.md#tracee-pipeline-concept
 
 ![Tracee Cache](../../images/tracee-cache.png)
 

diff --git a/...buting/deep-dive/dropping-capabilities.md → docs/docs/deep-dive/dropping-capabilities.md b/...buting/deep-dive/dropping-capabilities.md → docs/docs/deep-dive/dropping-capabilities.md
diff --git a/docs/contributing/deep-dive/healthz.md → docs/docs/deep-dive/healthz.md b/docs/contributing/deep-dive/healthz.md → docs/docs/deep-dive/healthz.md
diff --git a/...contributing/deep-dive/ordering-events.md → docs/docs/deep-dive/ordering-events.md b/...contributing/deep-dive/ordering-events.md → docs/docs/deep-dive/ordering-events.md
diff --git a/...ntributing/deep-dive/override-os-files.md → docs/docs/deep-dive/override-os-files.md b/...ntributing/deep-dive/override-os-files.md → docs/docs/deep-dive/override-os-files.md
diff --git a/docs/docs/deep-dive/overview.md b/docs/docs/deep-dive/overview.md
@@ -0,0 +1 @@
+This section goes deep explaning Tracee's internals, and how to build Tracee on different platforms for the users interested in contributing.
diff --git a/docs/contributing/deep-dive/performance.md → docs/docs/deep-dive/performance.md b/docs/contributing/deep-dive/performance.md → docs/docs/deep-dive/performance.md
@@ -4,8 +4,8 @@
     Before continuing, please read the [architecture page], in order to
     understand the [tracee pipeline] concept.
 
-[architecture page]: ../architecture.md
-[tracee pipeline]: ../architecture.md#tracee-pipeline-concept
+[architecture page]: ./architecture.md
+[tracee pipeline]: ./architecture.md#tracee-pipeline-concept
 
 ![Tracee Performance](../../images/tracee-performance.png)
 

diff --git a/.../contributing/deep-dive/secure-tracing.md → docs/docs/deep-dive/secure-tracing.md b/.../contributing/deep-dive/secure-tracing.md → docs/docs/deep-dive/secure-tracing.md
diff --git a/docs/docs/detecting/rego.md b/docs/docs/detecting/rego.md
@@ -4,7 +4,7 @@
     Differently than [golang built-in signatures](./golang.md), with Rego
     signatures you are able to add and/or remove signatures to Tracee without
     the need of recompiling it (or re-distributing the binary) BUT it may come
-    with a [performance price](../../contributing/deep-dive/performance.md) to pay.
+    with a [performance price](../../docs/deep-dive/performance.md) to pay.
 
 In order to create your own [Rego] signature you need to create a `.rego`
 file in the **rules directory** that has the following Rego Rules (now, in

diff --git a/docs/docs/overview.md b/docs/docs/overview.md
@@ -12,3 +12,5 @@ This documentation details how to use Tracee to access the features listed below
 	- Tracee is a runtime security detection engine, more than an introspection tool (tracee-ebpf) only. tracee-rules is a rules engine that helps you detect suspicious behavioral patterns in streams of events.
 - Integrating
 	- Tracee integration with other techonologies, like Prometheus.
+- Deep Dive
+	- In depth analysis of specific features and core logic to Tracee's various components.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -49,25 +49,25 @@ nav:
             - Postee: docs/integrating/postee.md
             - Falcosidekick: docs/integrating/falcosidekick.md
         - Prometheus: docs/integrating/prometheus.md
+    - Deep Dive:
+      - Architecture: docs/deep-dive/architecture.md
+      - Secure Tracing: docs/deep-dive/secure-tracing.md
+      - Performance: docs/deep-dive/performance.md
+      - Caching Events: docs/deep-dive/caching-events.md
+      - Ordering Events: docs/deep-dive/ordering-events.md
+      - Override OS files: docs/deep-dive/override-os-files.md
+      - Healthz: docs/deep-dive/healthz.md
+
   - Contributing:
     - Overview: contributing/overview.md
-    - Architecture: contributing/architecture.md
     - Source Code Guidelines: contributing/guidelines.md
     - Building:
       - Building Tracee: contributing/building/building.md
       - Building Environment: contributing/building/environment.md
       - Building Containers: contributing/building/containers.md
       - Building non CO-RE: contributing/building/nocore-ebpf.md
       - OS Packaging: contributing/building/packaging.md
-      - Building on OSX: contributing/building/macosx.md
-    - Deep Dive:
-      - Secure Tracing: contributing/deep-dive/secure-tracing.md
-      - Performance: contributing/deep-dive/performance.md
-      - Caching Events: contributing/deep-dive/caching-events.md
-      - Ordering Events: contributing/deep-dive/ordering-events.md
-      - Override OS files: contributing/deep-dive/override-os-files.md
-      - Healthz: contributing/deep-dive/healthz.md
-
+      - Building on OSX: contributing/building/macosx.md      
 theme:
     name: material
     language: 'en'