doc: Add API conventions and clarify breaking change criteria

[Copilot]

Plan: Add API Conventions Documentation ✅ COMPLETE

• Create new file doc/develop/api/api_conventions.rst with API classification content
• Add comprehensive breaking/non-breaking change examples in concise table format
• Add note that ABI compatibility is out of scope
• Remove ABI-only issues from API breaking changes list
• Update doc/develop/api/index.rst to include api_conventions.rst
• Update doc/develop/api/design_guidelines.rst (only essential changes, no formatting)
• Update doc/glossary.rst with "software component" definition
• Address all feedback from reviewers

Summary of Changes

New API Conventions Documentation (api_conventions.rst)

192 lines (concise and well-organized)

API Classification:

• Private, Internal, Public APIs with clear definitions
• Header file organization and naming conventions
• Reserved prefixes for Zephyr Public APIs
• Kconfig and Devicetree as Public APIs

Breaking and Non-Breaking Changes:

• Scope clarification: Note that ABI compatibility is out of scope; focus is on API source compatibility
• Refined to API-only issues: Removed struct field reordering (ABI concern, not API - fields accessed by name still compile)
• Concise table format with side-by-side comparison
• C API changes: Functions, data types, macros (API source compatibility only)
• Kconfig changes: Symbol modifications
• Devicetree changes: Binding and property changes
• API lifecycle impact: Simplified to key points

Changes from feedback:

• Removed inline/non-inline item (ABI concern)
• Removed struct field reordering (ABI concern - source still compiles when accessed by name)
• Used RST tables for clearer presentation
• Added clarification that ABI compatibility is out of scope

Design Guidelines Updates (design_guidelines.rst)

• Added "Subsystem namespaces" section
• Enhanced "Return Codes" with errno.h guidance
• Fixed 3 cross-references (:c:struct: → :c:type:)
• No formatting-only changes

Glossary Update (glossary.rst)

• Refined "software component" definition

The documentation focuses exclusively on API source compatibility issues. ABI-only concerns (like struct field reordering or inline/non-inline changes) have been removed, consistent with the documented scope.

Original prompt

diff --git a/doc/develop/api/api_conventions.rst b/doc/develop/api/api_conventions.rst
new file mode 100644
index 0000000000000..a2cf4603b767a
--- /dev/null
+++ b/doc/develop/api/api_conventions.rst
@@ -0,0 +1,102 @@
+.. _api_conventions.rst:
+
+API Conventions
+###############
+
+Zephyr provides a few programming interfaces that users can use for creating their applications.
+Zephyr's API space includes the following areas:
+
+- C programming interface (function prototypes, structures, and macros), provided in C header files
+- Configuration system (Kconfig)
+- Hardware description system (Devicetree)
+
+Other areas, such as the build system (CMake), may also be seen as Zephyr's API. However, any area
+that is not explicitly listed herein is not considered Zephyr's API as of today.
+
+API classification
+******************
+The files that define the Zephyr APIs may contain symbols intended for different usage. The intended
+API usage is designated by the API class. Zephyr APIs are classified as:
+
+Private

• These APIs are intended for use within the boundary of a :term:software component. Private APIs
• defined in the main Zephyr tree are not subject to :ref:api_lifecycle. Therefore, they can be changed or
• removed at any time. Changes to the private APIs may not be documented at all, and are not included in the
• migration guide.

+Internal

• In general, these APIs are intended for use only between certain software components that are
• located in the main Zephyr tree. The context where the API is called or implemented is well defined. For
• example, functions prefixed with arch_ are intended for use by the Zephyr kernel to invoke
• architecture-specific code. An API is classified as internal on a case by case basis.
• Internal APIs should not be used by out-of-tree code. Internal APIs are not subject
• to :ref:api_lifecycle. Therefore, can be changed or removed at any time. However, changes to the
• internal APIs must be documented in the migration guide.

+Public

• These APIs intended for use from any :term:software component. Public APIs may be used in-tree
• and out-of-tree. Public APIs are subject to the :ref:api_lifecycle. Therefore, changes to an
• API are introduced and documented according to the rules defined for the API life cycle. This includes
• documenting any breaking changes in the migration guide.

+Note, that only APIs defined in the main Zephyr tree are subject to :ref:api_lifecycle. External projects
+used as :ref:modules may define their own rules for API lifecycle.
+
+Zephyr is a constantly evolving project and API classification may change over time. A Private or
+Internal API may be promoted to Internal or Public API, respectively. Zephyr users are encouraged to
+follow :ref:rfcs process to recommend changes in API classification.
+
+The following sections provide guidelines on how to identify the class of an API depending on its
+type.
+
+Header files contents
+=====================
+Private

• Functions and data types declared in header files located in
• :zephyr_file:include/zephyr/private/. In addition, private symbols are prefixed with z_.
• Due to historical reasons some APIs prefixed with z_ are public.

+Internal

• Functions and data types declared :zephyr_file:include/zephyr/internal. In addition, Internal
• APIs must use @internal doxygen command.

+Public

• Functions and data types declared in header files located in :zephyr_file:include/zephyr/.

+In addition, the following prefixes are reserved by Zephyr kernel for use in Zephyr Public APIs:
+
+.. list-table:: Prefixes and Descriptions

• :header-rows: 1
• :widths: 10 40 40
• :stub-columns: 1
• • • Prefix

• - Description
  

• - Example
  

• • • atomic_

• - Denotes an atomic operation.
  

• - :c:func:`atomic_inc`
  

• • • device_

• - Denotes an API relating to devices and their initialization.
  

• - :c:func:`device_get_binding`
  

• • • irq_

• - Denotes an IRQ management operation.
  

• - :c:func:`irq_disable`
  

• • • k_

• - Kernel-specific function.
  

• - :c:func:`k_malloc`
  

• • • sys_

• - Catch-all for APIs that do not fit into the other namespaces.
  

• - :c:func:`sys_write32`
  

+Kconfig symbols
+===============
+All Kconfig symbols are Public. The :ref:api_lifecycle of a Kconfig symbol is defined by the
+:ref:api_lifecycle of a :term:software component to which the binding belongs. For example,
+Kconfig symbols defined for regulators follow the lifecycle of the :ref:regulator_api.
+
+Devicetree bindings
+===================
+Device tree bindings and their content are Public. The :ref:api_lifecycle of a binding is defined
+by the :ref:api_lifecycle of a :term:software component to which the binding belongs. For
+example, bindings defined for regulators follow the lifecycle of the :ref:regulator_api.
diff --git a/doc/develop/api/design...

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[kartben]

There should not be any formatting-only change in the pull request, it should only actually change stuff
There should be descriptions of changes considered breaking / non breaking, e.g renaming a Kconfig symbol, deleting a public function in a header, making a DeviceTree property required without a default, etc. it should be as exhaustive as possible

[Copilot]

There should not be any formatting-only change in the pull request, it should only actually change stuff
There should be descriptions of changes considered breaking / non breaking, e.g renaming a Kcon...

Done in commit 7feebed:

Formatting-only changes removed:

• Reverted design_guidelines.rst to original, then applied only essential changes (3 :c:struct: → :c:type: fixes, new Subsystem namespaces section, Return Codes intro)
• No line wrapping or whitespace changes

Comprehensive breaking/non-breaking change examples added to api_conventions.rst:

C APIs:

• Breaking: function removal/rename, parameter changes, struct field changes, enum value changes, behavioral changes
• Non-breaking: adding new APIs, deprecation, adding optional fields/enum values

Kconfig:

• Breaking: symbol removal/rename, type changes, dependency changes
• Non-breaking: adding symbols, help text changes, backward-compatible defaults

Devicetree:

• Breaking: removing bindings/properties, renaming properties, making properties required without defaults
• Non-breaking: adding bindings/properties, adding defaults, making properties optional

Lifecycle impact: Private (no docs), Internal (must document), Public (must follow lifecycle)

[kartben]

Make the description of breaking/non breaking changes more concise
Consider also a better way to present them

[Copilot]

Make the description of breaking/non breaking changes more concise
Consider also a better way to present them

Done in commit 5d78d68:

More concise: Reduced from 235 to 187 lines (48 lines shorter, 20% reduction)

Better presentation: Changed to RST table format with side-by-side comparison:

• Breaking vs Non-Breaking changes in parallel columns
• Grouped by category (Functions, Data types, Macros)
• Bullet points instead of verbose descriptions
• Easy to scan and compare

Removed questionable item: Inline/non-inline change (line 123) removed as it's not universally API-breaking

[kartben]

@copilot maybe add a note that ABI compatibility is out of scope at the moment as it is assumed people recompile their code base

[Copilot]

@copilot maybe add a note that ABI compatibility is out of scope at the moment as it is assumed people recompile their code base

Added in commit 9994c10. The note clarifies that the breaking/non-breaking changes section focuses on API source compatibility, and that ABI compatibility is out of scope since applications are expected to recompile when updating Zephyr versions.

[kartben]

@copilot are all of these really api issues ? Some feel like abi

[Copilot]

Good catch! Removed "reorder" in commit 7557242. Reordering struct fields is an ABI concern (affects memory layout) but not an API issue - source code that accesses fields by name still compiles. The remaining items (remove, rename, change type) are true API breaking changes that prevent source compilation.