I've had a few conversations recently about "appropriate" content for release notes, so I thought it was worth starting a separate thread here to clarify.
We have 3 potential audiences for release notes: 1. Developers consuming libraries or other code directly. 2. Deployers and operators. 3. End-users. We implemented reno for this cycle to replace the old wiki-based system for writing release notes for deployers, operators, and end-users. We have in-tree developer documentation for Developers. The two sets of documentation are meant for different purposes, so we need to think about what information we publish in each. As you are writing release notes using reno to be published under docs.openstack.org/releasenotes, please keep in mind the audience is *not* someone who is necessarily going to be looking at code or writing apps based on libraries we produce. Highlight information that deployers and operators will need, like changes to configuration options or service behaviors. Describe REST API changes that an end-user may need to know about. Internal details, library API changes, etc. -- any changes the deployer is not going to see -- are better covered in the developer documentation published under docs.openstack.org/developer. It's relatively easy to include the pbr-generated ChangeLog directly in the documentation (check the source for any of the Oslo libraries to see how we do that). Internal API changes can also be documented in the docstrings using the `versionadded` directive. Mixing these sorts of details into the deployer/operator notes makes those less usable, because the reader will have to sort through a large number of notes they don't care about in order to find the ones they do care about. Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
