Changelog guidelines#

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

Overview#

  1. You should start working on the update on the Thursday before Pigweed Live. 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. //docs/index.rst uses these comments to automatically pull the latest changelog highlights onto the homepage.

  4. Review each section of the new text:

    • Add a short 1-paragraph summary describing notable changes. Examples of notable changes include API changes or a unified collection of commits representing a larger body of work.

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

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

Changelog tool#

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

Output will be rendered here...