User Tools

Site Tools


evergreen-docs:release_notes_process

Release Notes Process for DIG Release Coordinator

Major Release Notes

Preparing for the release

Before the beta is cut, periodically review Launchpad Wishlist bugs with a pullrequest tag to see if they have the necessary release notes. If they don't, add the needsreleasenotes tag to them. If the person submitting the bug is fairly new, guide them through the process, using these release notes guidelines as a reference.

Generating the release notes file

  1. Developers and others add release notes to the docs/RELEASE_NOTES_NEXT directory.
  2. Around the time the beta is released, the create_release_notes.sh script is run, which generates a new Release Notes file containing all the notes contained in RELEASE_NOTES_NEXT.
  3. Remove the individual files from RELEASE_NOTES_NEXT after they are compiled, as otherwise things can get mixed up.
  4. After this script is run, make all copyediting, acknowledgment, and other changes to the file produced by create_release_notes.sh. Don't run this script again; you will lose your work!

Acknowledgements for Major Releases

The acknowledgements section is an opportunity to thank everyone who has contribute to a particular release. In major release notes, we include acknowledgements for contributors, their employing organizations, and the organizations that sponsored development in major release notes.

  • For organizations that commissioned development, contact known vendors whose developers contributed to the release and ask them if there are organizations that funded any of those enhancements. If the majority of the code was merged for a particular web client sprint, be sure to include the funders of that sprint.
  • For individuals who contributed code, management, translations, documentation patches and tests to this release:
    • Acknowledge the code contributors who authored any portion of the new features that are listed in the release notes. By focusing on new features, we are omitting many code contributions made to that particular branch that were bug fixes. The reason for this omission is that, since those branches were backported, those contributors were already acknowledged in the monthly point release notes for other releases.
      • One workflow to get this information:
        • Use the list of new features to identify the Launchpad bug IDs. A good way to find those bugs in launchpad without much searching is to look on the list of FIXCOMMITTED bugs.
        • For each launchpad bug ID, search the commit messages for this ID.
        • Note the people who authored and signed off on each relevant commit.
    • Acknowledge contributors responsible for managing or building the release.
    • Acknowledge translators who added translations for one of the 'official' Evergreen languages since the cutting of the last major release. These translators can be identified by going to https://translations.launchpad.net/evergreen, sorting the languages by 'Last Changed' date, and then clicking into each of the languages that have been changed since the last release. Within each language, the last edit date will be listed for each of the templates along with the translator who made the last edit.
    • Acknowledge documenters who have contributed documentations for new features in this release. As is the case with code contributors, we are omitting some documentation contributions made to that particular branch because they were backported and acknowledged at the time of the point release.
    • Acknowledge authors of any tests that were written for that release. Tests are most often written with the code for a new feature or a bug fix. However, when a test is written apart from any new feature or bug fix, those tests are typically merged to the master branch and not backported. Therefore, those authors should be acknowledged in the major release notes.
  • For organizations whose employees contributed patches, identify the library institutions, companies, etc. who employ the contributors acknowledged in the above section. In some cases, a code contributor may work for a library institution, but also do third-party contract work. Checking with those contributors is a good idea to ensure the appropriate organization is listed here.

Point Release Notes

List of bug fixes
  1. Go through the git commits for each release branch (e.g. rel_17_9 and rel_17_10) to find which bugs have been fixed since the last release. It's easier to start with the earliest branch (e.g. rel_17_9).
  2. Add a complete list of bug fixes to the top of the appropriate release notes file (e.g. RELEASE_NOTES_17_9.adoc) using Asciidoc. You may be able to use the commit messages to describe most of the bug fixes. You may also get some information from Launchpad. For each entry in the list, include a link to the launchpad bug so that readers can easily find more information about the bug.
  3. Commit your changes with a commit message like "Docs: Release notes for Evergreen 17.9.3". This is a typical point release note commit.
  4. Repeat the process for each other relevant release. Much of this can be copy/pasted, but there may also be fixes that weren't backported to some of those earlier releases.
  5. Push the commits to the release notes to the following branches:
    • master
    • the newer major release branch (e.g. rel_17_10)
    • the older major release branch, but only include the changes to the earlier branch (e.g. don't put the 17.10 changes in the rel_17_9 branch).
    • if point release branches have been created, cherry-pick to them as well.
Acknowledgements for Point Releases

Acknowledgements for point release notes have varied, but current practice has been to acknowledge the contributors, and not the employing organizations or organizations that sponsored development.

  • Provide an acknowledgement for each of the authors of the code commits that were merged to that release branch. Also include people who signed off on commits.
    • You could use git to find all the authors/sign-offers/committers, if you know the commit hash for the last commit in the previous point release. If you want to include everyone who signed off on commits, this command should get you close:
      • git log COMMIT_HASH^.. | grep "Signed-off-by" | sort | uniq
    • If you want to limit it to authors and committers, try the following:
      • git log COMMIT_HASH^.. --format="%aN" | sort | uniq
      • git log COMMIT_HASH^.. --format="%cN" | sort | uniq
      • %aN is Author Name, and %cN is Committer Name
evergreen-docs/release_notes_process.txt · Last modified: 2019/08/19 19:04 by sandbergja

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.