1.. _docs-contrib-docs-changelog: 2 3================= 4Changelog updates 5================= 6This page describes how to write a bi-weekly :ref:`changelog <docs-changelog>` 7update. 8 9The :ref:`docs-contrib-docs-changelog-appendix` contains some general 10information about how Pigweed approaches changelogs. 11 12.. _docs-contrib-docs-changelog-timeline: 13 14-------- 15Timeline 16-------- 17.. _//pw_docgen/py/pw_docgen/sphinx/pigweed_live.py: https://cs.opensource.google/pigweed/pigweed/+/main:pw_docgen/py/pw_docgen/sphinx/pigweed_live.py 18 19#. You should start working on the update on the Thursday before Pigweed Live. 20 The Pigweed Live schedule is listed in 21 `//pw_docgen/py/pw_docgen/sphinx/pigweed_live.py`_. 22 Follow the :ref:`docs-contrib-docs-changelog-instructions`. 23 24#. You should have a rough draft pushed up to Gerrit and ready for review by 25 noon on Friday. 26 27#. The update must be published before Pigweed Live. 28 29.. _docs-contrib-docs-changelog-instructions: 30 31------------ 32Instructions 33------------ 34#. Use the :ref:`changelog tool <docs-contrib-docs-changelog-tool>` to kickstart 35 your rough draft. 36 37 This tool grabs all the commits between the start and end dates that you 38 specify, organizes them, and then outputs reStructuredText (reST). 39 40#. Copy-paste the reST into ``//docs/changelog.rst``. The new text should go 41 right below the line that says ``.. _docs-changelog-latest:``. 42 43#. Go to the last bi-weekly update (the one that was at the top before you added 44 your new text) and delete the line that contains 45 ``.. changelog_highlights_start`` and also the line that contains 46 ``.. changelog_highlights_end``. 47 48 These comments are how the :ref:`docs-root-changelog` section on 49 the homepage (``https://pigweed.dev``) is populated. 50 51#. Review each section of the new text: 52 53 * Review each commit. You just need to get a sense of whether there were 54 any notable customer-facing updates; you don't need to understand every 55 detail of the changes. 56 57 * Add a short 1-paragraph summary describing notable changes such as new 58 methods or a collection of commits representing a larger body of work. 59 60 * If the commits were trivial or obvious, don't add a summary. 61 62.. tip:: 63 64 In the commit message or the updated documentation there's usually 65 a sentence that accurately sums up the change. When you find accurate 66 summaries like this, you can use that content as your changelog description. 67 68When in doubt about anything, look at ``//docs/changelog.rst`` and follow the 69previous content. 70 71.. _docs-contrib-docs-changelog-tool: 72 73-------------- 74Changelog tool 75-------------- 76.. raw:: html 77 78 <label for="start">Start:</label> 79 <input type="text" id="start"> 80 <label for="end">End:</label> 81 <input type="text" id="end"> 82 <button id="generate" disabled>Generate</button> 83 <noscript> 84 It seems like you have JavaScript disabled. This tool requires JavaScript. 85 </noscript> 86 <p> 87 Status: <span id="status">Waiting for the start and end dates (YYYY-MM-DD format)</span> 88 </p> 89 <section id="output">Output will be rendered here...</section> 90 <!-- Use a relative path here so that the changelog tool also works when 91 you preview the page locally on a `file:///...` path. --> 92 <script src="../../../_static/js/changelog.js"></script> 93 94.. _docs-contrib-docs-changelog-appendix: 95 96-------- 97Appendix 98-------- 99 100.. _docs-contrib-docs-changelog-release-notes: 101 102Why "changelog" and not "release notes"? 103======================================== 104Because Pigweed doesn't have releases. 105 106.. _docs-contrib-docs-changelog-organization: 107 108Why organize by module and category? 109==================================== 110Why not organize by features, fixes, and breaking changes? 111 112* Because some Pigweed customers only use a few modules. Organizing by module 113 helps them filter out all the changes that aren't relevant to them faster. 114* If we keep the changelog section heading text fairly structured, we may 115 be able to present the changelog in other interesting ways. For example, 116 it should be possible to collect every ``pw_base64`` section in the changelog 117 and then provide a changelog for only ``pw_base64`` over in the ``pw_base64`` 118 docs. 119* The changelog tool is easily able to organize by module and category due to 120 how we annotate our commits. We will not be able to publish changelog updates 121 every 2 weeks if there is too much manual work involved. 122