--- title: "Contributing" --- > Documentation Index > Fetch the complete documentation index at: https://openarkstudio.github.io/arknet/llms.txt > Use this file to discover all available pages before exploring further. # Contributing Develop arknet as an independent header-only project. Keep protocol behavior, IO ownership and public contracts reviewable through focused changes and reproducible checks. ## Directory Map | Directory | Responsibility | | --- | --- | | `include/arknet/base/` | IO scheduling, lifecycle, event queues and reusable components | | `include/arknet/tcp/` | TCP and TLS stream endpoints | | `include/arknet/udp/` | UDP clients, servers, sessions and cast | | `include/arknet/http/` | HTTP/HTTPS, routing and WebSocket implementation | | `include/arknet/websocket/` | Public WebSocket headers | | `include/arknet/external/` | Asio and Beast provider integration | | `tests/` | doctest cases, integration checks, stress tests and test certificates | | `benchmarks/` | Callback/coroutine benchmark programs, matrix runner and report tools | | `examples/` | Small applications demonstrating public APIs | | `docs/` | English and Chinese Markdown, Nimbus site and performance reports | | `cmake/` | Dependency discovery and installed-package configuration | ## Code Style `.clang-format` defines the C++ style: four-space indentation, Allman braces and a 120-column limit. Group includes as system libraries, third-party libraries and project headers, with a blank line between groups and names sorted within each group. Public project headers precede local headers; `windows.h` precedes system headers that depend on it. Keep conditional compilation and configuration macros in their required order. `.editorconfig` defines UTF-8, LF line endings and editor indentation. Use clang-format 18 to match CI. ```sh # Check formatting; --fix applies it. CLANG_FORMAT=clang-format-18 bash scripts/format.sh --check CLANG_FORMAT=clang-format-18 bash scripts/format.sh --fix ``` On macOS, install LLVM 18 with `brew install llvm@18` and set `CLANG_FORMAT="$(brew --prefix llvm@18)/bin/clang-format"`. On Ubuntu 24.04, install `clang-format-18`. On Windows, use LLVM 18 and run the script in Git Bash. If `clang-format` already resolves to version 18, omit `CLANG_FORMAT`. The script checks project headers, tests, examples and benchmark C++ sources. It excludes bundled Boost headers, doctest and historical measurement snapshots. CI runs the same check. Formatting tools are development dependencies only. ## Build and Run Tests See [Install and Configure](/arknet/get-started/installation) for dependency setup. From the repository root, build a development configuration and run the repository check target: ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DARKNET_ENABLE_SSL=ON \ -DARKNET_USE_BOOST_ASIO=OFF -DARKNET_ASIO_INCLUDE_DIR=/path/to/asio/include cmake --build build --parallel 3 cmake --build build --target arknet_check ``` Functional tests use vendored doctest and are development-only dependencies. `arknet_check` runs functional programs, stress checks and installed-package consumption directly. When benchmarks are enabled, it also runs their smoke cases. Per-program logs are under `build/tests/logs/`. This target does not use CTest. Run an individual executable for focused development: ```sh build/tests/arknet_tcp_test --list-test-cases build/tests/arknet_tcp_test --test-case="*framing*" build/tests/arknet_tls_test --reporters=junit --out=build/tls.xml ``` For Visual Studio and other multi-configuration generators, add `--config Debug` to the CMake build commands and use the generated configuration subdirectory and `.exe` executable names. Add tests that reproduce a behavior or failure, including completion counts and shutdown where applicable. Use explicit synchronization and bounded waits for asynchronous assertions. Shared component or provider changes need coverage across both providers, TLS on/off and owned/external IO where affected. Run sanitizers for lifetime and concurrency changes; run benchmark programs in separate Release builds. The current checked configurations and remaining coverage are recorded in [Testing](/arknet/project/testing). ## Benchmark and Report Changes Benchmark sources belong in `benchmarks/` and remain runnable by library users. Keep them independent of doctest. Compare identical hardware, dependencies, compiler settings and workloads; do not run benchmarks alongside builds or other tests. The standard procedure, command options and measurement definitions are in [Methodology](/arknet/performance/methodology). [IO Models](/arknet/concepts/io-models) explains shared-context and sharded-context comparisons, including native Asio coroutine workloads. The optional report generator's packages are listed in `benchmarks/requirements-report.txt`. Retain raw JSON, exact commands, host metadata, source revision and binary hashes with a report. Separate short smoke checks from performance evidence. Do not infer production capacity from loopback throughput or compare callback message RTT with coroutine batch RTT as if they were the same metric. ## Documentation and Commit History Every documentation page has an English and Chinese version. The Nimbus page header provides the language dropdown. Update both versions together. Keep examples, commands, defaults, limitations and status equivalent. Place detailed material under `docs/` and keep the root README concise. New pages also need navigation entries and working relative links on the static site and on GitHub. Organize documentation into Overview, Get started, Concepts, Features, Guides, Examples, Reference, Performance and Project. Concepts explain behavior and constraints; guides complete one task with steps and a verifiable result; reference pages specify exact interfaces and defaults; performance pages retain measurement conditions, charts and raw data. Each protocol has overview, server, client, configuration and performance pages. Link to shared mechanisms rather than maintaining duplicate explanations. Edit the Markdown sources under `docs/`. The build in `docs/site/` generates localized pages, syntax highlighting, search, SVG assets, clean per-page Markdown, `llms.txt` and `llms-full.txt`. Generated content is ignored by Git. Node.js 22.12+ is required only to build or preview documentation: ```sh cd docs/site npm ci npm run dev -- --host 127.0.0.1 --port 8767 npm run check ``` The local URL includes `/arknet/`, matching the GitHub Pages base path. `npm run check` checks the content conversion, Astro types, build output, internal page links, anchors, SVG paths and AI reading endpoints. The language dropdown preserves the current page; legacy Docsify hash links still redirect. Keep `@cloudflare/nimbus-docs` pinned and review starter updates before upgrading. Use Nimbus's `` with `` for sequential tasks, and `