Keep a Changelog

Record the notable changes to your project

Keep a record of how your project has changed by writing changelog entries. The changelog will automatically populate with the files contained within the changelog folder.

Keep your users updated as your project evolves

Configure your Changelog

Configure a changelog for your project by creating a changelog folder.

Configure a Changelog
1fern/
2├─ fern.config.json
3├─ docs.yml
4├─ changelog/
5    ├─ 07-08-24.md
6    └─ 08-21-24.mdx

Once you’ve configured your changelog, specify where it should appear within your docs in your docs.yml.

docs.yml
1tabs:
2  guides:
3    display-name: Guides
4    icon: light book-open
5  api:
6    display-name: API Reference
7    icon: light code
8  changelog:
9    display-name: Changelog
10    icon: light clock
11    changelog: ./changelog

View an example in GitHub of Humanloop’s docs.yml which powers their Changelog.

Configure a changelog at the API-level by creating a changelog folder specific to an API.

1fern/
2├─ fern.config.json
3├─ docs.yml
4└─ openapi/
5    ├─ openapi.yml
6    └─ changelog/
7        ├─ 07-15-24.md
8        └─ 08-23-24.mdx

Changelogs contained within your API folder will automatically be displayed at the bottom of your API reference. You do not need to configure your changelog(s) within docs.yml.

View an example of a changelog per API in Astronomer’s docs.

A unique changelog per API

Configure a changelog for your project by creating a changelog folder.

Configure a Changelog
1fern/
2├─ fern.config.json
3├─ docs.yml
4├─ pages/
5├─ changelog/
6    ├─ 07-08-24.md
7    └─ 08-21-24.mdx

Once you’ve configured your changelog, specify where it should appear within your navigation in your docs.yml.

docs.yml
1navigation:
2  - section: Introduction
3    contents: 
4      - page: Authentication
5        path: ./pages/authentication.mdx
6      - page: Versioning
7        path: ./pages/versioning.mdx
8  - api: API Reference
9  - changelog: ./changelog
10    title: Release Notes
11    slug: api-release-notes

Section-level changelogs cannot be nested within an api entry. See API-level changelogs to add an API-level entry.

Write a Changelog Entry

Create a new changelog entry by writing a Markdown file. You can use .md or .mdx files. The benefit of using .mdx is that you can leverage the built-in component library within an entry.

fern/openapi/changelog/2024-07-31.mdx
1## Summary
2
3In the latest release, we've added endpoints to create a new Plant.
4
5### What's new?
6
7New endpoints:
8
9- `POST /plant` add a new plant to inventory.
10
11New object schemas:
12
13- `CreatePlantRequest`
14
15<Note> Have questions? Reach out to your local botanist. </Note>

Entry date

Changelog entries are automatically sorted chronologically by the date specific in the file name. Specify the date of your entry using one of the following formats:

  • MM-DD-YYYY (e.g., 10-06-2024)
  • MM-DD-YY (e.g., 10-06-24)
  • YYYY-MM-DD (e.g., 2024-04-21)

Linking to an Entry

Each changelog entry has a unique URL you can direct users to. For example, https://humanloop.com/docs/v5/changelog/2024/8/16

Built with