Commit Graph
24 Commits
Author SHA1 Message Date
Michael FritscheandHamish Willee e4212fe915 docs(concept): add navigation terminology page (#29347)
* docs(concept): add navigation terminology page

Heading, course, track, bearing and drift have caused friction because
aviation and marine navigation use the same words with different
meanings, and PX4 code mixes both. Collect the official ICAO, FAA,
Bowditch, IHO and NMEA definitions in one place, together with the
reference frames, a precedence rule for conflicting terms, and a
separate section for where PX4 represents things differently (radians,
local map projection, signed cross-track error, wind vectors, deviating
field names), so that new code sticks to the official terminology.

Graphics are placeholders for now.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(concept): add ground vehicle terms to navigation terminology

ISO 8855 and SAE J670 reuse navigation words with different meanings:
the course angle is the actual direction of motion, and the vehicle
sideslip angle is ground-referenced, unlike the aerodynamic one. Add
the ground vehicle standards as a source, extend the precedence rule
and conflicts table, cover the z-up vehicle frames, and list the rover
names that use "bearing" for a course setpoint.

Also tone down the boat statement in the intro, as boat support is
still minimal.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* Add ground vehicle references

* fix(docs): add navigation nomenclature overview

* fix(docs): hide not yet used nomenclature

* feat(docs): navigation docs update overview image

* feat(docs): split navigation terminology doc into main and advanced page

* feat(docs): navigation terminology update overview image

* fix(docs): navigation terminology clarify heading and desired track definitions

* fix(docs): clean up navigation terminology tab

* fix(docs): clean up navigation_terminology.md

* fix(docs): clean up navigation_terminology_advanced.md

* fix(docs): correct navigation terminology field and range claims

position_controller_status.nav_bearing and xtrack_error have had no
producer since the fixed-wing position controller rework, so
NAV_CONTROLLER_OUTPUT forwards zeros; say so instead of describing
them as live values. Not all uORB angles are wrapped to [-pi, pi]
(transponder_report.heading is [0, 2pi]), Ackermann and differential
rovers use bearing_setpoint as a heading setpoint, and
estimator_innovations.beta is an innovation, not the sideslip angle.

Drop the FLU to FRD conversion note, which was wrong for ROS yaw and
does not belong on a terminology page, replace the caption of the
missing track frame figure with a TODO, and apply prettier.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(concept): update navigation_terminology page

* docs(concept): navigation terminology add course / course setpoint distinction vs course / course over ground

* docs(concept): navigation terminology - add detail images

* docs(concept): fix navigation terminology review findings

Fix issues found in review of the navigation terminology pages:

- Figures: make the SVGs visible in dark mode, draw the course setpoint
  pointing back towards the desired track (as NPFG commands it) rather
  than along it, match the track's end direction to the course, add an
  illustrative future track, and fix clipped and mis-spaced labels.
- Links: avoid in-page links into the collapsed details block, link the
  summary table fields and first uses of estimator, NPFG, pure pursuit
  and mecanum rovers.
- Accuracy: MAVLink headings are in centidegrees, the bearing example is
  the current (not next) waypoint, magnetometer calibration is applied
  by the sensors module, and only Ackermann/mecanum use bearing_setpoint.
- Style: rename "the norms" to "official definitions", remove casual
  bold emphasis, fix heading levels, British spelling, and one sentence
  per line.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>

* docs(concept): apply suggestion on px4 path follow computation

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* docs(concept): pull user-facing notes from advanced navigation terminology

Readers operating, tuning or reading logs should not need the advanced
page, so add the rover reversing case, the sideslip/drift naming hint,
and the user-facing names that don't match the terminology.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(concept): split local frame into tangent-plane and navigation frames

Local positions are a projection in the tangent-plane frame at the
estimator origin, while velocities and attitude are relative to the
north-east-down frame at the vehicle. Describe both, keeping the main
page short and the details on the advanced page.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(agents): point to navigation terminology before naming nav fields

Keep new code, uORB fields, parameters and docs from drifting away from
the agreed heading/course/track/bearing definitions again.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(concept): address review comments by mbjd

---------

Signed-off-by: Michael Fritsche <frimi999@gmail.com>
Signed-off-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
2026-11-10 10:12:17 +01:00
Ramon Roche bf6603b42b docs(ci): document the AI pull request review (#28989)
* docs(ci): document the AI pull request review

Adds an "AI Pull Request Review" page under Platform Testing and CI:
who can use it, the !ai-review command and its options, what a review
contains, cost, how it works and its trust model, and where to change
it. It is marked as a trial. The maintainers page lists the new
permission during onboarding, and the AI coding assistants page tells
contributors how to treat an AI review on their PR.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* docs(ci): mention the AI review check on the PR

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* docs(ci): correct the AI review options and re-run behaviour

The model and effort options only change the first pass; the confirming pass always runs Opus at high. A re-run collapses the old summary but leaves its inline comments, and the command only works on open PRs.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Ramon Roche <mrpollo@gmail.com>

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
2026-10-12 00:17:03 +11:00
Jacob Dahl d5223850dd docs(contributing): discourage force-pushing during review (#28931)
* docs(contributing): discourage force-pushing during review

A force-push after review has begun erases the commits a reviewer has read, so they cannot see what changed since. The guidance told contributors to squash and reword instead, which contradicts the commit and pr agent skills. PRs are typically squash-merged, so branch history does not need cleaning up before merge.

Assisted-by: Claude:claude-fable-5-1
Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com>

* ci(workflows): remove commit message check

PRs are squash-merged under the PR title, which is still checked. Flagging the individual commits pushed contributors to rewrite history mid-review.

Assisted-by: Claude:claude-fable-5-1
Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com>

---------

Signed-off-by: Jacob Dahl <dahl.jakejacob@gmail.com>
2026-09-30 11:04:19 -06:00
Hamish Willee 1340559f07 Update contribution guidelines for content formatting (#28389)
Clarified guidelines for content formatting and line breaks.
2026-08-26 16:27:39 +10:00
Hamish Willee 8ed15e6b19 docs(docs): Fix broken external links (#28300)
* docs(docs): Fix external links and associated tidy
* docs(docs): Fix up sidebar discontinued convention
* docs(docs): Fix up alternate sidebar
2026-08-20 11:53:24 +10:00
Ramon Roche a2f1bb7c34 docs(contribute): add AI coding assistant policy
Adopt a policy for AI-assisted contributions modeled on the Linux
kernel's coding-assistants document: the human submitter is the author
and accountable for every line, an AI tool never appears in authorship
or Signed-off-by tags, licensing follows the LF Generative AI Policy,
and disclosure via an Assisted-by trailer is required.

Summarize the policy in CONTRIBUTING.md and add it to the docs sidebar.
The commit and pr skills keep their disclosure and sign-off rules but do
not link the policy: files loaded into every agent session are standing
context, not rules applied on demand, so pointing at the policy from
there invites agents to pull it in and biases unrelated work.

Assisted-by: Claude:claude-opus-4-8[1m]
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
2026-07-23 09:44:46 -07:00
Hamish Willee 96e760a782 docs(docs): Fix almost all broken external links (#27790)
* docs(docs): Add missing uorb topics sidebar
* docs(docs): discontinue cuav v5 plus/nano
* docs(docs): Fix 404 and 303 status HTTP links
* docs(docs): more link fixes
* update(drivers): Docs fix to fix up link
* docs(docs): Fix up all remaining  broken links and add exclusions
2026-07-02 16:58:40 +10:00
Hamish Willee b3fbf37fae ci(docsorchestrator): Update to latest markdown link checker and link fixes (#27098) 2026-04-16 13:39:28 +10:00
Hamish Willee 71fffb0a42 docs(fix): Revert the link to dev call (#27090) 2026-04-15 17:48:21 +10:00
Hamish Willee 28aeb36637 docs(fix): broken link (#27067) 2026-04-14 07:51:33 +10:00
Ramon Roche 4e5c0fac7a docs(maintainers): introduce Code Owner and Reviewer maintainer types (#27010)
Split the maintainer role into two types to make it easier to grow the
bench without asking new contributors to commit to a specific component
up front. Code Owners keep their existing scoped responsibility for a
category, while Reviewers help across the project without ownership of
any specific area. Both are full maintainers, share the @PX4/dev-team
GitHub team, and have the same write access and voting rights.

Rename the Active Maintainers table to Code Owners with no change to
the current roster. Add an empty Reviewers table so future nominations
land in their own PRs. Update the contributor docs to describe the two
types, cover both in the recruitment and onboarding flow, and note the
promotion path from Reviewer to Code Owner.

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
2026-04-08 12:06:29 -07:00
Ramon Roche b243398231 feat(build): add SPDX 2.3 SBOM generation for builds (#26731) 2026-03-31 17:06:51 -06:00
Ramon Roche 4da97eb4fd ci(workflows): add commit message and PR title quality checks
Add CI enforcement of conventional commit format for PR titles and
commit messages. Includes three Python scripts under Tools/ci/:

- conventional_commits.py: shared parsing/validation library
- check_pr_title.py: validates PR title format, suggests fixes
- check_commit_messages.py: checks commits for blocking errors
  (fixup/squash/WIP leftovers) and advisory warnings (review-response,
  formatter-only commits)

The workflow (.github/workflows/commit_checks.yml) posts concise
GitHub PR comments with actionable suggestions and auto-removes them
once issues are resolved.

Also updates CONTRIBUTING.md and docs with the conventional commits
convention.

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
2026-03-06 17:51:54 -08:00
Hamish Willee b37733459d docs: Codespell check on English sources + swd fixes (#26657) 2026-03-05 12:50:59 +11:00
Hamish Willee ab318cb636 docs: Update local build instructions to include metadata building (#26654) 2026-03-05 11:39:50 +11:00
Hamish Willee 209c971c1b docs: Link fixes in docs - including 404 fixes (#26605)
* Redirect 301/308 HTTP link fixes
* Easy 404 fixes - easy
* Add internal anchor fixes and generate msg docs fix
2026-02-28 17:09:53 +11:00
Hamish Willee c0af8b9952 docs: Link fixes such as 301 redirects (#26586) 2026-02-26 18:33:37 +11:00
Hamish Willee 4c184f309c docs: Max code line length 140 chars (#26368) 2026-01-29 13:43:22 +11:00
Hamish Willee 5d5e23bcfa [Docs] Fix links and tidy config (#25184)
* Fix links and tidy config

* Add updated lock files
2025-07-10 16:11:58 +10:00
Hamish Willee 2c31e2bad5 Fix all possible HTTP to HTTPS docs links (#25153) 2025-07-03 18:09:58 +10:00
Hamish Willee 375f421c61 Link fixes galore (#25151) 2025-07-03 14:53:12 +10:00
Abhishek ChoithaniandHamish Willee effcb32a3e Contibuting to docs - open editor on linux (#24907)
* Update docs.md

Tested on Ubuntu

* Fix layout

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
2025-05-28 11:39:23 +10:00
Hamish Willee 27ff547e07 Updates linkchecker and fixes up the doc contribution sections (#24660)
* Update yarn linkchecker

* Fix edit page links. Fix contribution pages
2025-04-03 12:41:56 +11:00
Hamish WilleeandRamon Roche 88d623bedb Move PX4 Guide source into /docs (#24490)
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
2025-03-13 16:08:27 +11:00