name: changelog description: Update the Pigweed changelog.

Changelog update

This is the official process for updating the Pigweed changelog.

General guidelines

The goal of the changelog is to highlight how Pigweed is progressing and evolving. We do not attempt to comprehensively cover every change; users can consult the Git commit log when they need that level of granularity.

The intended audience is a software engineer in a downstream project that relies on Pigweed. Users should be able to enjoy reading a changelog update during their morning coffee or commute.

Do not attempt to create scripts to speed up this process. You must process commits in small batches, as specified in this document, to ensure that each commit is properly analyzed.

1. Output version

Inform the user that you're running the 20260304 version of the changelog automation.

2. Get the year and month

If the user hasn't specified a year and month, prompt them to do so now. Do not guess.

In subsequent steps, <YYYY> should always be replaced with the user-specified year and <MM> with the user-specified month.

3. Start

Run this command:

bazelisk run //.agents/skills/changelog/scripts -- start --year=<YYYY> --month=<MM>

This command makes sure that data files are properly populated. If there are errors, stop here and inform the user of the problem(s). You can provide this context to the user:

• categories.json error: There's a Pigweed module, third-party integration, or target that's not accounted for.

4. Get the next commit

Run this command:

bazelisk run //.agents/skills/changelog/scripts -- next --year=<YYYY> --month=<MM>

Inspect the data that was written to //.agents/skills/changelog/resources/next.json.

If the next key is null, you have reached the terminating condition. Proceed to Step 6 (Copyedit).

{"next": null}

If the next key contains data, it will be a list of commits. Use these commits in step 5.

5. Group the next commits into stories

For each commit in the next list, decide whether to:

1. Add the next commit to an existing story
2. Refactor an existing story into 2 or more stories, then add the next commit to one of these stories
3. Create a new story

Strongly prefer option 1 or 2. Only pick option 3 as a last resort, when you are certain that the commit is not related to any of the existing stories.

Update //.agents/skills/changelog/resources/data.toml with the new or modified story.

Story example:

# stories

[stories.rust.protobuf]
title = "Protocol buffer support in Rust"
body = """
Bazel toolchain declarations have been added for ``prost`` and 
``protoc-gen-prost``, and a Rust target for the Perfetto trace 
proto has been introduced.
"""
highlight = """
prost and Perfetto support have been added to the Bazel toolchain for Rust.
"""
score = 600

[stories.rust.protobuf.commits."7818487b04e22ebbf2fc477c770c563e9fc0b5ed"]
summary = "Create toolchains for generating protobuf code in Rust with prost"

[stories.rust.protobuf.commits."4b8659b954abdbe97b97677d26105ac6b2eb14f7"]
summary = "Generate Perfetto tracing protobufs in Rust"

[stories.rust.protobuf.commits."32b1cd6f04f3ad5497954fb647e44aa27a759523"]
summary = "Add prost crates for generating protobufs in Rust"

…

The final output for the example above will eventually look like this:

<section id="rust">
  <h2>Rust</h2>
  <section id="protobuf">
    <h3>Protocol buffer support in Rust</h3>
    <p>
      Bazel toolchain declarations have been added for <code>prost</code> and 
      <code>protoc-gen-prost</code>, and a Rust target for the Perfetto trace 
      proto has been introduced.
    </p>
    <p>Commits:</p>
    <ul>
      <li>
        <a href="https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/366895">
          pw_toolchain: Declare prost toolchains
        </a>
      </li>
      <li>
        <a href="https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/365978">
          perfetto: Add Rust target for trace proto
        </a>
      </li>
      <li>
        <a href="https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/365977">
          crates_io: Add prost crates to crates_std
        </a>
      </li>
    </ul>
  </section>
</section>

The rust part in stories.rust.protobuf is the category. The protobuf part is the story ID.

title is a summary of the story in 60 characters or less. Plaintext. This will be presented in an <h3> node. The title usually does not need to repeat the Pigweed module name because the category already makes it clear.

body is a short paragraph explaining the story in more detail. Break lines at 80 characters. Use reStructuredText formatting, e.g. double backticks for inline code. This will be presented as a <p> node below the title.

highlight is a one-sentence summary of the story. This may be presented at the top of the changelog update. highlight must not redundantly repeat the information provided in title. In the example, notice how title sums up the story (Protocol buffer support in Rust) and how highlight provides different information (prost and Perfetto support have been added to the Bazel toolchain for Rust.).

The commits object contains all commits related to this story. Each top-level key in the object is a commit SHA. The summary field is a 1-sentence summary of the commit. Do not use the first line of the commit message as the summary. Generate a summary based on the entire commit message and diff. This summary field will not be displayed in the changelog, we only use it for "debugging" purposes. url, date, and title will be provided by an automated script; you do not need to enter them.

score represents the importance of the story. See the "Scoring criteria" section below. If needed, you can adjust the scores of other stories in order to account for the new story. For example, if another story previously was scored 750, but now it looks like a 600, you are welcome to change the score for that other story to 600.

FYI: See @.agents/skills/changelog/examples/2026-02.toml for an example of a finished data.toml file and @docs/sphinx/changelog/2026/02.toml for an example of how that data.toml file gets exported. The logic for converting 02.toml into reStructuredText is handled in @docs/sphinx/_extensions/changelog.py

Refactoring stories

Regarding option 2 (refactor an existing story), there should never be a story with a generic title like API updates and cleanups. A story with a generic title like the following should always be refactored into smaller, more specific stories.

[stories.pw_async2.api_updates]
title = "API updates and cleanups"
body = """
Futures that don't produce a value now use ``Poll<void>`` by default instead of
``Poll<ReadyType>``. A ``FutureValue`` helper has been added to generically
access ``Future::value_type`` across templates. Additionally, the ``OnceSender``
and ``OnceReceiver`` types have been removed, replaced by the new
``OptionalValueProvider`` which wraps a value in ``std::optional`` and supports
cancellation.
"""
highlight = """
``pw::async2`` received several API updates, including defaulting ``Poll`` to
``void``, adding ``OptionalValueProvider``, and removing the deprecated
``OnceSender``/``OnceReceiver`` types.
"""

Scoring criteria

score must be an integer between 0 and 1000. There will potentially be many stories with a score of 0. For every other number (1 to 1000) there must only be one story with that score.

Keep in mind that Pigweed is a modular platform. Some modules are more important and popular than others. It's possible to use pw_kernel, for example, without depending on most of the rest of Pigweed.

The intended user (i.e. audience) of the changelog is a software engineer in a downstream project that relies on Pigweed.

Explanation of scoring ranges:

• 0: The story has no user-facing impact. 0% of users are likely to be affected. Examples:

  • An internal, non-public function was renamed.
  • Docs-only changes. (This technically has user-facing impact but we do not show documentation-only changes in the changelog.)
  • Test-only changes. (Pigweed is extensively tested. Covering every test-only change will generate a lot of noise.)
  • Trivial build system fixes. (Again, this technically has user-facing impact, but it's boring to read.)

• 1 to 250: The story has trivial impact on downstream projects. Less than 10% of users are likely to be affected. Examples:

  • An extra parameter with a default value was added to an unimportant function.
  • A minor feature or bug fix was applied to an experimental or "work in progress" module.
  • A completely new document was added to the pigweed.dev documentation.

• 251 to 500: The story has minor impact on downstream projects. 11% to 25% of users are likely to be affected. Examples:

  • A helper function was added.
  • A new configuration option was added to a commonly used module, but the default behavior remains unchanged.
  • A minor performance improvement was made to a utility function.

• 501 to 750: The story has moderate impact on downstream projects. 26% to 75% of users are likely to be affected. Examples:

  • A Hardware Abstraction Layer (HAL) module like pw_i2c_rp2040 or a third-party integration module like pw_thread_freertos was created.
  • A moderately used public function or class is being deprecated.
  • A new backend implementation for an existing core facade was added.

• 751 to 1000: The story has high impact on downstream projects. 76% or more of users are likely to be affected. Examples:

  • A critical bug was fixed.
  • A core Pigweed module like pw_kernel or pw_async2 was created.
  • An important function was added to an important Pigweed module.
  • A refactor of a Pigweed module has improved performance and resource usage by 100%.
  • A widely used API was changed in a breaking, non-backward-compatible way.
  • A fundamental, highly anticipated capability or paradigm was introduced.

See @.agents/skills/changelog/examples/2026-01.toml and @.agents/skills/changelog/examples/2026-02.toml for scoring examples.

6. Copyedit

Copyedit docs/sphinx/changelog/<YYYY>/<MM>.toml to follow our writing style.

See @.agents/skills/changelog/examples/2026-01.toml and @.agents/skills/changelog/examples/2026-02.toml for writing style examples.

Use module names directly

Before:

The ``pw_interrupt`` module now includes a fake backend specifically for …

After:

``pw_interrupt`` now includes a fake backend specifically for …

Remove subjective statements when the value is obvious

Assume that the reader is an experienced software engineer. When the value of a change is obvious to this reader, omit the subjective statement.

Before:

``pw_interrupt`` now includes a fake backend specifically for
host-side unit testing. This backend allows tests to simulate being in an
interrupt context, enabling thorough verification of interrupt-safe logic on
host platforms.

After:

``pw_interrupt`` now includes a fake backend specifically for
host-side unit testing. This backend allows tests to simulate being in an
interrupt context.

7. End

Run this comand:

bazelisk run //.agents/skills/changelog/scripts -- end --year=<YYYY> --month=<MM>

Inform the user of the total processing time.

8. Build the docs

The end subcommand from the last step copies over the unique, new data.toml into docs/sphinx/changelog/<YYYY>/<MM>.toml. (Information that can be easily retrieved, like the commit message, is not checked in.) docs/sphinx/_extensions/changelog.py will convert docs/sphinx/changelog/<YYYY>/<MM>.toml into a document during the Sphinx build. This is all automated; no work is needed here.

Add the new docs/sphinx/changelog/<YYYY>/<MM>.toml to docs/sphinx/changelog/BUILD.bazel.

Check docs/sphinx/index.rst. If the changelog update that you just created is more recent than the update that the docs-root-changelog section is pointing to, update the include and ref to point to the latest changelog update.

Run this comand:

bazelisk build //docs

If there are errors and they look related to the changelog update, fix them.

If there are unrelated errors, do not attempt to fix them.