Ως συντηρητής, η αναθεώρηση pull requests είναι κάτι που θα κάνεις αρκετά τακτικά.
Αυτό το έγγραφο περιέχει ορισμένες οδηγίες αναθεώρησης pull requests ειδικά για το Exercism.
Αναθεώρηση pull requests ασκήσεων
Η αναθεώρηση ενός pull request για μια Άσκηση Έννοιας ή μια Άσκηση Εξάσκησης μπορεί να είναι αποθαρρυντική, με τόσους πολλούς κανόνες γύρω από αυτούς τους τύπους ασκήσεων.
Για αυτόν τον λόγο, μια πρώτη αναθεώρηση από έναν συντηρητή συχνά διαρκεί δύο με τρεις ώρες και καταλήγει σε δεκάδες σχόλια.
Για τις Ασκήσεις Εννοιών υπάρχουν επίσης αρχεία με παρόμοιους στόχους/περιεχόμενο (π.χ. η άσκηση και η εισαγωγή της έννοιας), όπου είναι απαραίτητο να επικεντρωθείς στο να τελειοποιήσεις πρώτα ένα από αυτά, πριν απλωθείς πολύ πιο πέρα.
Για να κάνουμε αυτή τη ροή εργασίας πιο ομαλή, έχουμε αναπτύξει τις παρακάτω συστάσεις.
Σύσταση: ένας έμπειρος συντηρητής αναλαμβάνει την πρώτη αναθεώρηση
Οι λόγοι για να έχει ακριβώς ένας έμπειρος συντηρητής την πρώτη αναθεώρηση είναι:
- Δε γίνεται διπλή δουλειά αναθεώρησης
- Ο συνεισφέρων και ο συντηρητής θα δουλέψουν ως ζευγάρι στο pull request, κάτι που ελπίζουμε να δώσει στον συνεισφέροντα την αίσθηση ότι δεν το κάνει μόνος του
- Δε θα υπάρξουν αντιφατικά σχόλια αναθεώρησης από άλλους συντηρητές
Σύσταση: συγχώνευση με κατάσταση wip
Μόλις ο συνεισφέρων και ο συντηρητής μείνουν και οι δύο ικανοποιημένοι με την άσκηση, η άσκηση θα πρέπει να συγχωνευτεί με το status της ορισμένο σε wip (wip, δηλαδή εργασία σε εξέλιξη).
Οι ασκήσεις με αυτή την κατάσταση δε θα είναι διαθέσιμες στους μαθητές, αλλά θα είναι διαθέσιμες για προβολή στους κορυφαίους μέντορές μας (μόλις το υλοποιήσουμε κάποια στιγμή στο μέλλον).
Αυτοί οι χρήστες με υψηλή φήμη μπορούν τότε να δοκιμάσουν την άσκηση και να δημιουργήσουν issues ή pull requests για να τη διορθώσουν ή να τη βελτιώσουν.
Τα κύρια οφέλη αυτής της προσέγγισης είναι:
- Αφαιρεί το βάρος από το αρχικό ζευγάρι συνεισφέροντα/συντηρητή να τα κάνει όλα τέλεια
- Δεν οδηγεί σε τεράστιους κύκλους pull requests με πολλές φωνές (που είναι πραγματικά δύσκολοι στη διαχείριση)
Αναθεώρηση pull requests ασκήσεων εξάσκησης
Σύσταση: σκέψου αν η αλλαγή ανήκει πραγματικά στις problem-specifications
Μέρος του περιεχομένου μιας Άσκησης Εξάσκησης (όπως η εισαγωγή της) προέρχεται από τα (κοινόχρηστα) μεταδεδομένα της, όπως ορίζονται στο αποθετήριο problem-specifications.
Όταν αναθεωρείς ένα pull request που αλλάζει τέτοιο περιεχόμενο, σκέψου αν η αλλαγή θα μπορούσε να ωφελήσει και άλλα tracks.
Αν ναι, πρότεινε στον συνεισφέροντα να ανοίξει ένα pull request στο αντίστοιχο αρχείο του αποθετηρίου problem-specifications.
Γενικές συστάσεις αναθεώρησης
Σύσταση: ένας κύριος αναθεωρητής ανά pull request
Όλα τα pull requests θα πρέπει να έχουν έναν κύριο αναθεωρητή (όποιος συντηρητής το αναλάβει).
Άλλοι συντηρητές ή/και μέλη της κοινότητας θα πρέπει να λειτουργούν σε δευτερεύοντα ρόλο.
Υπάρχουν δύο κύριοι τρόποι με τους οποίους κάποιος σε δευτερεύοντα ρόλο μπορεί να συνεισφέρει σε μια αναθεώρηση:
- Έλεγχος ορθογραφίας/γραμματικής, αλλά μόνο αφού έχει γίνει η πρώτη αναθεώρηση από τον κύριο αναθεωρητή.
Μπορεί να είναι απογοητευτικό για τους συνεισφέροντες να λάβουν έναν έλεγχο ορθογραφίας/γραμματικής, να τον διορθώσουν και μετά να έρθει ένας συντηρητής και να τους ζητήσει πιο θεμελιώδεις αλλαγές.
Με άλλα λόγια: ο έλεγχος ορθογραφίας είναι κάτι που το κάνεις αφού τακτοποιηθούν οι θεμελιώδεις αλλαγές (ή πιθανώς σε ένα επόμενο pull request).
- Το να επισημαίνεις πράγματα χωρίς να ζητάς από τον αναθεωρητή να ενεργήσει.
Αν σχολιάζεις πράγματα που ο κύριος αναθεωρητής θα έπρεπε να σκεφτεί ή που μπορεί να του διέφυγαν, δημοσίευσε το σχόλιό σου εκφράζοντας μια γνώμη ή διατυπωμένο ως ερώτηση.
Έτσι γίνεται σαφές στον συνεισφέροντα ότι δεν του ζητάς να κάνει αλλαγές, κάτι που θα κάνει τα πράγματα λιγότερο μπερδεμένα για αυτόν.
Θα μειώσει επίσης την πιθανότητα ο κύριος αναθεωρητής να νιώσει "υπονομευμένος".
Σύσταση: μη σχολιάζεις άσχετα πράγματα
Όταν αναθεωρείς ένα pull request, σχολίασε μόνο πράγματα που σχετίζονται άμεσα με το pull request.
Για οτιδήποτε άλλο, άνοιξε ένα issue ή δημιούργησε ένα ξεχωριστό (επόμενο) pull request.
Σύσταση: παραπομπή στην τεκμηρίωση
Όταν είναι δυνατόν, προσπάθησε πάντα να παραπέμπεις σε τεκμηρίωση που εξηγεί τον λόγο για τον οποίο σχολιάζεις κάτι.
Αυτό βοηθά πολύ να μειωθεί η πιθανότητα να καταλήξουν τα πράγματα σε αντιπαράθεση.
Σύσταση: ζήτα βοήθεια από άλλες ομάδες
Αν θέλεις να ζητήσεις βοήθεια για την αναθεώρηση ενός pull request, έχουμε δύο συγκεκριμένες ομάδες που μπορείς να ειδοποιήσεις:
-
@exercism/reviewers: για οποιεσδήποτε γενικές αναθεωρήσεις
-
@exercism/github-actions: για οποιεσδήποτε ερωτήσεις σχετικά με τις ενέργειες GitHub
