Changelog Format

Based on the keep a changelog

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each versions is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • 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.

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.

What is the file format used?

The file should be written in Markdown format and should be named CHANGELOG.md for the defult language (PT - for SGIV10)

Other languages must be added as needed only, the name must include a dash followed by the ISO 639-1 2 digits language code as a suffix Ex: CHANGELOG-EN.md

Changelog Example PT

# Changelog

## Não publicado

- Exportação da lista de utilizadores

## [1.1.0] - 2017-12-07

### Adicionado

- Opção para gerir o logotipo da empresa
- Sincronização manual da AD
- ...

### Alterado

- ...

## [1.0.6] - 2017-11-07

### Corrigido

- Bug

Changelog Example EN

# Changelog

## Unreleased

- Exportação da lista de utilizadores

## [1.1.0] - 2017-12-07

### Added

- Opção para gerir o logotipo da empresa
- Sincronização manual da AD
- ...

### Changed

- ...

## [1.0.6] - 2017-11-07

### Fixed

- Bug