changelog.json File Specification
This document defines the official structure of the changelog.json file used by the ASCOOS OS kernel and by external applications that wish to generate HTML or Markdown changelogs through the TChangelogHandler class.
The structure is designed to be:
1. Root Structure
The changelog.json file is a JSON object where each property is a version key. The value of each property is an array of entries.
Example:
{
"initial": [
{ ... }
],
"1.0.0a30": [
{ ... }
]
}
Even when a version key contains only one entry, its value remains an array. This allows:
2. Version keys and special values
2.1 Special version key: "initial"
The "initial" version key is used to describe the initial state of the system (e.g., first public release, initial class structure, initial setup).
"initial": [
{
"date": "2025-08-01 07:00:00",
"version": 10000,
"version-state": "Initial",
"build": "1",
"module": "all",
"classes": [
{
"all": "Initial"
}
]
}
]2.2 Regular version keys (e.g., "1.0.0a30")
Regular version keys are generated by the stateToChangelogKey() method and follow patterns such as:
Example:
"1.0.0a30": [
{
"date": "2026-05-02 07:00:00",
"version": 10000,
"version-state": "Alpha-30",
"build": "17716",
"module": "core",
"classes": [ ... ],
"functions": [ ... ]
}
]
3. Entry structure per version
Each entry inside the array of a version key is a JSON object with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
date |
string | Yes | Date and time of the change (e.g., 2026-05-02 07:00:00). |
version |
integer | Yes | Numeric representation of the version (e.g., 10000). |
version-state |
string | Yes | Version state (e.g., Alpha-30, Initial). |
build |
string | Yes | Build number (e.g., 17716). |
module |
string | Optional | Name of the module to which the changes belong (e.g., core, all). |
classes |
array | Optional | List of classes affected in this version. |
functions |
array | Optional | List of function groups affected in this version. |
4. classes structure
The classes field is an array of objects. Each object describes a class or a general state (e.g., in "initial").
4.1 Example of a general initial state
"classes": [
{
"all": "Initial"
}
]
4.2 Example of a regular class
"classes": [
{
"name": "TCoreTrait",
"changes": [
"Transfer Extended PHPDoc docblocks to DoBu docblocks"
],
"methods": {
"getServerMemoryUsage()": "Provides memory usage statistics in percentage or structured form."
}
},
{
"name": "TMathHandler",
"changes": [
"Transfer Extended PHPDoc docblocks to DoBu docblocks"
],
"methods": {
"hermiteInterpolate()": "Evaluates the solution of an ODE at an arbitrary time using cubic Hermite interpolation between RK4 sample points.",
"hermiteInterpolateVector()": "Evaluates the solution of a vector-valued ODE system at an arbitrary time using cubic Hermite interpolation between adaptive RKF45 sample points.",
"rk4()": "The Runge-Kutta 4th Order (RK4) method is the gold standard for numerical integration of ordinary differential equations (ODEs). It provides a robust framework for simulating dynamic systems where an analytical solution is difficult or impossible to obtain.",
"rkf45": "RKF45 is an adaptive numerical method for solving ODEs that dynamically adjusts the step size to control the approximation error.",
"rkf45_sys()": "The Runge–Kutta–Fehlberg (RKF45) method extended to systems of coupled differential equations."
}
}
]
4.3 Class fields
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes (except special cases like "all") |
The class name (e.g., TStringList). |
description |
string | Optional | Description of the class. |
changes |
array of string | Optional | List of change descriptions related to the class. |
methods |
object | Optional | List of class methods as key/value pairs (method name → description). |
5. methods structure inside a class
The methods field is a JSON object where:
Example:
"methods": {
"__construct()": "Initializes the class with an array, and optional properties.",
"add()": "Adds a new string to the end of the list and returns its index.",
"clear()": "Clears all strings from the list."
}
6. functions structure
The functions field is an array of objects. Each object represents a function group, such as:
Example:
"functions": [
{
"global-functions": [
{
"getNiceFileSize()": "Converts a byte value into a human‑readable file size string.",
"humanizeKey()": "Converts a key-like string to human-readable title case."
}
]
},
{
"openssl": [
{
"openssl_bundle_create()": "Creates a unified PEM bundle containing certificate, private key, and optional chain.",
"openssl_ca_backup()": "Creates a compressed backup of the entire CA directory structure."
}
]
},
{
"mbstring": [
{
"mb_strcasecmp()": "Multibyte binary safe case-insensitive string comparison.",
"mb_strcmp()": "Multibyte safe string comparison"
}
]
}
]
7. Function groups
Each element of the functions array is an object with a single key, which is the name of the group (e.g., "openssl"), and the value is an array of objects.
Each object inside this array may contain:
Example of an openssl group:
{
"openssl": [
{
"openssl_bundle_create()": "Creates a unified PEM bundle containing certificate, private key, and optional chain.",
"openssl_ca_backup()": "Creates a compressed backup of the entire CA directory structure."
}
]
}
8. changes field
The changes field may appear:
Its format is an array of strings, where each string is a short description of a change.
Example:
"changes": [
"Transfer Extended PHPDoc docblocks to DoBu docblocks"
]
No structured format is used (e.g., added, changed, etc.) to keep the structure simple and flexible.
9. Full example
A full changelog.json example based on the structure:
{
"initial": [
{
"date": "2025-08-01 07:00:00",
"version": 10000,
"version-state": "Initial",
"build": "1",
"module": "all",
"classes": [
{
"all": "Initial"
}
]
}
],
"1.0.0a30": [
{
"date": "2026-05-02 07:00:00",
"version": 10000,
"version-state": "Alpha-30",
"build": "17716",
"module": "core",
"classes": [
{
"name": "TCoreTrait",
"changes": [
"Transfer Extended PHPDoc docblocks to DoBu docblocks"
],
"methods": {
"getServerMemoryUsage()": "Provides memory usage statistics in percentage or structured form."
}
},
{
"name": "TMathHandler",
"changes": [
"Transfer Extended PHPDoc docblocks to DoBu docblocks"
],
"methods": {
"rk4()": "The Runge-Kutta 4th Order (RK4) method is the gold standard for numerical integration of ordinary differential equations (ODEs)."
}
}
],
"functions": [
{
"global-functions": [
{
"getNiceFileSize()": "Converts a byte value into a human‑readable file size string."
}
]
}
]
}
]
}
10. Conclusion
The structure of the changelog.json file described here is the official ASCOOS OS specification for representing system version changes. Any tool (inside or outside ASCOOS OS) that wishes to work with the TChangelogHandler class must strictly follow this format.