Πώς να γράψετε ένα αποτελεσματικό, χρήσιμο μήνυμα Git Commit

Τα μηνύματα δέσμευσης είναι σύντομες περιγραφές κάθε δέσμευσης σε ένα σύστημα ελέγχου έκδοσης όπως το Git. Όταν πραγματοποιείτε αλλαγές στα αρχεία του έργου σας, θα πρέπει να παρέχετε ένα μήνυμα που να εξηγεί τι κάνουν ή γιατί τις κάνατε.

Τα μηνύματα δέσμευσης χρησιμεύουν ως μορφή τεκμηρίωσης και επικοινωνίας. Διαδραματίζουν κρίσιμο ρόλο στη διατήρηση ενός σαφούς και οργανωμένου ιστορικού εκδόσεων ενός έργου. Μάθετε πώς να γράφετε καλά μηνύματα δέσμευσης και τα άλλα μέλη της ομάδας σας θα εκτιμήσουν ακόμη περισσότερο τη δουλειά σας.

Δομή ενός μηνύματος καλής δέσμευσης

Ένα καλό παράδειγμα μηνύματος δέσμευσης περιλαμβάνει τέσσερις ενότητες: Τύπος, Περιγραφή, Σώμα και Υποσέλιδο.

Όπως έτσι:

: 
[προαιρετικό σώμα]
[προαιρετικό υποσέλιδο]

Τύπος

Ο τύπος περιγράφει το είδος της αλλαγής που έγινε στην παρούσα δέσμευση. Μπορείτε να χρησιμοποιήσετε οποιοδήποτε σύστημα έχει νόημα για τις περιστάσεις σας. Για παράδειγμα, εδώ είναι μερικά δείγματα λέξεων-κλειδιών που μπορείτε να χρησιμοποιήσετε για να σηματοδοτήσετε κάθε τύπο αλλαγής, μαζί με παράδειγμα χρήσης:

• κατόρθωμα: οι αλλαγές σας εισάγουν μια νέα δυνατότητα.
• διορθώσετε: διορθώνεις ένα σφάλμα.
• ανακατασκευαστής: Η αλλαγή σας αναπαράγει τον κώδικα χωρίς να διορθώσει κάποιο σφάλμα ή να προσθέσει μια νέα δυνατότητα.
• δοκιμή: κάνετε τυχόν αλλαγές που σχετίζονται με δοκιμές. Για παράδειγμα, όταν εσείς γράψτε τεστ με το Jest ή οποιοδήποτε άλλο πλαίσιο δοκιμών εσύ διαλέγεις.
• αγγαρεία: αλλαγές που δεν σχετίζονται με επιδιόρθωση, δυνατότητα ή δοκιμή. Για παράδειγμα, ενημέρωση εξαρτήσεων.
• έγγραφα: όταν ενημερώνετε την τεκμηρίωση.
• στυλ: αλλαγές που δεν επηρεάζουν το νόημα του κώδικα, όπως προσθήκη κενού διαστήματος, ελλείποντα ερωτηματικά κ.λπ.
• perf: αλλαγές που σχετίζονται με βελτιώσεις απόδοσης.
• χτίζω: όταν κάνετε αλλαγές που επηρεάζουν τα αρχεία κατασκευής.
• ci: αλλαγές που σχετίζονται με τη συνεχή ολοκλήρωση.
• επαναστρέφω: κατά την επαναφορά σε προηγούμενη δέσμευση.

Περιγραφή

Η «περιγραφή» ενός μηνύματος δέσμευσης είναι μια συνοπτική και περιγραφική περίληψη των αλλαγών που έγιναν στο commit. Λειτουργεί ως τίτλος που αποτυπώνει την ουσία της δέσμευσης.

Κατά τη σύνταξη της περιγραφής, λάβετε υπόψη τα εξής:

• Κάντε το αρκετά σαφές και συγκεκριμένο ώστε να περιγράψετε τη δέσμευση με μια ματιά.
• Κάντε το σύντομο και περιεκτικό. Στην ιδανική περίπτωση, ο περιορισμός του σε 50 χαρακτήρες ή λιγότερους θα ήταν καλύτερο.
• Γράψτε το σε ενεστώτα, ακόμα κι αν περιγράφετε αλλαγές που έχουν ήδη γίνει.
• Χρησιμοποιήστε την επιτακτική διάθεση ενώ το γράφετε.
• Ξεκινήστε το με κεφαλαίο γράμμα.
• Μην το τελειώνετε με περίοδο.

Για παράδειγμα:

κατόρθωμα: Εφαρμογή εναλλαγής σκοτεινής λειτουργίας για την αρχική σελίδα

Αυτό το παράδειγμα δείχνει πώς μπορείτε να γράψετε την περιγραφή για μια δέσμευση που εφαρμόζει τη σκοτεινή λειτουργία. Χρησιμοποιεί το κατόρθωμα πληκτρολογήστε επειδή εισάγει μια νέα δυνατότητα.

Σώμα (Προαιρετικό)

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

Ακολουθούν ορισμένα πράγματα που πρέπει να προσέξετε κατά τη σύνταξη του σώματος ενός μηνύματος δέσμευσης:

• Το Git δεν αναδιπλώνει ποτέ το κείμενο αυτόματα, επομένως τυλίξτε το μη αυτόματα σε 72 χαρακτήρες όταν γράφετε το σώμα. Αυτό δίνει στο Git αρκετό χώρο για την εσοχή κειμένου, καθιστώντας το πιο ευανάγνωστο.
• Χρησιμοποιήστε το σώμα για να εξηγήσετε τι συνέβη στην αλλαγή, γιατί κάνατε την αλλαγή και το σκεπτικό πίσω από την αλλαγή σας.
• Πρέπει να αφήσετε μια κενή γραμμή μεταξύ της γραμμής περιγραφής και του σώματος. Αυτό επιτρέπει στο Git να κάνει διάκριση μεταξύ τους.
• Εάν η δέσμευση εισάγει πολλές αλλαγές ή επηρεάζει διαφορετικές περιοχές της βάσης κωδικών, σκεφτείτε να χρησιμοποιήσετε κουκκίδες ή παραγράφους για να αναλύσετε τις τροποποιήσεις. Αυτό βελτιώνει την αναγνωσιμότητα και βοηθά τους αναγνώστες να κατανοήσουν τις διάφορες πτυχές της δέσμευσης.

Για παράδειγμα:

κατόρθωμα: Προσθέστε το GitHub ως πάροχο OAuth
Ενσωματώστε το GitHub ως πάροχο OAuth για να ενεργοποιήσετε την απρόσκοπτη λειτουργία 
έλεγχος ταυτότητας με λογαριασμούς GitHub.
- Εφαρμογή ροής ελέγχου ταυτότητας OAuth με το GitHub API
- Διαμορφώστε τα απαραίτητα τελικά σημεία και ρυθμίσεις για τον έλεγχο ταυτότητας GitHub
- Ενημερώστε τη διεπαφή χρήστη για να συμπεριλάβει την επιλογή σύνδεσης στο GitHub

Το παραπάνω παράδειγμα δείχνει ένα καλό μήνυμα δέσμευσης Git για μια δυνατότητα που προσθέτει Το GitHub ως πάροχος OAuth στην αίτησή σας. Αυτό το μήνυμα δέσμευσης έχει μια συνοπτική γραμμή σύνοψης (50 χαρακτήρες ή λιγότερο), ένα πιο λεπτομερές επεξηγηματικό κείμενο (αναδιπλωμένο σε περίπου 72 χαρακτήρες) και σημεία κουκκίδων για πρόσθετες πληροφορίες.

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

Όταν αναφέρετε ζητήματα, αιτήματα έλξης ή άλλα σχετικά στοιχεία, χρησιμοποιήστε την κατάλληλη σύνταξη ή μορφή που απαιτείται από το σύστημα παρακολούθησης προβλημάτων του έργου σας. Αυτό διασφαλίζει ότι οι αναφορές αναγνωρίζονται και συνδέονται σωστά.

Για παράδειγμα:

κατόρθωμα: Προσθέστε το GitHub ως πάροχο OAuth
Ενσωματώστε το GitHub ως πάροχο OAuth για να ενεργοποιήσετε την απρόσκοπτη λειτουργία 
έλεγχος ταυτότητας με λογαριασμούς GitHub.
- Εφαρμογή ροής ελέγχου ταυτότητας OAuth με το GitHub API
- Διαμορφώστε τα απαραίτητα τελικά σημεία και ρυθμίσεις για τον έλεγχο ταυτότητας GitHub
- Ενημερώστε τη διεπαφή χρήστη για να συμπεριλάβει την επιλογή σύνδεσης στο GitHub
Επιλύει: #123
Δείτε επίσης: #456, #789

Το υποσέλιδο αναφέρεται στο σχετικό ζήτημα #123 και αναφέρει άλλα σχετικά ζητήματα #456 και #789 για πρόσθετο πλαίσιο.

Προσθήκη του μηνύματος δέσμευσης

Μπορείτε να γράψετε μηνύματα δέσμευσης χρησιμοποιώντας το -Μ σημαία ακολουθούμενη από το μήνυμα δέσμευσης που περικλείεται σε εισαγωγικά (προαιρετικό αλλά συνιστάται).

ο -Μ Το flag είναι ιδανικό για σύντομα μηνύματα δέσμευσης, που συνήθως περιλαμβάνουν τον τύπο και την περιγραφή.

Για παράδειγμα:

git commit -m "chore: Change linter to ESlint"

Ωστόσο, όταν το μήνυμα δέσμευσης απαιτεί περισσότερες λεπτομέρειες, όπως ένα σώμα και ένα υποσέλιδο, θα ήταν καλύτερα να γράψετε το commit σε ένα πρόγραμμα επεξεργασίας κειμένου ή IDE.

Εναλλακτικά, μπορείτε να γράψετε μεγάλα μηνύματα δέσμευσης σε ένα αρχείο κειμένου και να χρησιμοποιήσετε το --αρχείο επισημάνετε για να καθορίσετε τα μηνύματα δέσμευσης ως τα περιεχόμενα του αρχείου κειμένου.

Για παράδειγμα:

git commit --αρχείο commit_message.txt

Όταν εκτελείτε την παραπάνω εντολή, το git θα χρησιμοποιήσει τα περιεχόμενα του αρχείου ως μήνυμα δέσμευσης.

Μπορείτε επίσης να πείτε στο git να ανοίξει τον προεπιλεγμένο επεξεργαστή για να γράψει ένα μεγαλύτερο μήνυμα. Εάν έχετε το σύνολο μεταβλητών περιβάλλοντος GIT_EDITOR ή EDITOR, το git θα ανοίξει αυτό το πρόγραμμα όταν εκτελείτε ένα γυμνό git commit εντολή.

Γιατί πρέπει να γράφετε καλά μηνύματα δέσμευσης

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

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