Changelog updates#

This page describes how to write a bi-weekly changelog update.

The Appendix contains some general information about how Pigweed approaches changelogs.

Timeline#

  1. You should start working on the update on the Thursday before Pigweed Live. The Pigweed Live schedule is listed in //pw_docgen/py/pw_docgen/sphinx/pigweed_live.py. Follow the Instructions.

  2. You should have a rough draft pushed up to Gerrit and ready for review by noon on Friday.

  3. The update must be published before Pigweed Live.

Instructions#

  1. Use the changelog tool to kickstart your rough draft.

    This tool grabs all the commits between the start and end dates that you specify, organizes them, and then outputs reStructuredText (reST).

  2. Copy-paste the reST into //docs/changelog.rst. The new text should go right below the line that says .. _docs-changelog-latest:.

  3. Go to the last bi-weekly update (the one that was at the top before you added your new text) and delete the line that contains .. changelog_highlights_start and also the line that contains .. changelog_highlights_end.

    These comments are how the What’s new in Pigweed section on the homepage (https://pigweed.dev) is populated.

  4. Review each section of the new text:

    • Review each commit. You just need to get a sense of whether there were any notable customer-facing updates; you don’t need to understand every detail of the changes.

    • Add a short 1-paragraph summary describing notable changes such as new methods or a collection of commits representing a larger body of work.

    • If the commits were trivial or obvious, don’t add a summary.

Tip

In the commit message or the updated documentation there’s usually a sentence that accurately sums up the change. When you find accurate summaries like this, you can use that content as your changelog description.

When in doubt about anything, look at //docs/changelog.rst and follow the previous content.

Changelog tool#

Status: Waiting for the start and end dates (YYYY-MM-DD format)

Output will be rendered here...

Appendix#

Why “changelog” and not “release notes”?#

Because Pigweed doesn’t have releases.

Why organize by module and category?#

Why not organize by features, fixes, and breaking changes?

  • Because some Pigweed customers only use a few modules. Organizing by module helps them filter out all the changes that aren’t relevant to them faster.

  • If we keep the changelog section heading text fairly structured, we may be able to present the changelog in other interesting ways. For example, it should be possible to collect every pw_base64 section in the changelog and then provide a changelog for only pw_base64 over in the pw_base64 docs.

  • The changelog tool is easily able to organize by module and category due to how we annotate our commits. We will not be able to publish changelog updates every 2 weeks if there is too much manual work involved.