# Veda, the First Agentic Hobby OS Needs Contribution

> Source: <https://github.com/vahmoh25/Veda/commit/e272c19af15ef1d0b7d932e2c4308cfecbd82d81>
> Published: 2026-10-16 22:53:40+00:00

|  | 
|  | `1` | `+`<!-- SPDX-FileCopyrightText: © 2026 Vahid Mohammadi --> | 
|  | `2` | `+`<!-- SPDX-License-Identifier: GPL-3.0-only --> | 
|  | `3` | `+` | 
|  | `4` | `+`# Contributing to Veda | 
|  | `5` | `+` | 
|  | `6` | `+` Thank you for helping build Veda. This guide covers how to propose a | 
|  | `7` | `+` change, the standards every change meets, and how changes are tested and | 
|  | `8` | `+` reviewed. [Developing](documentation/DEVELOPING.md) has the commands in | 
|  | `9` | `+` full, [Coding conventions](documentation/CODING.md) the rules the code | 
|  | `10` | `+` follows, and [Architecture](documentation/ARCHITECTURE.md) the design. | 
|  | `11` | `+` | 
|  | `12` | `+`**Contents:** [Before you start](#before-you-start) · [Making a change](#making-a-change) · [Engineering standards](#engineering-standards) · [Testing](#testing) · [Documentation](#documentation) · [Commits](#commits) · [Pull requests](#pull-requests) · [Reporting a vulnerability](#reporting-a-vulnerability) · [Licence](#licence) | 
|  | `13` | `+` | 
|  | `14` | `+`## Before you start | 
|  | `15` | `+` | 
|  | `16` | `+`- **Found a bug?** Open an issue with the steps, what happened and what | 
|  | `17` | `+`  you expected, the commit (`git rev-parse --short HEAD`) and what | 
|  | `18` | `+` `cargo orchestration doctor` says. Attach the log: | 
|  | `19` | `+` `target/veda/serial.log` after `script`, `shot` or `test`, the file | 
|  | `20` | `+` `cargo orchestration run --serial FILE` writes, or `VEDA/LOGS/` on a live | 
|  | `21` | `+`  system's stick. | 
|  | `22` | `+`- **Planning more than a fix?** Open an issue first for a new service, | 
|  | `23` | `+`  protocol or application, a change to who may do what, or a new | 
|  | `24` | `+`  dependency or port. Agreeing on the approach saves rework. | 
|  | `25` | `+`- **Have a question?** Open an issue. | 
|  | `26` | `+`- **Found a vulnerability?** Report it privately, never in an issue; see | 
|  | `27` | `+` [Reporting a vulnerability](#reporting-a-vulnerability). | 
|  | `28` | `+` | 
|  | `29` | `+` To set up, follow the [quick start](README.md#quick-start): Veda builds on | 
|  | `30` | `+` an x86-64 Linux machine with KVM, and the toolchain and the driver VM's | 
|  | `31` | `+` Linux are built once. | 
|  | `32` | `+` | 
|  | `33` | `+`## Making a change | 
|  | `34` | `+` | 
|  | `35` | `+` 1. **Branch** from an up-to-date `main` of your fork. | 
|  | `36` | `+` 2. **Make one change**, with its tests and documentation. In a new | 
|  | `37` | `+`   checkout, run a `cargo orchestration` command (such as `doctor`) before | 
|  | `38` | `+`   Cargo itself, so that Cargo builds the crates Veda patches | 
|  | `39` | `+`   ([Builds](documentation/DEVELOPING.md#builds)). | 
|  | `40` | `+` 3. **Iterate** on what you changed: | 
|  | `41` | `+` | 
|  | `42` | `+` ``` bash | 
|  | `43` | `+`   cargo test -p vnetstack                                           # one crate's unit tests, on the host | 
|  | `44` | `+`   cargo orchestration script verification/ui/firewall-question.vts  # one GUI script, headless | 
|  | `45` | `+`   cargo orchestration run --cmdline run=settings                    # boot with an application started | 
|  | `46` | `+` ``` | 
|  | `47` | `+` | 
|  | `48` | `+` 4. **Check everything** before you open a pull request: | 
|  | `49` | `+` | 
|  | `50` | `+` ``` bash | 
|  | `51` | `+`   cargo fmt --all --check         # formatting, as rustfmt.toml sets it | 
|  | `52` | `+`   cargo orchestration clippy      # Clippy over every crate as Veda builds it, warnings as errors | 
|  | `53` | `+`   cargo orchestration test --ui   # unit tests, systest inside Veda, then every GUI and agent script | 
|  | `54` | `+` ``` | 
|  | `55` | `+` | 
|  | `56` | `+`## Engineering standards | 
|  | `57` | `+` | 
|  | `58` | `+` Veda is an operating system: its code handles other programs' data and | 
|  | `59` | `+` people's files, and has to keep working when something around it fails. | 
|  | `60` | `+` Every change meets these standards; [Coding conventions](documentation/CODING.md) | 
|  | `61` | `+` has the detailed rules. | 
|  | `62` | `+` | 
|  | `63` | `+`### Security | 
|  | `64` | `+` | 
|  | `65` | `+`- **Trust nothing from outside the process.** Check IPC messages, files, | 
|  | `66` | `+`  network data and what people type before using them. Malformed input | 
|  | `67` | `+`  returns an error, never a panic. | 
|  | `68` | `+`- **Decide by identity.** A service gives each caller only what it needs, | 
|  | `69` | `+`  judged by the identity the registry gives each connection, which a | 
|  | `70` | `+`  process cannot forge ([Who may do what](documentation/NETWORKING.md#who-may-do-what) | 
|  | `71` | `+`  is an example). | 
|  | `72` | `+`- **Bound what others can grow.** Every queue, table and buffer that | 
|  | `73` | `+`  another process can fill has a limit, so that one process cannot starve | 
|  | `74` | `+`  the rest. | 
|  | `75` | `+`- **Fail closed.** Defaults are the safe choice (the firewall starts in | 
|  | `76` | `+`  stealth mode), and what is stored is checked again when it is read back. | 
|  | `77` | `+`- **Keep secrets secret.** Keys and passwords stay out of logs and the | 
|  | `78` | `+`  agent's state, and are never shown or returned once saved. | 
|  | `79` | `+`- **Proven cryptography.** Use RustCrypto and rustls, not code of your | 
|  | `80` | `+`  own; [Libraries](documentation/DEPENDENCIES.md) records each exception | 
|  | `81` | `+`  and why. | 
|  | `82` | `+`- **Leave consent to the system.** An application's agent actions declare | 
|  | `83` | `+`  their real risk and run the code the keyboard and mouse run | 
|  | `84` | `+`  ([Consent and safety](documentation/AGENT.md#consent-and-safety)). | 
|  | `85` | `+`- **` unsafe` only where nothing else will do,** each block with a | 
|  | `86` | `+` `// SAFETY:` comment saying why it is sound. | 
|  | `87` | `+` | 
|  | `88` | `+`### Reliability | 
|  | `89` | `+` | 
|  | `90` | `+`- **Expect failure.** Services restart when they crash, and the driver VM | 
|  | `91` | `+`  when its Linux does: a client reconnects and restores what the restart | 
|  | `92` | `+`  lost, as `vui` registers an application with the agent again. | 
|  | `93` | `+`- **Answer in time.** An application's frame never waits on slow work, | 
|  | `94` | `+`  which goes to a thread ([The `vui` toolkit](documentation/DEVELOPING.md#the-vui-toolkit)), | 
|  | `95` | `+`  and a call to a peer that may hang, such as a driver, has a deadline | 
|  | `96` | `+`  (`set_timeout`). | 
|  | `97` | `+`- **Say what failed.** Errors are a crate's own enum implementing | 
|  | `98` | `+` `Display`, in words a person can act on: what failed, and on what. | 
|  | `99` | `+` | 
|  | `100` | `+`### Code | 
|  | `101` | `+` | 
|  | `102` | `+`- **Proven libraries first.** Use a mature crate where one fits | 
|  | `103` | `+`  ([What a library must fit](documentation/DEPENDENCIES.md#what-a-library-must-fit)). | 
|  | `104` | `+`  A new dependency goes in `[workspace.dependencies]` with its reason; a | 
|  | `105` | `+`  library that is wrong becomes a port, and the fix goes upstream. | 
|  | `106` | `+`- **Write like the code around it**: its naming, comment density and | 
|  | `107` | `+`  idioms. What depends on the processor architecture stays in `arch/` | 
|  | `108` | `+`  ([Architectures](documentation/CODING.md#architectures)). | 
|  | `109` | `+`- **Explain why.** Public items have doc comments, every module a `//!` | 
|  | `110` | `+`  overview, and comments say why the code is as it is. | 
|  | `111` | `+`- **Keep a change whole and small.** No unrelated renames or reformatting | 
|  | `112` | `+`  beside a fix, and nothing left that the change made unused. | 
|  | `113` | `+`- **Mind the emulator.** Without KVM, QEMU runs Veda 5 to 20 times slower | 
|  | `114` | `+`  than native code: keep hot loops lean | 
|  | `115` | `+`  ([Performance](documentation/CODING.md#performance)), and measure what a | 
|  | `116` | `+` `perf` change claims, before and after. | 
|  | `117` | `+` | 
|  | `118` | `+`## Testing | 
|  | `119` | `+` | 
|  | `120` | `+` A change is finished when it is tested where it could break: | 
|  | `121` | `+` | 
|  | `122` | `+`\| What changed \| Test it with \| Run it with \| | 
|  | `123` | `+`\|--------------\|--------------\|-------------\| | 
|  | `124` | `+`\| Logic: parsing, protocols, state, maths \| Unit tests beside the code \| `cargo test -p <crate>` \| | 
|  | `125` | `+`\| The kernel, services, the POSIX layer, the standard library \| `systest`, and the C and Rust test programs \| `cargo orchestration test` \| | 
|  | `126` | `+`\| Applications, the shell, devices, recovery \| A GUI script in `verification/ui` \| `cargo orchestration script FILE` \| | 
|  | `127` | `+`\| What the agent does \| An agent script in `verification/agent` \| `cargo orchestration script FILE` \| | 
|  | `128` | `+` | 
|  | `129` | `+`- **A fix comes with the test that catches it,** checked to fail without | 
|  | `130` | `+`  the fix. | 
|  | `131` | `+`- **Deterministic and offline.** Tests talk to stand-ins (a server on the | 
|  | `132` | `+`  host, one for Deepgram, a video decoder, a microphone) and wait on log | 
|  | `133` | `+`  lines rather than fixed delays. What needs the real Internet or Deepgram | 
|  | `134` | `+`  goes in `verification/real/`, run by hand. | 
|  | `135` | `+`- **No flaky tests.** A test that fails now and then has a bug, in it or | 
|  | `136` | `+`  in the code: find it rather than retrying. | 
|  | `137` | `+`- **Break things on purpose.** Crashes, restarts and pulled cables have | 
|  | `138` | `+`  scripts, so that recovery is tested like any other feature. | 
|  | `139` | `+`- **A new crate with host tests** goes in `HOST_TESTED` | 
|  | `140` | `+`  (`orchestration/src/runner.rs`); a test fails until it is there. | 
|  | `141` | `+` | 
|  | `142` | `+`[Scripts and tests](documentation/DEVELOPING.md#scripts-and-tests) covers | 
|  | `143` | `+` the scripts, whose language `orchestration/src/script.rs` documents. | 
|  | `144` | `+` | 
|  | `145` | `+`## Documentation | 
|  | `146` | `+` | 
|  | `147` | `+`- **Update what you change.** A change to behaviour, a command, a protocol | 
|  | `148` | `+`  or a limit updates the document that describes it, in the same pull | 
|  | `149` | `+`  request. | 
|  | `150` | `+`- **Write as the documents do**: plain, precise British English in short | 
|  | `151` | `+`  sentences; tables for reference; commands, code and paths in backticks; | 
|  | `152` | `+`  a link rather than a repetition; no emojis. | 
|  | `153` | `+`- **Retake pictures with their scripts.** The README's screenshots come | 
|  | `154` | `+`  from `documentation/screenshots.vts`, Interceptor's from | 
|  | `155` | `+` `documentation/interceptor.vts`. | 
|  | `156` | `+` | 
|  | `157` | `+`## Commits | 
|  | `158` | `+` | 
|  | `159` | `+` Each commit message is one line: | 
|  | `160` | `+` | 
|  | `161` | `+```` text | 
|  | `162` | `+` type(scope): description | 
|  | `163` | `+```` | 
|  | `164` | `+` | 
|  | `165` | `+`- **type**: one of the table below. | 
|  | `166` | `+`- **scope**: what changed, as one lowercase word: a component (`kernel`, | 
|  | `167` | `+` `firewall`, `shell`, `drivervm`), or `repo` for the whole repository. | 
|  | `168` | `+`- **description**: imperative and lowercase ("add", not "added" or | 
|  | `169` | `+`  "adds"), without a full stop, the whole line 72 characters at most. | 
|  | `170` | `+`- **Nothing else**: no body or footer. The pull request explains. | 
|  | `171` | `+` | 
|  | `172` | `+`\| Type \| For \| | 
|  | `173` | `+`\|------\|-----\| | 
|  | `174` | `+`\| `feat` \| A new capability \| | 
|  | `175` | `+`\| `fix` \| A bug fix \| | 
|  | `176` | `+`\| `perf` \| Faster or smaller, behaving the same \| | 
|  | `177` | `+`\| `refactor` \| Restructured, behaving the same \| | 
|  | `178` | `+`\| `test` \| Tests alone \| | 
|  | `179` | `+`\| `docs` \| Documentation alone \| | 
|  | `180` | `+`\| `build` \| The build, the toolchain or the ports \| | 
|  | `181` | `+`\| `chore` \| Upkeep: removals, lint fixes, licence headers \| | 
|  | `182` | `+`\| `style` \| Formatting alone \| | 
|  | `183` | `+` | 
|  | `184` | `+```` text | 
|  | `185` | `+` feat(firewall): add a firewall that asks when an application listens | 
|  | `186` | `+` fix(videos): handle decoder restarts and lengthen vgl's fence wait | 
|  | `187` | `+` perf(glsl): preprocess shaders in linear time | 
|  | `188` | `+```` | 
|  | `189` | `+` | 
|  | `190` | `+` Every commit builds and passes the tests, so that `git bisect` works, and | 
|  | `191` | `+` the history stays linear: rebase on `main`, never merge it into your | 
|  | `192` | `+` branch. | 
|  | `193` | `+` | 
|  | `194` | `+`## Pull requests | 
|  | `195` | `+` | 
|  | `196` | `+` Open a pull request against `main` from a branch of your fork, and say: | 
|  | `197` | `+` | 
|  | `198` | `+`- **What and why**: the problem, and how the change solves it. | 
|  | `199` | `+`- **How you tested it**: the commands and scripts you ran, and what you | 
|  | `200` | `+`  could not test (hardware you do not have, say). | 
|  | `201` | `+`- **What it looks like**, for a visible change: a screenshot | 
|  | `202` | `+`  (`cargo orchestration shot`, or a script's `shot`). | 
|  | `203` | `+` | 
|  | `204` | `+` Before asking for a review: | 
|  | `205` | `+` | 
|  | `206` | `+`- [ ] `cargo fmt --all --check` and `cargo orchestration clippy` pass | 
|  | `207` | `+`- [ ] `cargo orchestration test --ui` passes | 
|  | `208` | `+`- [ ] New behaviour has tests, and a fix the test that catches it | 
|  | `209` | `+`- [ ] The documents that describe the change are up to date | 
|  | `210` | `+`- [ ] New files start with their licence header | 
|  | `211` | `+`- [ ] Commits follow the format, on an up-to-date `main` | 
|  | `212` | `+` | 
|  | `213` | `+` Reviews look at correctness and security first, then tests, clarity and | 
|  | `214` | `+` fit. Answer a question in the code when the next reader would ask it too | 
|  | `215` | `+`(a comment, a better name), and fold changes into the commits they belong | 
|  | `216` | `+` to rather than adding commits that fix earlier ones. Reviews are about the | 
|  | `217` | `+` code: be specific, and be kind. | 
|  | `218` | `+` | 
|  | `219` | `+`## Reporting a vulnerability | 
|  | `220` | `+` | 
|  | `221` | `+`> [!CAUTION] | 
|  | `222` | `+`> Never report a vulnerability in a public issue. | 
|  | `223` | `+` | 
|  | `224` | `+` Report it privately through GitHub's | 
|  | `225` | `+`[private vulnerability reporting](https://github.com/vahmoh25/Veda/security/advisories/new) | 
|  | `226` | `+`(the **Security** tab, **Report a vulnerability**): what you found, how to | 
|  | `227` | `+` reproduce it, and what it exposes. Where that button is missing, open an | 
|  | `228` | `+` issue that asks for a private contact, without details. | 
|  | `229` | `+` | 
|  | `230` | `+` A vulnerability is anything that crosses a boundary Veda draws: a process | 
|  | `231` | `+` reaching what its capabilities do not give it, a caller doing what its | 
|  | `232` | `+` identity does not allow, the agent acting without consent, traffic the | 
|  | `233` | `+` firewall should stop, or the driver VM reaching memory the IOMMU should | 
|  | `234` | `+` keep from it. | 
|  | `235` | `+` | 
|  | `236` | `+`## Licence | 
|  | `237` | `+` | 
|  | `238` | `+` Veda is under the [GNU General Public License, version 3](LICENSE) only. | 
|  | `239` | `+` By contributing, you license your contribution under it (or under the MIT | 
|  | `240` | `+` licence, for the driver VM's renderer, as [Licensing](documentation/LICENSING.md) | 
|  | `241` | `+` says). | 
|  | `242` | `+` | 
|  | `243` | `+`- **Every new file** starts with its SPDX header, with your name and the | 
|  | `244` | `+`  year the file is first published | 
|  | `245` | `+`  ([Licence headers](documentation/CODING.md#licence-headers) has the form | 
|  | `246` | `+`  for each kind of file): | 
|  | `247` | `+` | 
|  | `248` | `+` ``` rust | 
|  | `249` | `+` // SPDX-FileCopyrightText: © 2026 Your Name | 
|  | `250` | `+` // SPDX-License-Identifier: GPL-3.0-only | 
|  | `251` | `+` ``` | 
|  | `252` | `+` | 
|  | `253` | `+`  To a file you change substantially, you may add a line of your own | 
|  | `254` | `+`  below those there. `cargo orchestration test` checks every file. | 
|  | `255` | `+`- **Code from elsewhere is not copied in.** Third-party software is a port | 
|  | `256` | `+`  (`implementation/ports/`): its release, pinned by its SHA-256, with a | 
|  | `257` | `+`  small, explained patch | 
|  | `258` | `+`  ([Updating a port](implementation/ports/README.md#updating-a-port)), and | 
|  | `259` | `+`  its licence in [Licensing](documentation/LICENSING.md). |