Σημασιολογική έκδοση

Semantic Versioning (SemVer) - σύμβαση για το πώς ο αριθμός έκδοσης αντικατοπτρίζει τη φύση των αλλαγών. Μορφότυπος: MAJOR. MINOR. PATCH [- PRERELEASE] [+ ΚΑΤΑΣΚΕΥΗ].

• MAJOR - Ασυμβίβαστες αλλαγές (θραύση).
• MINOR - αμοιβαία συμβατά χαρακτηριστικά/επεκτάσεις.
• PATCH - Διορθώσεις σφαλμάτων/ασφαλείας συμβατές προς τα πίσω.

Στόχος: προβλέψιμη εξέλιξη των API, των γεγονότων, των σχημάτων δεδομένων, των SDK και των ρυθμίσεων χωρίς ξαφνικές αναλύσεις καταναλωτή.

1) Αριθμοί σύμβασης

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Προεκχύλιση ('-α', '-β', '-rc') - ασταθή συγκροτήματα, δεν υπόσχονται συμβατότητα.
Κατασκευή μεταδεδομένων ('+ sha') - δεν επηρεάζει τη σειρά σύγκρισης, χρήσιμη για τον εντοπισμό.
Έως 1. 0. Οποιαδήποτε αλλαγή μπορεί να θεωρηθεί παραβίαση (αλλά είναι καλύτερο να ακολουθήσετε τους κανόνες από την αρχή).

2) Τι να θεωρήσετε θραύση/ελάσσονος σημασίας/έμπλαστρο

• Διορθώσεις για σφάλματα και ασφάλεια χωρίς αλλαγή της σύμβασης.
• Επικαιροποιήσεις σύνδεσης που δεν επηρεάζουν τη σύμβαση.
• Βελτιστοποίηση χωρίς αλλαγή απόκρισης/γεγονότων/συστημάτων.

• Προσθήκη νέων προαιρετικών πεδίων/μεθόδων/τελικών σημείων.
• Επέκταση των αξιών της κλίσης εάν οι καταναλωτές ανέχονται άγνωστες αξίες.
• Νέοι δείκτες βάσεων δεδομένων, ακυρώσιμες στήλες με προεπιλεγμένα, νέα γεγονότα επιπλέον των παλαιών.

• Διαγραφή/μετονομασία πεδίων, αλλαγή τύπων, υποχρεωτική.
• Αλλαγή σημασιολογίας/καταστάσεων/κωδικών σφάλματος.
• Αλλαγή μορφής σειράς, βασικού σχήματος, πρωτοκόλλου μεταφοράς.
• Συμπίεση/συγχώνευση θεμάτων, μεταφορά της έννοιας του γεγονότος, αλλαγή του σχήματος κατάτμησης.
• Μετακινήσεις βάσεων δεδομένων που απαιτούν αλλαγή «δύο φάσεων» χωρίς συμβατότητα προς τα πίσω.

3) Έκδοση τεχνουργήματος

3. 1 ΑΝΑΠΑΥΣΗ

Παραλλαγές: 'URI/v1/...', κεφαλίδες ('Accept: application/vnd. acme. παιχνίδι + json; έκδοση = 1 '), παράμετρος.
Σύσταση: έκδοση σε URI για δημόσιες API. για το εσωτερικό - μέσω της κεφαλίδας c διαπραγμάτευσης.
MINOR: προσθήκη προαιρετικών πεδίων, νέων φίλτρων/πόρων, δεν αλλάζουν τις υπάρχουσες απαντήσεις.
PATCH: διορθώσεις, βελτίωση ορισμού, σταθερή διαλογή.

3. 2 gRPC

Αλλαγή υπογραφών/τύπων MAJOR (νέο πακέτο/υπηρεσία: 'acme. πορτοφόλι. v2 ').
Νέα πεδία - με προαιρετική επισήμανση· ο εξυπηρετητής πρέπει να αγνοεί το άγνωστο.
Δεν διαγράφουμε τα πεδία: «depricket + reserve a number», διαγράφουμε - μόνο στο επόμενο MAJOR.

3. 3 GraphQL

MINOR: νέα πεδία/τύποι/ερωτήματα· αφαίρεση - μέσω '@ decrecated' + παράθυρο μετάβασης, πλήρης αφαίρεση - MAJOR.
Μεταβολή nullable→non - ακυρώσιμη - MAJOR.

3. 4 Εκδηλώσεις και θέματα (Κάφκα/SQS)

Schemas in Schema Registry: εξέλιξη της πρόσθετης ύλης (προσθήκη πεδίων με προεπιλογές).
Νέα ασύμβατη έκδοση → νέου θέματος/θέματος ('bet. settled. v2 ').
Η κλείδα κατάτμησης είναι αμετάβλητη εντός του MAJOR.

3. 5 διαγράμματα DB

1. Προσθήκη στήλης (ακυρώσιμη/προεπιλεγμένη) →

2. Συμπληρώστε την οπίσθια γέμιση →

3. Μετάφραση ανάγνωσης

4. Αφαίρεση παλαιών (μόνο MAJOR).

Αλλαγή τύπου/PK/μοναδικότητα - MAJOR, κάτω από το phicheflag και διπλή εγγραφή.

3. 6 SDK/CLI

Οι δημόσιες μέθοδοι/υπογραφές είναι οι ίδιοι κανόνες.
Για την αυτοπαραγωγή (OpenAPI/Proto) - έκδοση της ονομασίας παρτίδας και των αντικειμένων.

4) Πολιτική στέρησης και κύκλος ζωής

Κάθε αλλαγή θραύσης προηγείται αποπροσανατολισμός (συνήθως 90-180 ημέρες για εξωτερικές, 30-60 για εσωτερικές).
Επικοινωνίες: changelog, e-mail/webhooks σε συνεργάτες, πανό στην πύλη του προγραμματιστή.
Λειτουργία διπλής λειτουργίας: παράλληλη παρακολούθηση του μεριδίου κυκλοφορίας «v1» και «v2».
Κεφαλίδες ηλιοβασίλεμα (REST): 'Ηλιοβασίλεμα: 2026-03-31', 'Σύνδεσμος: <url>; rel = «υποτίμηση» '.

5) Διαπραγμάτευση έκδοσης

Ο πελάτης στέλνει την επιθυμητή έκδοση + τη μέγιστη υποστηριζόμενη έκδοση (για παράδειγμα, 'Accept-Version: 1,2').
Ο εξυπηρετητής απαντά με 'Content-Version:' if μπορεί να προωθήσει.
Σε δικατευθυντικά πρωτόκολλα (WebSocket, gRPC) - ανταλλαγή πλαισίων Hello με 'υποστηριζόμενες _ εκδόσεις'.

6) Ενσωμάτωση προσαρμογέα παρόχου (ACL)

Ο εξωτερικός πάροχος αλλάζει το σύστημα - μέσα στον προσαρμογέα κρατάμε τα v1/v2 mappers και απελευθερώνουμε MINOR για την εσωτερική εκδήλωση, διατηρώντας το συμβόλαιο τομέα μας.
Αν οι εξωτερικές αλλαγές μπουν μέσα, αυτό είναι το μείζον γεγονός του τομέα μας και ένα νέο θέμα.

7) Changelog και δεσμευτικές ετικέτες

• 'feat:'... → MINOR
• 'fix:... '/' chore ',' doc , 'perf' (χωρίς σύμβαση) PATCH
• 'feat!: '/' fix!!: '/' refactor!:' ή 'BREAKING CHANGE:' in MAJOR → body

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Αυτοματοποίηση απελευθέρωσης

CI: επικυρωτές κυκλωμάτων (OpenAPI/Protobuf/Avro/JSON-Schema), ανίχνευση θραύσης. περισσότερα

SemVer-bot: Ανάλυση Συμβατικά Commits → υπολογίζει bump (major/minor/patch), βάζει μια ετικέτα, παράγει ένα changelog.
CD: ξεχωριστή εγκατάσταση και απελευθέρωση (οι phicheflags/ρυθμίσεις ενεργοποιούν τη νέα έκδοση).
Έλεγχος: Μην δημοσιεύετε «τελευταία» στο PRO έως ότου πετύχετε καναρίνι και συμφωνηθούν SLO.

9) Σημασιολογία για τις διαμορφώσεις και τις πολιτικές

Οι ρυθμίσεις (YAML/JSON) έχουν επίσης μια έκδοση σχήματος: 'schema _ version: 3'.
MINOR - νέα προαιρετικά πεδία/κανόνες MAJOR - αλλαγή δομής/υποχρέωσης.
υποστήριξη v2/v3 στον επικυρωτή· εξομάλυνση της έκθεσης ασυμβίβαστου μεταξύ των μεταναστών.

10) Δοκιμή συμβατότητας

Δοκιμές συμβάσεων με γνώμονα τους καταναλωτές (Σύμφωνο): ανά ολοκλήρωση.
Δοκιμές εξέλιξης σχήματος: εκτελέστε παλιά ωφέλιμα φορτία σε ένα νέο σχήμα και αντιστρόφως.
Επανάληψη - Παίζει την κίνηση παραγωγής 'v1' στο 'v2' στη σκιά.
Με βάση την ιδιοκτησία: αντίσταση σε άγνωστα πεδία/enum.

11) Δυνατότητα παρατήρησης ανά έκδοση

Μετρήσεις ετικετών/καταγραφές: 'api _ version', 'schema _ version', 'event _ version'.
Ταμπλό μετάβασης: μερίδιο κυκλοφορίας κατά εκδόσεις, σφάλμα/καθυστέρηση κατά 'v1/v2'.
Καταχωρίσεις: εάν το «v1» δεν πέσει όπως είχε προγραμματιστεί. 4xx/5xx ανάπτυξη μετά την απελευθέρωση του 'v2'.

12) Πρότυπα μετανάστευσης χωρίς χρόνο διακοπής

Επέκταση της σύμβασης → → μετανάστευσης (БД).
Διπλή εγγραφή + σύγκριση αποκλίσεων πριν την αλλαγή ανάγνωσης.
Σύγκριση σκιών για την κατάταξη/κανόνες.
Κανάριος ανά ενοικιαστή/περιφέρεια· διαθέτουν σημαίες για γρήγορες ανατροπές.
Read-compat/Write-compat windows: η νέα έκδοση διαβάζει παλιά δεδομένα, αλλά γράφει σε νέα μορφή.

13) Αντι-μοτίβα

«Έκδοση σε κάθε πεδίο» αντί της έκδοσης του πόρου/γεγονότος.
Κρυφές αλλαγές θραύσης στο πλαίσιο του MINOR (για παράδειγμα, αλλαγή αθετήσεων).
Αφαίρεση υποβαθμισμένων παραθύρων και μετρήσεων κατανάλωσης.
«Forever v1»: κανένα σχέδιο για την εξάλειψη παλαιών εκδόσεων → τεχνικών χρεών και τρωτών σημείων.
Αναμίξτε την επιχειρηματική έκδοση και την έκδοση της εικόνας του δοχείου.

14) Κατάλογος ελέγχου πολιτικής έκδοσης

• Σταθερή μορφή έκδοσης και πηγές αλήθειας (Μητρώο/Πύλη).
• Εγκεκριμένος κατάλογος κριτηρίων θραύσης από τεχνουργήματα (REST/gRPC/GraphQL/events/DB).
• Διαδικασία αποπροσανατολισμού: συγχρονισμός, επικοινωνίες, ηλιοβασίλεμα/πανό, διπλή λειτουργία.
• Αυτόματο diff checker και συμβατικές δεσμεύσεις.
• Ταμπλό έκδοσης και συναγερμού κατανάλωσης.
• Βιβλία παιχνιδιών για τη μετανάστευση (επέκταση/μετανάστευση/συμβόλαιο, διπλή γραφή, σκιά).
• Οι ρυθμίσεις και τα SDK έχουν τις δικές τους εκδόσεις και περιπτώσεις.
• Τεκμηρίωση «πώς να επιλέξετε μια έκδοση» για τους πελάτες και «πώς να αναβαθμίσετε» για τις ομάδες.

15) Παραδείγματα εκδόσεων (περιπτώσεις iGaming)

'BetSettled v1' event → 'v2': προσθήκη 'κενό _ λόγο' (προαιρετικό) και 'φόρο. ποσό "(προαιρετικό) - ΕΛΑΧΙΣΤΟ ποσό. Μετονομάστηκε σε 'payout'→'win_amount' - MAJOR, ένα νέο θέμα.
REST '/πορτοφόλια/μεταφορά ': προσθήκη φίλτρου'? ενοικιαστής _ id = '- MINOR. Αλλαγή κωδικού σφάλματος '409'→'422' - MAJOR.
GraphQL: Σημειωτέο 'Player. ηλικία 'ως' @ υποτιμημένο 'υπέρ του' Player. Ωο-ομάδα '- απελευθέρωση σε MINOR, διαγραφή σε MAJOR μετά την περίοδο X.
DB: προσθήκη στήλης 'bonus _ stager _ left' nullable - MINOR. Ακυρώθηκε και διαγράφηκε το «bonus _ left» - MAJOR (μέσω επέκτασης/σύμβασης).

Συμπέρασμα

Η σημασιολογική έκδοση δεν αφορά τους αριθμούς, αλλά την εμπιστοσύνη και την προβλεψιμότητα. Σαφείς κανόνες, αυτοματοποιημένοι έλεγχοι, ελεγχόμενες αποβολές και διαφανής τηλεμετρία επιτρέπουν σε API, συμβάντα και σχέδια χωρίς πόνο να εξελίσσονται για ενσωμάτωση - και να απελευθερώνουν αλλαγές συχνά, με ασφάλεια και νόημα.