| |
| | 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 has the commands in |
| | 9 | + full, Coding conventions the rules the code |
| | 10 | + follows, and Architecture the design. |
| | 11 | + |
| | 12 | +Contents: Before you start · Making a change · Engineering standards · Testing · Documentation · Commits · Pull requests · Reporting a vulnerability · 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. |
| | 28 | + |
| | 29 | + To set up, follow the 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). |
| | 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 |
| | 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 |
| | 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 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). |
| | 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), |
| | 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). |
| | 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). |
| | 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), 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 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 thatgit bisectworks, and | | |191|+the history stays linear: rebase onmain, never merge it into your | | | 192|+branch. | | |193|+| | |194|+## Pull requests | | | 195|+| | |196|+Open a pull request againstmainfrom 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 --checkandcargo orchestration clippypass | | |207|+- [ ] cargo orchestration test --uipasses | | |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 testchecks 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. |
Give Your Python Agent Memory in Ten Lines