OrchidChangelog
Track and discover changes across the various versions of your library or application.
About
The Changelog plugin tracks changes by adding files in the changelog/
directory. The filename is used as the version
name by default, but it can also be set manually within the file's Front Matter as the version
property. You can also
set in the Front Matter whether a version is considered a "major" or a "minor" version. The content of the page is then
taken as the release notes for that version.
This plugin also generates a JSON file, meta/versions.json
, which includes a listing of all the major versions of your
project (you can optionally have it include minor versions as well). Sites which archive each version in a different URL
root may wish to have their theme try to locate the latest meta/versions.json
, and use Javascript to display those
versions. This way, older versions of your project's documentation can create a link to the documentation on newer
versions.
You may also include the changelog
component on any page to render a listing of all versions with their release notes.
Installation
dependencies {
orchidRuntime("io.github.javaeden.orchid:OrchidChangelog:0.21.2")
}
<dependency>
<groupId>io.github.javaeden.orchid</groupId>
<artifactId>OrchidChangelog</artifactId>
<version>0.21.2</version>
<type>pom</type>
</dependency>
libraryDependencies += "io.github.javaeden.orchid" % "OrchidChangelog" % "0.21.2"
@file:DependsOn("io.github.javaeden.orchid:OrchidChangelog:0.21.2")
Demo
Usage
Directory-Based (multi-file)
Changelog versions are created as files sitting in the changelog/
directory of your site content. The filenames should
be the version name, and they can be put in subdirectories for better organization. Alternatively, you can name the
files something different and set the version
property in each entry's Front Matter.
The files are processed with the same rules for other site content, where the file extension determines how to process the content. The content of the file is the release notes for that version.
Example Changelog Directory Structure
. / (resources root)
├── homepage.md
├── config.yml
└── changelog/
├── 0.1/
| └── 0.1.0.md
├── 0.2/
| └── 0.2.0.md
| └── 0.2.1.md
├── 1.0/
| └── 1.0.0.md
| └── 1.0.1.md
| └── 1.1.0.md
└── 2.0/
└── 2.0.0.md
Example Changelog entry
// changelog/1.0.0.md
---
---
This project is now stable and ready for production use!
# New Features
...
# Breaking Changes
...
Changelog entries are ordered according to the versions' Semantic Versioning, but are limited to just major, minor, and patch versions.
Bumps between changelog versions are detected automatically.
File-Based (single file)
Singe version 0.18.2, Orchid now supports single-file changelog formats such as
Keep A Changelog. In such formats, all versions of the software are documented
in a single file, usually in the repository root in a file called CHANGELOG.md
or something similar. OrchidChangelog
will locate this file, parse the individual versions from it based on a specified header regex, and construct your site
changelogs from these entries.
The following configuration will change from the default directory-based changelogs to the file-based format:
changelog:
adapter:
type: "file" # required
baseDir: "./docs" # optional, change the directory to search for the changelog file in. Defaults to resources root dir
filename: "CHANGES.md" # optional, the name of the file to look for
versionRegex: '...' # optional, change the regex used to locate version header lines in the file. Defaults to Markdown headers of level 1 or 2
The default syntax for a Changelog version header is a Markdown header of level 1 or 2, which contains the version name
and an optional release date in YYYY-MM-DD
format. Versions are usually listed in the file in reverse-chronological
order.
## 1.1.0
- Unreleased version
## 1.0.0 - 2017-08-20
- Major version release
## 0.2.1 - 2017-07-09
- Patch version release
## 0.2.0 - 2017-07-08
- Minor version release
## 0.1.0 - 2017-06-20
- Initial release
Customizing versions.json
Orchid creates a meta/versions.json
file, which is an index of the "important" versions that others would need to know
about. Major versions are added to versions.json
by default. Each entry contains the version number and whether that version
was a major, minor, or patch change or not.
You can also have minor versions added to this index by adding includeMinorVersions: true
to your config.yml
:
changelog:
includeMinorVersions: true
In addition, you can have the release notes for each version added included with each entry in versions.json
by adding
includeReleaseNotes: true
to your config.yml
. The release notes are the compiled content of each entry:
changelog:
includeReleaseNotes: true