├── CHANGELOG.md ├── Examples └── swiftenv.md ├── LICENSE ├── README.md └── Specification.md /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 1.0.0 4 | 5 | ### Enhancements 6 | 7 | * Adds a recommendation that the sections should be ordered in importance. The 8 | reader should see breaking changes first as these are more important. 9 | 10 | ## 0.1.0 11 | 12 | Initial release of the changelog specification. 13 | -------------------------------------------------------------------------------- /Examples/swiftenv.md: -------------------------------------------------------------------------------- 1 | # Changelog for swiftenv 2 | 3 | ## 0.2.1 4 | 5 | ### Bug Fixes 6 | 7 | * Fixes an issue when installing via Homebrew and the `$SWIFTENV_ROOT` 8 | directory didn't exist. 9 | 10 | ## 0.2.0 11 | 12 | ### Enhancements 13 | 14 | * Adds support for versions of Swift included in Xcode. 15 | * Added `swiftenv --help`. 16 | 17 | ## 0.1.0 18 | 19 | Initial release. 20 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015, Kyle Fuller 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | 7 | * Redistributions of source code must retain the above copyright notice, this 8 | list of conditions and the following disclaimer. 9 | 10 | * Redistributions in binary form must reproduce the above copyright notice, 11 | this list of conditions and the following disclaimer in the documentation 12 | and/or other materials provided with the distribution. 13 | 14 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 15 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 17 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 18 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 21 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 23 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | A formal specification for semantic changelog files and entries. 4 | 5 | ## Quick Links 6 | 7 | - [Specification](Specification.md) 8 | 9 | ## Rationale and Goals 10 | 11 | The primary goal around the changelog specification is to formalise a structure 12 | for changelog files to bring consistency across projects. 13 | 14 | A formal specification around changelogs may also allow automation via tools. 15 | Tools can understand semantics around changes, whether a change is breaking, an 16 | enhancement or a bug fix and automatically determine the next appropriate 17 | [semantic version](http://semver.org) number. Along with dealing with any 18 | manual tasks around changelog management. 19 | 20 | ## Examples 21 | 22 | A small example changelog entry: 23 | 24 | ```markdown 25 | ## 0.2.0 26 | 27 | ### Enhancements 28 | 29 | * Adds support for versions of Swift included in Xcode. 30 | * Added `swiftenv --help`. 31 | ``` 32 | 33 | Or rendered as markdown: 34 | 35 | > ## 0.2.0 36 | > ### Enhancements 37 | > * Adds support for versions of Swift included in Xcode. 38 | > * Added `swiftenv --help`. 39 | 40 | ### Examples Elsewhere 41 | 42 | You can find examples of changelogs in the wild in the following projects: 43 | 44 | - [swiftenv](https://github.com/kylef/swiftenv/blob/master/CHANGELOG.md) 45 | - [CocoaPods](https://github.com/CocoaPods/CocoaPods/blob/master/CHANGELOG.md) 46 | - [Xcodeproj](https://github.com/CocoaPods/Xcodeproj/blob/master/CHANGELOG.md) 47 | - [Jekyll](https://github.com/jekyll/jekyll/blob/master/History.markdown) 48 | 49 | ### Parsers & Generators 50 | 51 | Interested in programmatically reading or manipulating your changelog? 52 | 53 | - [Golang: parkr/changelog](https://github.com/parkr/changelog) 54 | -------------------------------------------------------------------------------- /Specification.md: -------------------------------------------------------------------------------- 1 | # Changelog Specification 2 | 3 | This document is a full specification of the changelog format. 4 | 5 | ## Filename 6 | 7 | Changelogs should be stored in a filename called `CHANGELOG.md`. 8 | 9 | ## Release 10 | 11 | A release is indicated by a subheading followed by the release name. 12 | 13 | ```markdown 14 | ## 1.0.0 15 | ``` 16 | 17 | A released version may contain a date in the ISO8601 standard using UTC. 18 | The date must be contained within round brackets: 19 | 20 | ```markdown 21 | ## 1.0.0 (2016-01-09) 22 | ``` 23 | 24 | A release may also contain a short summary. 25 | 26 | ```markdown 27 | ## 1.0.0 (2016-01-09) 28 | 29 | Initial release of Curassow. 30 | ``` 31 | 32 | ## Section 33 | 34 | Within a release, you may define sections to group individual change entries 35 | together via subheadings. For example, to create a section called "Bug Fixes": 36 | 37 | ```markdown 38 | ### Bug Fixes 39 | ``` 40 | 41 | You MAY define your own sections with any name. It is recommended that you use 42 | the section names defined below so that tooling can understand the semantic 43 | meaning of changes. 44 | 45 | - Breaking - Indicates a change that is backwards incompatible and breaks the 46 | existing behaviour. 47 | - Enhancements - New functionality that is introduced. 48 | - Bug Fixes - Backwards compatible bug fixes. 49 | 50 | The order of sections should be in the order of importance. For example, 51 | Breaking section SHOULD be above Enhancements. Enhancements SHOULD be above Bug 52 | Fixes. 53 | 54 | ## Change Entry 55 | 56 | A change entry is in the form of a markdown list. 57 | 58 | ```markdown 59 | * My change 60 | ``` 61 | 62 | Each entry is markdown, so it may contain any form of valid markdown such as 63 | links. 64 | 65 | It is recommended that you contain the author of the change along with 66 | any related issues. For example: 67 | 68 | ```markdown 69 | * Explicitly inform the user to close existing project when switching to 70 | a workspace for the first time. 71 | [Kyle Fuller](https://github.com/kylef) 72 | [#2996](https://github.com/CocoaPods/CocoaPods/issues/2996) 73 | ``` 74 | 75 | Or, rendered: 76 | 77 | > * Explicitly inform the user to close existing project when switching to 78 | > a workspace for the first time. 79 | > [Kyle Fuller](https://github.com/kylef) 80 | > [#2996](https://github.com/CocoaPods/CocoaPods/issues/2996) 81 | --------------------------------------------------------------------------------