Skip to content

pr-workflow.md

Latest commit

 

History

History
132 lines (85 loc) · 6.97 KB

pr-workflow.md

File metadata and controls

132 lines (85 loc) · 6.97 KB

Ροή Εργασιών Pull Request (PR)

Αυτό το έγγραφο περιγράφει τη διαδικασία διαχείρισης των Pull Requests (PR) στο ZeroClaw, με στόχο τη διασφάλιση υψηλής απόδοσης, ασφάλειας και σταθερότητας του κώδικα.

Σχετική Τεκμηρίωση

  • README.md: Ταξινόμηση και πλοήγηση στην τεκμηρίωση.
  • ci-map.md: Ιδιοκτησία ροών εργασίας CI και διαχείριση σφαλμάτων.
  • reviewer-playbook.md: Οδηγός για ελεγκτές κώδικα (reviewers).

0. Περίληψη

  • Σκοπός: Καθορισμός ενός ντετερμινιστικού μοντέλου διαχείρισης PR βάσει ανάλυσης κινδύνου.
  • Κοινό: Συνεισφέροντες (contributors), συντηρητές (maintainers) και αυτοματοποιημένοι πράκτορες ελέγχου.
  • Πεδίο Εφαρμογής: Κύκλος ζωής PR, κριτήρια ετοιμότητας, δρομολόγηση κινδύνου και πρωτόκολλα αποκατάστασης.

1. Ταχεία Διαχείριση βάσει Κατάστασης PR

1.1 Ημιτελές Πρότυπο PR

  • Ζητήστε τη συμπλήρωση του προτύπου και την παροχή αποδεικτικών στοιχείων μέσω λίστας ελέγχου.
  • Αναστείλετε τον λεπτομερή έλεγχο μέχρι την πλήρη συμπλήρωση των στοιχείων.

1.2 Αποτυχία στην Πύλη CI (CI Gate)

  • Οι αποτυχίες πρέπει να επιλύονται με βάση τον χάρτη CI.
  • Ο έλεγχος από τον συντηρητή ξεκινά μόνο μετά την επιτυχία όλων των απαιτούμενων ελέγχων CI.

1.3 Τροποποιήσεις Υψηλού Κινδύνου

  • Αλλαγές σε κρίσιμα υποσυστήματα απαιτούν λεπτομερή έλεγχο.
  • Απαιτούνται ρητά αποδεικτικά στοιχεία για το πλάνο επαναφοράς (rollback) και δοκιμές ορίων ασφαλείας.

1.4 Αντικατάσταση ή Διπλότυπο PR

  • Απαιτείται αναφορά στο PR που αντικαθίσταται και καθαρισμός της ουράς εργασιών.
  • Το πλεονάζον PR κλείνει μετά από επιβεβαίωση του συντηρητή.

2. Αρχές Διακυβέρνησης

  • Διεκπεραιωτικότητα: Διατήρηση σταθερού ρυθμού συγχωνεύσεων (merges).
  • Ποιότητα Σήματος: Γρήγορη ανάδραση από το CI με ελάχιστα ψευδώς θετικά αποτελέσματα.
  • Ασφάλεια: Αυστηρός έλεγχος σε κρίσιμες επιφάνειες επίθεσης.
  • Αναστρεψιμότητα: Οι αλλαγές πρέπει να είναι κατανοητές και εύκολα αναστρέψιμες.

3. Ρυθμίσεις Αποθετηρίου (Branch Protection)

Οι παρακάτω κανόνες εφαρμόζονται στον κλάδο main:

  • Απαίτηση επιτυχών ελέγχων κατάστασης (Status Checks) πριν από τη συγχώνευση.
  • Υποχρεωτική επιτυχία της "Πύλης Απαιτούμενου CI".
  • Απαίτηση έγκρισης από CODEOWNERS για ευαίσθητες διαδρομές.
  • Απόρριψη παλαιών εγκρίσεων σε περίπτωση νέων commits.
  • Απαγόρευση αναγκαστικής προώθησης (force-push).

4. Κύκλος Ζωής PR

4.1 Υποβολή (Intake)

  • Χρήση του προτύπου .github/pull_request_template.md.
  • Αυτόματη απόδοση ετικετών (labels) για το μέγεθος, τον κίνδυνο και την ενότητα (π.χ. risk:high, size:M).

4.2 Επικύρωση

  • PR που αφορούν αποκλειστικά τεκμηρίωση παρακάμπτουν τις εργασίες μεταγλώττισης.
  • Ο κώδικας Rust ελέγχεται για lints, επιτυχή μεταγλώττιση και δοκιμές (unit/integration tests).

4.3 Έλεγχος (Review)

  • Προτεραιότητα βάσει κινδύνου και μεγέθους.
  • Κρίσιμες διαδρομές (src/security, src/gateway, CI workflows) απαιτούν έγκριση από συντηρητές.

4.4 Συγχώνευση (Merge)

  • Προεπιλεγμένη μέθοδος: Squash Merge.
  • Οι τίτλοι των commits πρέπει να ακολουθούν τη σύμβαση Conventional Commits.

5. Κριτήρια Ετοιμότητας (DoR / DoD)

5.1 Definition of Ready (DoR)

  • Πλήρως συμπληρωμένο πρότυπο.
  • Σαφής περιγραφή των αλλαγών και της εμβέλειάς τους.
  • Αποδεικτικά χειροκίνητης ή αυτόματης επικύρωσης.
  • Ύπαρξη σχεδίου επαναφοράς.

5.2 Definition of Done (DoD)

  • Όλοι οι έλεγχοι CI είναι επιτυχείς.
  • Λήψη όλων των απαραίτητων εγκρίσεων (reviewers, code owners).
  • Οι ετικέτες αντικατοπτρίζουν το πραγματικό περιεχόμενο και τον κίνδυνο.

6. Διαχείριση Μεγέθους

Ετικέτα Γραμμές Κώδικα
size: XS < 80
size: S 80 - 250
size: M 250 - 500
size: L 500 - 1000
size: XL > 1000

Tip

Προτιμήστε τα μεγέθη XS, S και M. Τα PR μεγέθους L και XL πρέπει να δικαιολογούνται ρητά και να συνοδεύονται από εκτενείς δοκιμές.

7. Πολιτική Αποκατάστασης (Rollback)

Εάν μια αλλαγή προκαλέσει προβλήματα μετά τη συγχώνευση:

  1. Αναστροφή (Revert) του PR στον κλάδο main άμεσα.
  2. Ανάλυση της βαθύτερης αιτίας (Root Cause Analysis).
  3. Επαναϋποβολή της διόρθωσης μαζί με δοκιμές αποτροπής υποτροπής (regression tests).

8. Σχετική Τεκμηρίωση

  • README.md: Ταξινόμηση και πλοήγηση τεκμηρίωσης.
  • ci-map.md: Ιδιοκτησία και διαχείριση CI.
  • reviewer-playbook.md: Οδηγός ελέγχου κώδικα.