Μετάβαση στο περιεχόμενο

Ροή εργασίας release

Το AdaptiveLearner εκδίδει release σε κάθε ολοκλήρωση κύριας υποφάσης. Η πλήρης διαδικασία αυτοματοποιείται από το make sync-versions και μια CI εργασία release-gate· τα ανθρώπινα βήματα είναι απλώς επιλογή έκδοσης, CHANGELOG και tag.

Σύμβαση εκδόσεων

Το Adaptive Learner ακολουθεί Semantic Versioning 2.0.0:

  • Major (X.0.0) — breaking changes σε API ή αρχιτεκτονική. Κρατημένο για μελλοντικές μεγάλες αλλαγές.
  • Minor (X.Y.0) — νέα χαρακτηριστικά, backward-compatible. Προεπιλογή για κάθε ολοκλήρωση φάσης.
  • Patch (X.Y.Z) — διορθώσεις σφαλμάτων, backward-compatible. Αλυσίδες hotfix.

Τα pre-release tags (-alpha, -beta, -rc) δεν χρησιμοποιούνται. Τα releases είναι πάντα σταθερά.

Τα 8 βήματα release

1. Καταγραφή κατάστασης

git log --oneline $(git describe --tags --abbrev=0)..HEAD
git diff --stat $(git describe --tags --abbrev=0)..HEAD

Αναθεώρησε τι προστέθηκε από το τελευταίο tag. Αποφάσισε το επίπεδο αύξησης.

2. Συγγραφή notes ανά release

Πρόσθεσε αρχείο changelog/releases/vX.Y.Z.md ακολουθώντας τη μορφή του πιο πρόσφατου release (Added / Fixed / Tests / Closed backlog items / Commits / Upgrade notes). Το CI release-gate ελέγχει ότι αυτό το αρχείο υπάρχει για το tag που ωθείται.

3. Χειροκίνητη επεξεργασία κανονικής έκδοσης

Το μόνο χειροκίνητα επεξεργαζόμενο πεδίο έκδοσης στο σύνολο του repo:

# backend/pyproject.toml
[tool.poetry]
version = "X.Y.Z"

4. Διάδοση

make sync-versions

Ενημερώνει αυτόματα 18 αρχεία:

  • frontend/package.json
  • launcher/pyproject.toml
  • launcher/adaptive_learner_launcher/__init__.py
  • launcher/adaptive-learner-launcher.spec (CFBundle plist
  • CFBundleShortVersionString)
  • 10× plugins/adaptive-learner-plugin-*/pyproject.toml
  • 3× literals __version__ plugin __init__.py
  • install.sh (αναγεννάται από install.sh.template)
  • install.ps1 (αναγεννάται από install.ps1.template)

5. Επαλήθευση

make sync-versions-check     # εξέρχεται non-zero σε απόκλιση
make test                    # 2634 tests πρέπει να περάσουν
cd frontend && npm run build # πρέπει να επιτύχει

Το workflow CI release-gate (.github/workflows/release-gate.yml) τρέχει το ίδιο sync-versions-check σε κάθε tag push. Αν τοπικά συμφωνεί αλλά το CI αποτυγχάνει, η απόκλιση εισήχθη μεταξύ τοπικού ελέγχου και push — διερεύνησε.

6. Commit + tag

git add -A
git commit -m "chore(release): bump version to vX.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z — phase headline + summary"

Τα μηνύματα tag είναι annotated, πολυγραμμικά και συνοψίζουν το release. Γίνονται τα GitHub Release notes κατά το επόμενο βήμα.

7. Push

git push origin main --tags

Ενεργοποιεί:

  • ci.yml στο νέο commit (τεστ)
  • release-gate.yml στο νέο tag (έλεγχος απόκλισης version-pin)
  • coverage.yml στο νέο commit (coverage HTML)
  • deploy-gh-pages.yml στο νέο commit (δημοσίευση δημόσιου site)
  • launcher-{linux,macos,windows}.yml όταν το GitHub δημιουργεί το Release από το tag

8. Δημιουργία GitHub Release

gh release create vX.Y.Z \
  --title "Adaptive Learner vX.Y.Z" \
  --notes-file changelog/releases/vX.Y.Z.md

Το --notes-file διασφαλίζει ότι η σελίδα GitHub Release ταιριάζει με τα notes ανά release που commitαρίστηκαν στο βήμα 2.

Εκδόσεις plugin

Τα plugins κλειδώνουν βήμα-βήμα με την κανονική έκδοση εφαρμογής. Ο ίδιος αριθμός σε όλα τα 10 αρχεία pyproject.toml plugin συν τα τρία literals __version__ στα __init__.py plugin. Μια μελλοντική απόφαση "core vs third-party plugin" μπορεί να τα αποσυνδέσει, αλλά η ρύθμιση v1.20.0 είναι ενιαία σε όλα τα 18 διαδιδόμενα αρχεία.

Ροή hotfix

Τα releases επιπέδου patch (0.X.1, 0.X.2) ακολουθούν τα ίδια 8 βήματα. Η ενότητα "Hotfix history" του release CHANGELOG καταγράφει την αλυσίδα όταν προσγειώνονται πολλά hotfixes διαδοχικά.

Διακριτά commits αύξησης deps pre-release

Όταν ο κύκλος release αυξάνει dependencies (Vite, React κ.λπ.), κράτα κάθε αύξηση ως δικό της commit. Λόγοι:

  • Λεπτομέρεια bisect — μια οπισθοδρόμηση απομονώνεται σε μια αύξηση.
  • Αναγνωσιμότητα CHANGELOG — οι αναγνώστες βλέπουν την πραγματική αιτιολόγηση κάθε αύξησης.
  • Επαναφορά — μια κακή αύξηση μπορεί να αναιρεθεί ανεξάρτητα.

Το πλήρες πρότυπο τεκμηριώνεται στο .claude/rules/release-workflow.md. Η πειθαρχία rules-as-docs κρατά τα ανθρώπινα έγγραφα (αυτή η σελίδα) και τους κανόνες μηχανής συγχρονισμένους.