diff --git a/docs/how-to-guides/software-management/guidelines-for-changelog-entries.md b/docs/how-to-guides/software-management/guidelines-for-changelog-entries.md new file mode 100644 index 0000000000000000000000000000000000000000..902f13f176bfeea7d628b3824adfbde73394c66b --- /dev/null +++ b/docs/how-to-guides/software-management/guidelines-for-changelog-entries.md @@ -0,0 +1,109 @@ +# Guidelines for Changelog Entries +This document provides guidelines for CHANGELOG.md files and entries. Changelog files can be found in all ASC software repositories, and they should follow the same style. + +## Creating an Initial Changelog File +If the repository in which you are working does not contain a changelog file, then it should be created. Within the ASC, we have elected to use markdown for our changelog files, so the file should be CHANGELOG.md. + +!!! Tip "Markdown Syntax" + Users unfamiliar with markdown can review the syntax [here](https://www.markdownguide.org/basic-syntax/) + +A newly created changelog file will not have any changes logged, but it should still the same structure as other changelog files within the ASC's software ecosystem. The following boilerplate text can be copied, pasted, and edited to fit the new project. + +``` Markdown +# Changelog + +All changes that impact users of this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +<!--- +This document is intended for users of the applications and API. Changes to things +like tests should not be noted in this document. + +When updating this file for a PR, add an entry for your change under Unreleased +and one of the following headings: + - Added - for new features. + - Changed - for changes in existing functionality. + - Deprecated - for soon-to-be removed features. + - Removed - for now removed features. + - Fixed - for any bug fixes. + - Security - in case of vulnerabilities. + +If the heading does not yet exist under Unreleased, then add it as a 3rd heading, +with three #. + + +When preparing for a public release candidate add a new 2nd heading, with two #, under +Unreleased with the version number and the release date, in year-month-day +format. Then, add a link for the new version at the bottom of this document and +update the Unreleased link so that it compares against the latest release tag. + + +When preparing for a bug fix release create a new 2nd heading above the Fixed +heading to indicate that only the bug fixes and security fixes are in the bug fix +release. +--> + +## [Unreleased] + +### Changed + +### Added + +### Deprecated + +### Removed + +### Fixed + +### Security +``` + + +## Logging Changes +Changes to an existing changelog should occur within the 'Unreleased' heading, and they should be categorized according to their change type. Descriptions of each change type can be found within the boilerplate text above. Each changelog entry should contain a brief (one line) description of the change as well as a link to the issue that it resolves. If no issue exists for the change, then one should be created. For guidance on creating an issue, visit the [issue creation guidelines](./guidelines-for-reporting-issues.md). An example of a changelog entry is as follows: + + +``` Markdown +... +## [Unreleased] + +### Changed + +### Added + - Added sinusoidal projection to the list of available projections. [#42](https://github.com/USGS-Astrogeology/awesome-repo/issues/42) +### Deprecated + +### Removed + +... + +``` + + + +## Updating the Changelog for a Release +When releasing a package containing a changelog, the "Unreleased" tag should be replaced with the version and date of the release, and a new "Unreleased" tag should be placed above. In this way, all previously unreleased changes are captured under the new version tag. Following the "1.0" release of our fake "awesome-repo" in the example above, the changelog would look like: + +``` Markdown +... +## [Unreleased] +### Changed +### Added +### Deprecated +### Removed +### Fixed +### Security + +## [1.0.0] - 12/31/1999 +### Changed +### Added + - Added sinusoidal projection to the list of available projections. [#42](https://github.com/USGS-Astrogeology/awesome-repo/issues/42) +### Deprecated +### Removed +### Fixed +### Security +... + +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e2af981b07b5c852e85925549f95503118ec1884..63043add53a7b9ccddfbece9ae4dd25df1a76975 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,7 +58,8 @@ nav: - ISIS Public Release Process: how-to-guides/software-management/public-release-process.md - Software Support: how-to-guides/software-management/software-support.md - Guidelines for Reporting Issues: how-to-guides/software-management/guidelines-for-reporting-issues.md - - Guidelines for Pull Requests: how-to-guides/software-management/guidelines-for-pull-requests.md + - Guidelines for Pull Requests: how-to-guides/software-management/guidelines-for-pull-requests.md + - Guidelines for Changelog Entries: how-to-guides/software-management/guidelines-for-changelog-entries.md - ISIS Developer Guides: - How To Write ISIS Tests with CTest and GTest: how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md - App Testing CookBook: how-to-guides/isis-developer-guides/app-testing-cookbook.md