Veda, the First Agentic Hobby OS Needs Contribution Veda, described as the first agentic hobby operating system, has published a contribution guide asking developers to help build the project. The guide, released under GPL-3.0-only by copyright holder Vahid Mohammadi, requires contributors to build on an x86-64 Linux machine with KVM and to run `cargo orchestration` commands such as `doctor`, `clippy`, and `test --ui` before opening a pull request. Contributors must branch from an up-to-date `main` of their fork, make one change with its tests and documentation, and report vulnerabilities privately rather than in an issue. | | | | 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