docs: comprehensive README update with getting started guide#62
Open
EffortlessSteven wants to merge 2 commits into
Open
docs: comprehensive README update with getting started guide#62EffortlessSteven wants to merge 2 commits into
EffortlessSteven wants to merge 2 commits into
Conversation
…e index - README.md: updated features, hardware, sims, architecture, testing - docs/how-to/getting-started.md: build, run, configure quick start - docs/reference/crate-index.md: full crate reference by category Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the 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. 📒 Files selected for processing (3)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Review Summary by QodoComprehensive documentation update with README, getting started guide, and crate index
WalkthroughsDescription• Comprehensive README overhaul with features, hardware support, and architecture overview • New getting-started guide covering prerequisites, build, run, and configuration • Complete crate index reference organized by functional area • Added CI/MSRV/license badges and simulator/hardware compatibility tables Diagramflowchart LR
A["README.md<br/>Features & Architecture"] --> B["Documentation<br/>Structure"]
C["getting-started.md<br/>Build & Run Guide"] --> B
D["crate-index.md<br/>Crate Reference"] --> B
B --> E["User Onboarding<br/>& Reference"]
File Changes1. README.md
|
Code Review by Qodo
1.
|
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Comment on lines
+173
to
+174
| Place profiles in the configured profile directory (see `FLIGHT_PROFILE_PATH` | ||
| environment variable) and load them with `flightctl profile load`. |
There was a problem hiding this comment.
1. Flight_profile_path mismatch 🐞 Bug ✓ Correctness
The new getting-started guide documents FLIGHT_PROFILE_PATH, but the repo’s env-var invariants file (explicitly referenced as the complete list elsewhere) does not define it, creating conflicting setup instructions. Users following the guide will likely set a variable that the project doesn’t formally support/document centrally.
Agent Prompt
## Issue description
`docs/how-to/getting-started.md` introduces `FLIGHT_PROFILE_PATH`, but the repo’s env-var inventory (`infra/local/invariants.yaml`) does not define it, while other docs claim that inventory is the complete list.
## Issue Context
This PR adds a primary onboarding doc; inconsistent env-var guidance is high-friction for new users.
## Fix Focus Areas
- docs/how-to/getting-started.md[173-182]
- infra/local/invariants.yaml[8-20]
- docs/how-to/setup-dev-env.md[129-135]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
There was a problem hiding this comment.
Pull request overview
Documentation refresh for OpenFlight, adding a more complete top-level README plus user-facing reference/how-to docs to improve onboarding and navigation across the workspace.
Changes:
- Expanded
README.mdwith features, supported sims/hardware, architecture overview, testing pyramid, and links intodocs/. - Added a “Getting Started” how-to guide covering prerequisites, build/run commands, and initial configuration.
- Added a crate index reference doc grouping workspace crates by functional area.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| README.md | Reworked landing-page docs: badges, feature/support matrices, architecture/testing overview, and doc links. |
| docs/how-to/getting-started.md | New onboarding guide for building/running the daemon and using the CLI. |
| docs/reference/crate-index.md | New categorized index intended to enumerate all workspace crates. |
Comment on lines
+124
to
+129
| # Show active profile | ||
| cargo run -p flight-cli -- profile show | ||
|
|
||
| # Load a profile | ||
| cargo run -p flight-cli -- profile load my-profile.toml | ||
| ``` |
There was a problem hiding this comment.
flightctl does not have a profile load subcommand, and the CLI expects profile apply <path> (from a JSON file) rather than loading a .toml. Please update these example commands to match the actual flightctl profile subcommands (apply/activate/show/etc.) so new users can follow the guide successfully.
Comment on lines
+55
to
+60
| | Tool | Purpose | | ||
| |------|---------| | ||
| | `cargo-nextest` | Faster parallel test runner | | ||
| | `cargo-public-api` | API stability checks (`cargo xtask validate`) | | ||
| | `cargo-watch` | Automatic rebuild on save | | ||
| | `cargo-fuzz` | Fuzz testing protocol parsers | |
There was a problem hiding this comment.
The Markdown tables in this doc start rows with || ..., which renders as an extra empty first column in GitHub Markdown. Use a single leading | for each row (including the header/separator) so the tables render correctly.
Comment on lines
+24
to
+28
| | Crate | Description | | ||
| |-------|-------------| | ||
| | `flight-axis` | Axis processing engine — curves, deadzones, detents, mixers. Runs at 250 Hz. | | ||
| | `flight-scheduler` | Platform RT thread scheduling (MMCSS on Windows, rtkit on Linux). | | ||
| | `flight-bus` | Lock-free event bus for inter-component communication. | |
There was a problem hiding this comment.
These tables use || at the start of each row, which renders an unintended empty first column in GitHub Markdown. Switch to a single leading | for the header, separator, and each row so the table formats correctly.
Comment on lines
+29
to
+33
| | Simulator | Crate | Protocol | | ||
| |---|---|---| | ||
| | **Microsoft Flight Simulator** (MSFS 2020/2024) | `flight-simconnect` | SimConnect SDK | | ||
| | **X-Plane** (11/12) | `flight-xplane` | UDP + plugin | | ||
| | **DCS World** | `flight-dcs-export` | Export.lua | |
There was a problem hiding this comment.
The tables in this README (e.g., Supported Simulators / ADR list / Workspace Crates / Testing) start rows with ||, which renders as an extra empty first column in GitHub Markdown. Use a single leading | for proper table formatting.
|
|
||
| [](https://github.com/EffortlessMetrics/OpenFlight/actions) | ||
| [](https://www.rust-lang.org) | ||
| [](LICENSE-MIT) |
There was a problem hiding this comment.
The license badge text indicates dual licensing (MIT/Apache-2.0) but the badge link points only to LICENSE-MIT. Consider linking the badge to a neutral location (e.g., the License section or a combined licensing doc) or to both license files to avoid implying MIT-only.
Suggested change
| [](LICENSE-MIT) | |
| [](#license) |
Comment on lines
+141
to
+142
| `compat/manifests/devices/` by vendor/product ID. The manifest defines axis | ||
| counts, button maps, and FFB capabilities. |
There was a problem hiding this comment.
The path compat/manifests/devices/ referenced here doesn’t exist in the repo; device compatibility/manifests appear to live under compat/devices/ (and compat/compatibility.json). Please update this path so readers can actually find the manifests you’re describing.
Suggested change
| `compat/manifests/devices/` by vendor/product ID. The manifest defines axis | |
| counts, button maps, and FFB capabilities. | |
| `compat/devices/` (indexed by `compat/compatibility.json`) by vendor/product ID. | |
| The manifest defines axis counts, button maps, and FFB capabilities. |
Comment on lines
+156
to
+170
| ```toml | ||
| [metadata] | ||
| name = "My First Profile" | ||
| simulator = "msfs" | ||
|
|
||
| [axes.roll] | ||
| curve = "linear" | ||
| deadzone = 0.03 | ||
| sensitivity = 1.0 | ||
|
|
||
| [axes.pitch] | ||
| curve = "scurve" | ||
| deadzone = 0.05 | ||
| sensitivity = 0.8 | ||
| curvature = 0.3 |
There was a problem hiding this comment.
This section says profiles are TOML files and the example is TOML, but existing documentation and the CLI describe profiles as JSON (e.g., flightctl profile apply <file>.json). Please align the file format and example here with the current profile schema/serialization used by the codebase to avoid conflicting guidance.
Suggested change
| ```toml | |
| [metadata] | |
| name = "My First Profile" | |
| simulator = "msfs" | |
| [axes.roll] | |
| curve = "linear" | |
| deadzone = 0.03 | |
| sensitivity = 1.0 | |
| [axes.pitch] | |
| curve = "scurve" | |
| deadzone = 0.05 | |
| sensitivity = 0.8 | |
| curvature = 0.3 | |
| ```json | |
| { | |
| "metadata": { | |
| "name": "My First Profile", | |
| "simulator": "msfs" | |
| }, | |
| "axes": { | |
| "roll": { | |
| "curve": "linear", | |
| "deadzone": 0.03, | |
| "sensitivity": 1.0 | |
| }, | |
| "pitch": { | |
| "curve": "scurve", | |
| "deadzone": 0.05, | |
| "sensitivity": 0.8, | |
| "curvature": 0.3 | |
| } | |
| } | |
| } |
Comment on lines
+173
to
+183
| Place profiles in the configured profile directory (see `FLIGHT_PROFILE_PATH` | ||
| environment variable) and load them with `flightctl profile load`. | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| | Variable | Default | Description | | ||
| |----------|---------|-------------| | ||
| | `RUST_LOG` | `info` | Logging level (`trace`, `debug`, `info`, `warn`, `error`) | | ||
| | `FLIGHT_CONFIG_PATH` | Platform default | Path to configuration directory | | ||
| | `FLIGHT_PROFILE_PATH` | Platform default | Path to profile directory | | ||
|
|
There was a problem hiding this comment.
FLIGHT_PROFILE_PATH is documented here, but it doesn’t appear in the repo’s environment-variable inventory (e.g., infra/local/invariants.yaml) or the local docker-compose env vars. If profiles live under FLIGHT_CONFIG_PATH, consider documenting that instead; otherwise add/define FLIGHT_PROFILE_PATH consistently across tooling and docs.
Suggested change
| Place profiles in the configured profile directory (see `FLIGHT_PROFILE_PATH` | |
| environment variable) and load them with `flightctl profile load`. | |
| ## Environment Variables | |
| | Variable | Default | Description | | |
| |----------|---------|-------------| | |
| | `RUST_LOG` | `info` | Logging level (`trace`, `debug`, `info`, `warn`, `error`) | | |
| | `FLIGHT_CONFIG_PATH` | Platform default | Path to configuration directory | | |
| | `FLIGHT_PROFILE_PATH` | Platform default | Path to profile directory | | |
| Place profiles under your configuration directory (by default | |
| `$FLIGHT_CONFIG_PATH/profiles`) and load them with `flightctl profile load`. | |
| ## Environment Variables | |
| | Variable | Default | Description | | |
| |----------|---------|-------------| | |
| | `RUST_LOG` | `info` | Logging level (`trace`, `debug`, `info`, `warn`, `error`) | | |
| | `FLIGHT_CONFIG_PATH` | Platform default | Path to the configuration directory (profiles, rules, etc.) | |
|
|
||
| # Crate Index | ||
|
|
||
| Complete reference for every workspace crate in OpenFlight, grouped by |
There was a problem hiding this comment.
The introduction claims this is a complete reference for every workspace crate, but at least flight-psx is a workspace member (Cargo.toml includes crates/flight-psx) and is not listed below. Either add the missing crates (and keep this index in sync) or soften the claim to avoid being misleading.
Suggested change
| Complete reference for every workspace crate in OpenFlight, grouped by | |
| Reference index for the documented workspace crates in OpenFlight, grouped by |
| - Panel and control hardware: `flight-panels`, `flight-panels-core`, `flight-panels-saitek`, `flight-panels-cougar`, `flight-hotas-saitek`, `flight-hotas-thrustmaster`, `flight-streamdeck` | ||
| - Safety, diagnostics, and observability: `flight-ffb`, `flight-watchdog`, `flight-blackbox`, `flight-tracing`, `flight-metrics`, `flight-tactile` | ||
| - Persistence and platform integration: `flight-writers`, `flight-updater`, `flight-security`, `flight-process-detection`, `flight-replay` | ||
| OpenFlight ships device manifests for **2 200+** controllers, sticks, yokes, pedals, throttles, and panels. See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the full device matrix with tier ratings and test coverage. |
There was a problem hiding this comment.
2 200+ is an unusual number format in English and can be misread. Consider using 2,200+ (or 2200+) for clarity.
Suggested change
| OpenFlight ships device manifests for **2 200+** controllers, sticks, yokes, pedals, throttles, and panels. See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the full device matrix with tier ratings and test coverage. | |
| OpenFlight ships device manifests for **2,200+** controllers, sticks, yokes, pedals, throttles, and panels. See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the full device matrix with tier ratings and test coverage. |
- License badge now links to #license section instead of LICENSE-MIT - Fix number format: 2 200+ -> 2,200+ - Replace non-existent flightctl profile load with profile apply - Convert TOML profile example to JSON (matches codebase format) - Fix device manifest path: compat/manifests/devices/ -> compat/devices/ - Replace non-existent FLIGHT_PROFILE_PATH with FLIGHT_CONFIG_PATH - Soften crate-index intro from 'complete reference' to 'reference index' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
CI Feedback 🧐A test triggered by this PR failed. Here is an AI-generated analysis of the failure:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation update for OpenFlight.
Changes