Alexsoft Software Έργα Ascoos OS Τεκμηρίωση Παραδείγματα
ASCOOS OS → Τεκμηρίωση → Ελληνική Τεκμηρίωση → Προδιαγραφές → Προδιαγραφή αρχείου changelog.json

Προδιαγραφή αρχείου changelog.json

Ελάχιστες Απαιτήσεις: AOS 1.0.0+ 🐘 PHP 8.4.0+
Δυσκολία:
Συγγραφέας: Χρήστος Δρογκίδης Ημερομηνία: 04-05-2026 09:00 Τελευταία Ενημέρωση: 04-05-2026 18:00 English

Το παρόν έγγραφο ορίζει την επίσημη δομή του αρχείου changelog.json που χρησιμοποιείται από τον πυρήνα του ASCOOS OS και από εξωτερικές εφαρμογές που επιθυμούν να παράγουν HTML ή Markdown changelog μέσω της κλάσης TChangelogHandler.

Η δομή είναι σχεδιασμένη ώστε να είναι:



Δείγμα από εκτέλεση στην οποία ο χρήστης έδωσε λανθασμένο enconding.
Δείγμα από παραγόμενο έγγραφο αναφοράς αλλαγών σε μορφή markdown.

1. Ριζική δομή (Root structure)

Το changelog.json είναι ένα JSON object στο οποίο κάθε ιδιότητα (property) είναι ένα version key. Η τιμή κάθε ιδιότητας είναι array από entries.

Παράδειγμα:

{
    "initial": [
        { ... }
    ],
    "1.0.0a30": [
        { ... }
    ]
}


Ακόμη και όταν υπάρχει μόνο ένα entry για ένα version key, η τιμή παραμένει array. Αυτό επιτρέπει:


2. Version keys και ειδικές τιμές

2.1 Ειδικό version key: "initial"

Το version key "initial" χρησιμοποιείται για να περιγράψει την αρχική κατάσταση του συστήματος (π.χ. πρώτη δημόσια έκδοση, αρχική δομή κλάσεων, αρχικό setup).

"initial": [
    {
        "date": "2025-08-01 07:00:00",
        "version": 10000,
        "version-state": "Initial",
        "build": "1",
        "module": "all",
        "classes": [
            {
                "all": "Initial"
            }
        ]
    }
]


2.2 Κανονικά version keys (π.χ. "1.0.0a30")

Τα κανονικά version keys παράγονται από τη μέθοδο stateToChangelogKey() και έχουν μορφή όπως:


Παράδειγμα:

"1.0.0a30": [
    {
        "date": "2026-05-02 07:00:00",
        "version": 10000,
        "version-state": "Alpha-30",
        "build": "17716",
        "module": "core",
        "classes": [ ... ],
        "functions": [ ... ]
    }
]


3. Δομή entry ανά έκδοση

Κάθε entry μέσα στο array ενός version key είναι ένα JSON object με τα εξής πεδία:

Πεδίο Τύπος Υποχρεωτικό Περιγραφή
date string Ναι Ημερομηνία και ώρα της αλλαγής (π.χ. 2026-05-02 07:00:00).
version integer Ναι Αριθμητική αναπαράσταση της έκδοσης (π.χ. 10000).
version-state string Ναι Κατάσταση έκδοσης (π.χ. Alpha-30, Initial).
build string Ναι Αριθμός build (π.χ. 17716).
module string Προαιρετικό Όνομα module στο οποίο ανήκουν οι αλλαγές (π.χ. core, all).
classes array Προαιρετικό Λίστα κλάσεων που επηρεάζονται σε αυτή την έκδοση.
functions array Προαιρετικό Λίστα ομάδων συναρτήσεων που επηρεάζονται σε αυτή την έκδοση.

4. Δομή classes

Το πεδίο classes είναι array από objects. Κάθε object περιγράφει μία κλάση ή μια γενική κατάσταση (π.χ. στο "initial").

4.1 Παράδειγμα γενικής αρχικής κατάστασης

"classes": [
    {
        "all": "Initial"
    }
]


4.2 Παράδειγμα κανονικής κλάσης

"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 Πεδία κλάσης

Πεδίο Τύπος Υποχρεωτικό Περιγραφή
name string Ναι (εκτός ειδικών περιπτώσεων όπως "all") Το όνομα της κλάσης (π.χ. TStringList).
description string Προαιρετικό Περιγραφή της κλάσης.
changes array of string Προαιρετικό Λίστα περιγραφών αλλαγών που αφορούν την κλάση.
methods object Προαιρετικό Λίστα μεθόδων της κλάσης, ως key/value (όνομα μεθόδου → περιγραφή).

5. Δομή methods μέσα σε κλάση

Το πεδίο methods είναι ένα JSON object όπου:


Παράδειγμα:

"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

Το πεδίο functions είναι array από objects. Κάθε object αντιπροσωπεύει μία ομάδα συναρτήσεων (function group), όπως:


Παράδειγμα:

"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)

Κάθε στοιχείο του array functions είναι ένα object με ένα μόνο key, το οποίο είναι το όνομα της ομάδας (π.χ. "openssl"), και η τιμή είναι array από objects.

Κάθε object μέσα σε αυτό το array μπορεί να περιέχει:


Παράδειγμα ομάδας openssl:

{
    "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

Το πεδίο changes μπορεί να εμφανιστεί:

Η μορφή του είναι array από strings, όπου κάθε string είναι μία σύντομη περιγραφή αλλαγής.

Παράδειγμα:

"changes": [
    "Transfer Extended PHPDoc docblocks to DoBu docblocks"
]


Δεν χρησιμοποιείται structured μορφή (π.χ. added, changed κλπ) ώστε να παραμείνει απλό και ευέλικτο.

9. Πλήρες παράδειγμα

Παράδειγμα πλήρους changelog.json με βάση τη δομή:

{
    "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. Συμπέρασμα

Η δομή του changelog.json που περιγράφεται εδώ είναι η επίσημη προδιαγραφή του ASCOOS OS για την αναπαράσταση αλλαγών σε εκδόσεις του συστήματος. Οποιοδήποτε εργαλείο (εντός ή εκτός ASCOOS OS) που επιθυμεί να συνεργαστεί με την κλάση TChangelogHandler πρέπει να ακολουθεί πιστά αυτή τη μορφή.