Writing Change Logs and Migration Guides

Changelogs:

Whenever making a change to the codebase copy the template change log entry in the https://github.com/NREL/buildstockbatch/blob/master/docs/changelog/changelog_dev.rst file and update it to reflect your changes. Please link issues and pull requests as demonstrated in the example.

When making major or minor releases create a new change log rst file - e.g. changelog_1_23.rst for release of version 1.23 - and move all merged changes from the development change log file to the new release file. Ensure the template is still in the development change log file.

Migration Guide:

The goal of the migration guide is to provide a narrative overview of changes made to buildstockbatch since last release, and the impact that these changes will have on users. Of particular importance to discuss are breaking changes, new features, and any deprecations. A successful migration guide will allow all users to update to the new version without having to engage with the developers of the various new code pieces.

To make a migration guide copy and paste the previous migration guide, and then update it to reflect the new release. Migration guides should be included for each major and minor version release, even if they simply inform the user that no significant changes have been made. This is important as it will allow the user to know that if there are breaking changes they should file a bug issue.

Index:

The last step is to add the new change log and migration guide to the index.rst is the changelogs docs folder. To do so follow the pattern already implemented. Please rebuild and verify the new docs locally by running the command make html or make.bat html in the main docs folder - https://github.com/NREL/buildstockbatch/tree/master/docs - prior to pushing the new version to master for release.