Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PX4 Core Components & Release Workflows #3443

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+199 −1
Open

PX4 Core Components & Release Workflows #3443

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
55b5ffa
releases: defines the release workflow for PX4
junwoo091400 Mar 7, 2023
3dc00a5
Fix up table
hamishwillee Nov 13, 2024
dd6365f
Subedit of release stuff
hamishwillee Nov 13, 2024
4b6582d
Update en/concept/core_components.md
hamishwillee Jan 28, 2025
d8fe59a
Update en/concept/core_components.md
hamishwillee Jan 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions en/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -433,6 +433,7 @@
- [Writing your First Application](modules/hello_sky.md)
- [Application/Module Template](modules/module_template.md)
- [Concepts](concept/index.md)
- [PX4 Core Components](concept/core_components.md)
- [PX4 System Architecture](concept/px4_systems_architecture.md)
- [PX4 Flight Stack Architecture](concept/architecture.md)
- [Controller Diagrams](flight_stack/controller_diagrams.md)
Expand Down
91 changes: 91 additions & 0 deletions en/concept/core_components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# PX4 Core Components

These "core components" define the core functionality of PX4-Autopilot.

They are tested in continuous integration tests and are regularly monitored and tested by their maintainers.
Core components are the first priority in stable point releases.

## Core component criteria

Each core component must have:

- Maintainer
- Tester
Comment on lines +12 to +13
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is desirable, but we haven't had a maintainer for MacOS forever, and many of these others too. So perhaps something less "must" ish

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, who is this tester?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there's no maintainer for a given component, we need to make sure it's clearly marked somewhere. Same for testers.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense. I'm assuming you'll keep working on this until it is ready to merge then.


## PX4 Core Components List

For many of the core components that has a corresponding label in Github, you can click on them to view the relevant Issue/PRs.

| Core component (category) | Sub component | Maintainer |
| ---------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------ |
| [uORB (Architecture)][uORB (Architecture)] | | |
| [Parameter (Architecture)][Parameter (Architecture)] | | |
| Realtime Clock (Architecture) | | |
| Work queue (Architecture) | | |
Comment on lines +21 to +24
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO all of these are subcomponets of "architecture", owned by either/both Beat and Daniel.

| GNSS (State Estimation) | Velocity / Position | |
| | Heading | |
| [Optical flow (State Estimation)][Optical flow (State Estimation)] | | |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is probably a subset of estimation, not its own thing.

| [Vision][Vision] (State Estimation) | | |
| [Boards (NuttX)][Boards (NuttX)] | [Pixhawk standard][Pixhawk standard] | |
| IMU (Driver) | | |
| Distance Sensor (Driver) | | |
| Failure Injection (?) | | |
| RTK GPS (Driver) | Heading estimate from dual RTK GPS | [Alex Klimaj](https://github.com/AlexKlimaj) |
| [Documentation][Documentation] | PX4, MAVLink, QGC, MAVSDK | [Hamish Willee](https://github.com/hamishwillee) |
| Battery (Library) | | |
| Flight Task (Library) | | [Matthias Grob](https://github.com/MaEtUgR) |
| Matrix (Library) | | |
| Autotuning (Library) | | |
| [Github Actions (Continuous Integration)][Github Actions (Continuous Integration)] | | |
| [Jenkins (Continuous Integration)][Jenkins (Continuous Integration)] | | |
| Linux (Toolchain) | | |
| Mac OS (Toolchain) | | |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mrpollo Are you populating the list of maintainers here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes thats the idea

| [Windows (Toolchain)][Windows (Toolchain)] | | |
| [ROS2][ROS2] | | |
| [Gazebo Classic (Simulation)][Gazebo Classic (Simulation)] | | |
| [Gazebo (Simulation)][Gazebo (Simulation)] | | |
| Flightgear (Simulation) | | |
| JSBSim (Simulation) | | |
| jMAVSim (Simulation) | | |
| SIH (Simulation) | | |
Comment on lines +47 to +50
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The are all community maintained. I think it might be worth listing these separately. Only SIH has a maintainer, of sorts.

Suggested change
| Flightgear (Simulation) | | |
| JSBSim (Simulation) | | |
| jMAVSim (Simulation) | | |
| SIH (Simulation) | | |

| Multivehicle Simulation | | |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a feature of a simulation type as I understand it, so would be a sub set of gazebo (say).

| [MAVLink (Communication)][MAVLink (Communication)] | | |

[uORB (Architecture)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3AUorb+
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note, I pulled all the links out to make this table editable. This works better with automatic prettiering.

[Parameter (Architecture)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3AParameter+
[Documentation]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Documentation+%F0%9F%93%91%22
[Optical flow (State Estimation)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Optical+flow+%F0%9F%91%81%EF%B8%8F%E2%80%8D%F0%9F%97%A8%EF%B8%8F%22
[Vision]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3Avision
[Boards (NuttX)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Boards+%28flight+controller%29+%F0%9F%8D%AB%22+
[Pixhawk standard]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3Apixhawk
[MAVLink (Communication)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Communication+%28MAVLink%29+%F0%9F%93%A1%22
[Github Actions (Continuous Integration)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22CI+%F0%9F%A4%96%22
[Jenkins (Continuous Integration)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3Ajenkins-ci
[Windows (Toolchain)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3Awindows
[ROS2]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3AROS2
[Gazebo Classic (Simulation)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22gazebo+classic%22
[Gazebo (Simulation)]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3Agazebo

### Vehicle types

| Core component | Sub component | Maintainer |
| -------------------------- | --------------------------------------------------------------- | ---------- |
| [Multirotor][Multirotor] | Acro mode | |
| | Stabilized mode | |
| | |
| [Fixed wing][Fixed wing] | |
| [Hybrid VTOL][Hybrid VTOL] | |
| | Altitude mode in hover |
| | Position mode in hover |
| | Auto mode in hover | |
| | Quad-chute | |
| | Pull/Tilter assist for forward acceleration in hover | |
| | Weather vane (automatically aligning vehicle heading into wind) | |
| [Boat][Boat] | | |
| [Rover][Rover] | Ackermann, Differential | |

[Multirotor]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Multirotor+%F0%9F%9B%B8%22
[Fixed wing]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Fixed+Wing+%F0%9F%9B%A9%EF%B8%8F%22
[Hybrid VTOL]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Hybrid+VTOL+%F0%9F%9B%A9%EF%B8%8F%F0%9F%9A%81%22
[Boat]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Boat+%F0%9F%9A%A4%22
[Rover]: https://github.com/PX4/PX4-Autopilot/issues?q=label%3A%22Rover+%F0%9F%9A%99%22
108 changes: 107 additions & 1 deletion en/releases/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Releases

A list of PX4 release notes, they contain a list of the changes that went into each release, explaining the included features, bug fixes, deprecations and updates in detail.
## Release Notes

The release notes archive for each release contains a detailed list of included features, bug fixes, deprecations, and updates.

- [main](../releases/main.md) (changes since v1.15)
- [v1.15](../releases/1.15.md)
Expand All @@ -9,3 +11,107 @@ A list of PX4 release notes, they contain a list of the changes that went into e
- [v1.12](../releases/1.12.md)

The full archive of releases for the PX4 autopilot project can be found on [GitHub](https://github.com/PX4/PX4-Autopilot/releases)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the rest of the maintainers are happy with this, so am I.

One concern is that there are no time-frames for expectations. Now I know we can't say to a maintainer, you will have tested and fixed all issues by next week, but we can say something like "the intent is that we'll converge within 2 months to a candidate in which only critical issues will be fixed, and 3 months for release from branch-off. Maintainers and tested are therefore expected to report on their progress to these goals" (or similar). Something that ties accountability.

## Release Versioning

The PX4 project is using a versioning scheme based on the semantic versioning system ([Wikipedia article](https://en.wikipedia.org/wiki/Software_versioning)).
The current scheme is as follows:

```plain
major.minor.patch[-beta#]
```

:::info
Full semantic versioning will be adopted starting from `v2.0.0`.
The releases before that don't follow the strict Semantic versioning process.
Before `v2.0` it is assumed bumps in `minor` are considered to be `Major` releases.
:::

- Change in `major`: Breaking changes in functionality
- Change in `minor`: New non-breaking changes and features
- Change in `patch`: All other non-breaking changes including bugfixes

## Release Schedule

PX4 follows the following release schedule:

- `Major` or `minor` releases: Roughly every 6 months
- `patch` releases: When critical bug-fix / hardware support is needed
- `beta` releases: Every 1 week during beta testing phase

## Stakeholders

The whole process depends on the contribution of the maintainers.
However, for the release process specifically, a 'Release manager' (referred below as well) will be the person in charge of overseeing the overall process.

## Release Procedure

The decision on whether the upcoming release will involve a change in major version, or just a minor will be discussed during the [weekly coordination meeting](../contribute/dev_call.md).

If the general consensus agrees that the change for the upcoming release is big enough, the major version will be updated.
Otherwise, only the minor version will be updated.

### New Major Release

The process starts when the release manager creates a new branch following the `release/Major.minor` pattern, this new branch is branched from the `main` branch of the PX4-Autopilot project on GitHub.

For the initial beta release of a new major/minor change, a "branch-out deadline" gets set during the weekly call.

The procedure is:

1. Agreement on branch-out deadline by consensus during the call
2. Publication in social media & mailing list about deadline
3. Project board with the name for the new release gets created:
1. The board must include a `patch version` field (selectable)
4. Until the branch-out date
1. All the PR/Issues that a contributor wants to finish before the deadline gets added to the Project Board
2. All the release blocking Issues / PRs gets added to the Project Board by each maintainer

On the branch out-date, the `release/Major.minor` branch gets branched out and a `Major.minor.0-beta1` gets released for testing.

#### Beta Testing

Before the new major/minor release, the beta version gets released for a testing phase.
During the beta testing phase following changes are **allowed**:

- Critical bug fixes
- New hardware support

And following changes are **not allowed**:

- Big new features
- Refactors (with no functional changes)

During the beta testing, the procedure is:

1. During the weekly coordination call
1. Remaining issues for the next beta release gets discussed, and maintainers make an effort to resolve all issues before the next beta release
2. Discussion on certain PRs that may be worth to be included in the next beta gets discussed, and gets added to Project Board appropriately
2. Test reports from users get collected as a Github Issue / Discord message / Flight Review log / Discuss forum post
1. User-reported issues will be discussed by the maintainer team, and the maintainer in charge of the sector creates / adds an issue to keep track of it in the project tracker and assign the next beta version to its `patch version` field.

#### Maintainers Agreement before the Release

Once the release branch reaches a mature state with reliable firmware builds and no major issues are reported, the maintainer team votes to promote the branch to a stable release.

##### What should maintainers look for when Making a Decision?

- The [core functionality](../concept/core_components.md) that they maintain has been tested, and has no major issues
- All the outstanding issues/PRs with `patch version` as the last beta version are resolved

#### Point/Patch Releases

Patch releases are the ones where we apply a patch (e.g. bugfix, hardware support) to a previous point release without big feature changes.
Often, we need a quick patch release after the point release, as the number of testing increases significantly & new errors get found.

Only the following **allowed** changes will be accepted for patch releases:

- Critical bug fixes
- New hardware support

Procedure:

1. The `patch version` of the last beta release (e.g. `M.m.0-beta9`) gets renamed to include the release name (e.g. `M.m.0/M.m.0-beta9`)
2. New tag for the last release commit gets tagged (as `M.m.0`) by the 'Release manager'
3. Release notes are prepared in Github side collaboratively by maintainers
4. Public new point release announcement gets made via social media / mailing list by the 'Release manager'