Skip to content

book: add more contents to developer guide#221

Merged
kxxt merged 3 commits into
mainfrom
dev-guide
May 18, 2026
Merged

book: add more contents to developer guide#221
kxxt merged 3 commits into
mainfrom
dev-guide

Conversation

@kxxt
Copy link
Copy Markdown
Owner

@kxxt kxxt commented Apr 20, 2026

Summary by CodeRabbit

  • Documentation
    • Added three Developer Guide pages: system architecture overview, a testing guide with running and coverage procedures, and a release-cutting checklist covering pre-release checks and publication steps.
    • Updated the documentation index to link to the new Developer Guide resources.

Review Change Stack

@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 20, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
tracexec Ready Ready Preview, Comment May 18, 2026 1:06pm

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 20, 2026

Warning

Rate limit exceeded

@kxxt has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 24 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 2611b870-ffdf-4c76-a7e2-ff60a8782421

📥 Commits

Reviewing files that changed from the base of the PR and between 72dc8a0 and 382986b.

📒 Files selected for processing (3)
  • book/SUMMARY.md
  • book/dev/architecture.md
  • book/dev/tests.md

Walkthrough

Adds three Developer Guide pages (architecture, tests, release checklist) and updates book/SUMMARY.md to link the new pages and correct the Internal Architecture TOC entry.

Changes

Developer Guide

Layer / File(s) Summary
Table of contents update
book/SUMMARY.md
Corrected Internal Architecture link to ./dev/architecture.md and added Tests and Checklist for Cutting a Release TOC entries.
Architecture document
book/dev/architecture.md
New page describing crate separation (frontend vs backend), tracexec-core abstractions, and the TracerMessage/PendingRequest event routing model.
Release checklist
book/dev/release.md
New checklist covering pre-release checks, changelog and docs updates, version bumping, tagging, and publishing the release draft.
Tests documentation
book/dev/tests.md
New guide for running workspace vs root-required tests, generating combined coverage (user-space and eBPF/kernel), and test authoring conventions (root-only markers, eBPF serialization).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

  • kxxt/tracexec#175: Initial mdBook setup and SUMMARY.md structure that this change builds upon.

Poem

🐰 A rabbit hops through pages new,
With tests and tips and release brew,
Architecture penned in tidy lines,
Checklists, coverage, all aligns,
Hooray — the dev guide sprouts and grew!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main change: adding developer guide content (architecture, tests, and release documentation to book/dev/).
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch dev-guide

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (2)
book/dev/tests.md (1)

84-84: Minor: Consider inserting "it" for clarity.

The phrase "test that requires root" could optionally be "test that it requires root" for slightly better readability, though the current phrasing is grammatically acceptable.

♻️ Optional refinement
-When adding a test that  requires root, please mark it with
+When adding a test that requires root, please mark it with

Note: There's also a double space before "requires" that should be reduced to a single space.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@book/dev/tests.md` at line 84, The sentence "When adding a test that 
requires root, please mark it with" has an extra space and could be clearer;
edit the fragment "test that  requires root" to remove the double space and
optionally insert "it" to read either "test that requires root" or "test that it
requires root" (preferably "test that requires root" for concise clarity) so the
wording is grammatically clean.
book/dev/release.md (1)

13-16: Improve sentence clarity and completeness.

Line 13 ends abruptly ("if some features are changed"), and line 14 has an awkward construction ("Update CHANGELOG.md to document" followed by sub-bullets). Consider rephrasing for better readability.

♻️ Suggested refinement
-- [ ] Update this book if some features are changed 
+- [ ] Update this book if any features are changed.
 - [ ] Update `CHANGELOG.md` to document 
-  - notable changes compared to previous stable release for a stable release or release candidate,
-  - or notable changes compared to previous unstable release for an unstable `alpha/beta` release.
+  - for stable releases or release candidates: notable changes compared to the previous stable release,
+  - for unstable `alpha/beta` releases: notable changes compared to the previous unstable release.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@book/dev/release.md` around lines 13 - 16, The two checklist lines are
unclear: replace the fragment "Update this book if some features are changed"
with a full sentence like "Update this book whenever features or user-facing
behavior change." Also rewrite the "Update `CHANGELOG.md` to document" bullet
into a complete sentence and simplify the sub-bullets to parallel phrasing, e.g.
"Update `CHANGELOG.md` to document notable changes: for stable releases or
release candidates, compare to the previous stable release; for unstable
(alpha/beta) releases, compare to the previous unstable release." Ensure
punctuation and parallel structure are applied to the sub-bullets and terminate
each item with a period.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@book/dev/architecture.md`:
- Line 29: Fix the subject-verb agreement in the sentence "We includes a tiny
perfetto trace protobuf binding minified by hand so `perfetto-trace-proto`" by
changing "includes" to "include" so it reads "We include a tiny perfetto trace
protobuf binding minified by hand so `perfetto-trace-proto`"; update that exact
sentence in the documentation (look for the sentence containing
"`perfetto-trace-proto`") and keep the rest unchanged.
- Line 25: Typo: change the phrase "through out" to the single word "throughout"
in the sentence mentioning the `tracexec-core` crate (the string containing
"tracexec-core" and "through out") so it reads "...that are used throughout".
Ensure only the spacing is corrected and punctuation/capitalization around
`tracexec-core` is preserved.
- Line 42: The doc incorrectly calls TracerMessage a struct; update the sentence
to state that TracerMessage is an enum with variants Event and StateUpdate
(e.g., "TracerMessage is an enum with variants `Event` and `StateUpdate` used
for messages from backend to frontend"), and ensure any surrounding text or
examples reflect enum semantics and variant names `Event` and `StateUpdate`.

In `@book/dev/tests.md`:
- Line 82: Fix the typo in the sentence "Feel free to add new tests to coverage
new/modified code." by replacing "coverage" with "cover" so it reads "Feel free
to add new tests to cover new/modified code."; update the string in
book/dev/tests.md where that exact sentence appears.

---

Nitpick comments:
In `@book/dev/release.md`:
- Around line 13-16: The two checklist lines are unclear: replace the fragment
"Update this book if some features are changed" with a full sentence like
"Update this book whenever features or user-facing behavior change." Also
rewrite the "Update `CHANGELOG.md` to document" bullet into a complete sentence
and simplify the sub-bullets to parallel phrasing, e.g. "Update `CHANGELOG.md`
to document notable changes: for stable releases or release candidates, compare
to the previous stable release; for unstable (alpha/beta) releases, compare to
the previous unstable release." Ensure punctuation and parallel structure are
applied to the sub-bullets and terminate each item with a period.

In `@book/dev/tests.md`:
- Line 84: The sentence "When adding a test that  requires root, please mark it
with" has an extra space and could be clearer; edit the fragment "test that 
requires root" to remove the double space and optionally insert "it" to read
either "test that requires root" or "test that it requires root" (preferably
"test that requires root" for concise clarity) so the wording is grammatically
clean.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: cb73bb61-5866-4673-a51d-7fbf1b4c3e62

📥 Commits

Reviewing files that changed from the base of the PR and between 03bda74 and 57c5205.

📒 Files selected for processing (4)
  • book/SUMMARY.md
  • book/dev/architecture.md
  • book/dev/release.md
  • book/dev/tests.md

Comment thread book/dev/architecture.md Outdated
Comment thread book/dev/architecture.md Outdated
Comment thread book/dev/architecture.md Outdated
Comment thread book/dev/tests.md Outdated
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@book/dev/tests.md`:
- Line 50: Replace the hardcoded target triple in the export line (currently
setting CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER) with a variable-based name
using the existing <TARGET_TRIPLE> pattern (same approach as used on Line 18) so
the root-coverage command is architecture-agnostic, and add a short example
demonstrating how to set <TARGET_TRIPLE> before running the command.

In `@book/SUMMARY.md`:
- Around line 37-38: Two empty TOC links ("[Backend Differences]()" and "[Event
System]()") in SUMMARY.md cause broken navigation; either remove these two
entries or replace the empty parentheses with the correct relative doc paths
(e.g., replace "[Backend Differences]()" and "[Event System]()" with valid links
to their markdown pages) so the table of contents points to real pages, or
temporarily delete those list items until the pages exist.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 59494047-8e91-4b15-8731-1a1c6a7d2a3b

📥 Commits

Reviewing files that changed from the base of the PR and between 57c5205 and 72dc8a0.

📒 Files selected for processing (4)
  • book/SUMMARY.md
  • book/dev/architecture.md
  • book/dev/release.md
  • book/dev/tests.md
✅ Files skipped from review due to trivial changes (1)
  • book/dev/architecture.md

Comment thread book/dev/tests.md Outdated
Comment thread book/SUMMARY.md
Comment on lines 37 to 38
- [Backend Differences]()
- [Event System]()
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix empty TOC links to avoid broken navigation.

Line 37 and Line 38 use empty URLs, which creates broken entries in the book navigation. Please either link to real pages or temporarily remove these items until the docs exist.

Suggested diff
-  - [Backend Differences]()
-  - [Event System]()
+  - [Backend Differences](./dev/backend-differences.md)
+  - [Event System](./dev/event-system.md)
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 37-37: No empty links

(MD042, no-empty-links)


[warning] 38-38: No empty links

(MD042, no-empty-links)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@book/SUMMARY.md` around lines 37 - 38, Two empty TOC links ("[Backend
Differences]()" and "[Event System]()") in SUMMARY.md cause broken navigation;
either remove these two entries or replace the empty parentheses with the
correct relative doc paths (e.g., replace "[Backend Differences]()" and "[Event
System]()" with valid links to their markdown pages) so the table of contents
points to real pages, or temporarily delete those list items until the pages
exist.

@kxxt kxxt merged commit 531a96a into main May 18, 2026
6 checks passed
@kxxt kxxt deleted the dev-guide branch May 18, 2026 13:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant