Changelog

A changelog page is where we aggregate all the changes for the given release. All releases reside on the same page in reverse chronological order (newer at the top).

The core structure is based on Keep a Changelog.

Index File

The index file recaps major releases, which we were focusing on, such as DAL in the 2022.9 release. The index file is located in the folder, which denotes the version such as 202209/index.adoc.

The index file is structured as follows:

include::ROOT:partial$variables.adoc[]

[#yyyy-mm-x]
= `yyyy.mm`

// Release recap and introduction (sales pitch sort of a thing).

:leveloffset: +1

// Include patch releases ordered by patch number descending (05 -> 04 -> ... -> 00)

:leveloffset: -1

Patch Versions

Patch versions outline the changes that were presented in the given version patch, such as additions, deprecations, and changes.

We now use a tool for the changelog to handle the heavy lifting. Patch releases are described in JSON files inside the src/modules/ROOT/pages/changelog directory (inside the version folder). To exemplify, the 02 patch for the 2022.9 version would be located in the src/modules/ROOT/pages/changelog/202209/02.json file.

The patch release JSON file is structured as follows:

{
  "meta": {
    "releasedOn": "YYYY.MM.DD"
  },

  "added": [],
  "changed": [],
  "deprecated": [],
  "removed": [],
  "fixed": [],
  "security": [],
  "development": []
}

A simple sample with a single changelog entry:

{
  "meta": {
    "releasedOn": "2022.10.20"
  },

  "added": [{
    "what": ["..."],
    "why": ["..."],
    "refs": ["..."]
  }],
  "changed": []
}

You can freely omit unneeded bits from the JSON.

Changelog Entries

`added`

added outlines additions to Corteza such as new features or added UI elements.

what

Describe what the new addition is. To exemplify: "what": "gauge, funnel, and pie charts to the Low Code charts".

The what should provide enough information for the reader to know what was added and where it was added.

why optional

Describe the reasoning behind the new addition. To exemplify: "why": "to cover use-cases which require these charts".

The why should provide some background for the addition.

Template:

{
  "what": ["..."],
  "why": ["..."],
  "refs": []
}

`changed`

changed outlines changes to existing Corteza features.

what

Describe what was changed. To exemplify: "what": "workflow initialization and preprocessing pipeline".

The what should provide enough information for the reader to know what was changed.

why optional

Describe the reasoning behind the change. To exemplify: "why": "to increase performance and optimize memory usage".

The why should provide some background for the addition.

how optional

Describe how the thing changed. To exemplify: "how": "by pre-processing workflows and initializing them in Corteza boot procedure".

The how should provide enough information for the reader to know the new state and potential implications.

Template:

{
  "what": ["..."],
  "why": ["..."],
  "how": ["..."],
  "refs": []
}

`deprecated`

deprecated outlines things that are pending removal. Deprecated bits can still be used but should no longer be relied on, as we can remove them in future releases.

what

Describe what was deprecated. To exemplify: "what": "automation scripts and the Corredor server".

The what should provide enough information for the reader to know what was deprecated.

why optional

Describe the reasoning behind the deprecation. To exemplify: "why": "because it’s a legacy system and the NG Corredor server will replace it".

The why should provide some background into the reasoning behind the deprecation.

Template:

{
  "what": ["..."],
  "why": ["..."],
  "refs": []
}

`removed`

removed outlines things that are no longer available in Corteza.

what

Describe what was removed. To exemplify: "what": "automation scripts and the Corredor server".

The what should provide enough information for the reader to know what was removed.

why optional

Describe the reasoning behind the removal. To exemplify: "why": "because the NG Corredor server replaced it".

The why should provide some background into the reasoning behind the deprecation.

Template:

{
  "what": ["..."],
  "why": ["..."],
  "refs": []
}

`fixed`

fixed outlines changes to existing Corteza features.

If the bug fix changes the original flow of the feature, mention it under changed as well.

what

Describe what was fixed. To exemplify: "what": "funnel chart labels rendered over the page block when there were too many available options".

The what should provide enough information for the reader to know what was fixed. Focus more on what the issue was from the UI perspective instead of the logic perspective.

how optional

Describe how the thing was fixed. To exemplify: "how": "by moving overflowing elements into /dev/null".

The how should provide enough information for the reader what the patch does.

Template:

{
  "what": ["..."],
  "how": ["..."],
  "refs": []
}

`security`

security outlines security-related fixes.

If the bug fix changes the original flow of the feature, mention it under changed as well.

what

Describe what the security hole was. To exemplify: "what": "Fixed the stored XSS attack via xyz".

The what should provide enough information for the reader to know the issue and what caused it. Focus more on what the issue was from the UI perspective instead of the logic perspective.

how optional

Describe how the thing was fixed. To exemplify: "how": "by removing xyz completely".

The how should provide enough information for the reader about what the patch does.

Template:

{
  "what": ["..."],
  "how": ["..."],
  "refs": []
}

`development`

development outlines the development-related quality of life additions.

what

Describe what the development quality of life addition was. To exemplify: "what": "Added C3 to simplify component development in a containerized environment".

The what should provide enough information for the reader to know what was added and why it’s good.

Template:

{
  "what": ["..."],
  "refs": []
}

Adding References

GitHub Commits

To reference a GitHub commit, simply add the full URL into the refs array.

An example of a GitHub commit reference:

{
  "refs": ["https://github.com/cortezaproject/corteza-server/commit/fd6465d0f95d78210401f0d0be9c16e1290341af"]
}

Tips for Better Changelogs

avoid ambiguous text, such as Fixed Low Code chart rendering — what was the issue? How was it fixed? Is this the one I was affected by?
Try to phrase the changelog entries in a way that describes what the user was facing or what a user could do with it. To exemplify, "Fixed chart legend overflowing onto the chart when a lot of options are presented" instead of Fixed chart legend positioning".