Αυτό είναι ένα style guide, εμπνευσμένο από το How to Get Your Change Into the Linux Kernel, τα git man pages και διάφορα practices που χρησιμοποιούνται ευρέως στην κοινότητα.
Υπάρχουν μεταφράσεις στις παρακάτω γλώσσες:
Αν θέλετε να συνεισφέρετε, παρακαλώ να το κάνετε! Κάντε fork το project και ανοίξτε ένα pull request.
-
Επιλέγετε μικρά και περιγραφικά ονόματα:
# καλό $ git checkout -b oauth-migration # λάθος - πολύ ασαφές $ git checkout -b login_fix
-
Αναγνωριστικά IDs από αντίστοιχα tickets εξωτερικών υπηρεσιών (π.χ. ένα Github issue) είναι καλοί υποψήφιοι για χρήση μέσα σε όνομα ενός branch. Για παράδειγμα:
# GitHub issue #15 $ git checkout -b issue-15 -
Χρησιμοποιείτε παύλες ως διαχωριστικά λέξεων.
-
Όταν δουλεύουν πολλά άτομα στο ίδιο feature, είναι βολικό να υπάρχουν προσωπικά feature branches και ένα ομαδικό feature branch. Χρησιμοποιείτε την εξής σύμβαση:
$ git checkout -b feature-a/master # ομαδικό feature branch $ git checkout -b feature-a/maria # feature branch της Μαρίας $ git checkout -b feature-a/nick # feature branch του Νίκου
Τα προσωπικά branches γίνονται περιοδικά merge στο ομαδικό branch (βλ. "Merging"). Στο τέλος, το ομαδικό branch είναι αυτό που θα γίνει merge στο "master".
-
Όταν κάνετε merge ένα branch σας, διαγράψτε το από το remote repository (εκτός αν υπάρχει συγκεκριμένος λόγος ώστε να μην το κάνετε).
Tip: Χρησιμοποιείστε την παρακάτω εντολή ενώ είστε στο "master" branch, για να δείτε τη λίστα με τα branches που έχουν γίνει ήδη merge:
$ git branch --merged | grep -v "\*"
-
Κάθε commit πρέπει να αντιπροσωπεύει μια συγκεκριμένη λογική αλλαγή. Μην κάνετε πολλές λογικές αλλαγές σε ένα commit. Για παράδειγμα, αν ένα patch διορθώνει ένα bug και βελτιώνει το performance ενός feature, διαχωρίστε το σε δύο ξεχωριστά commits.
-
Μη καταμερίζετε μια λογική αλλαγή σε διαφορετικά commits. Για παράδειγμα, το implementation ενός feature και τα αντίστοιχα tests, ανήκουν στο ίδιο commit.
-
Κάντε commit νωρίς και συχνά. Τα μικρά και ανεξάρτητα commits είναι πιο εύκολο να κατανοηθούν και να γίνουν revert αν κάτι πάει στραβά.
-
Τα commits πρέπει να είναι ταξινομημένα με λογική σειρά. Για παράδειγμα, αν το commit X εξαρτάται από αλλαγές που έγιναν στο commit Y, τότε το commit Y πρέπει να προηγείται του commit X.
-
Χρησιμοποιείτε τον editor και όχι το terminal, όταν γράφετε το commit message:
# καλό $ git commit # λάθος $ git commit -m "Quick fix"
Το να γράφεις σχόλια commit από το terminal ενισχύει το σκεπτικό του να πρέπει να "στριμώξεις" τα πάντα σε μια γραμμή, το οποίο συνήθως έχει ως αποτέλεσμα κακής ποιότητας commit messages.
-
O τίτλος του commit (δηλ. η πρώτη γραμμή) πρέπει να είναι περιγραφικός και σύντομος. Ιδανικά, δεν πρέπει να ξεπερνάει τους 50 χαρακτήρες. Πρέπει να ξεκινάει με κεφαλαία και να είναι γραμμένος σε προστακτική ενεστώτα. Δεν πρέπει να τελειώνει με τελεία.
# καλό - προστακτική ενεστώτα, λιγότερο από 50 χαρακτήρες, χρήση κεφαλαίων Mark huge records as obsolete when clearing hinting faults # λάθος fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.
Τον τίτλο ακολουθεί μια κενή γραμμή και αμέσως μετά μια πιο λεπτομερής περιγραφή. Πρέπει γίνεται wrap στους 72 χαρακτήρες και να εξηγεί γιατί έγιναν οι αλλαγές, πώς λύνουν το πρόβλημα και τυχόν επιπτώσεις που μπορεί να έχει.
Θα πρέπει επίσης να περιέχει υποδείξεις σε σχετικές πηγές (π.χ. link στο αντίστοιχο θέμα ενός bug tracker).
Short (50 chars or fewer) summary of changes More detailed explanatory text, if necessary. Wrap it to 72 characters. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Further paragraphs come after blank lines. - Bullet points are okay, too - Use a hyphen or an asterisk for the bullet, followed by a single space, with blank lines in between Source http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Τέλος, όταν γράφετε ένα commit message, σκεφτείτε τι θα θέλατε να δείτε αν διαβάζατε αυτό το commit ένα χρόνο αργότερα.
-
Αν το commit A εξαρτάται από το commit B, τότε θα πρέπει αυτός ο συσχετισμός να φαίνεται στο μήνυμα του commit A. Χρησιμοποιείτε τa hashes τους για να αναφερθείτε σε commits.
Ομοίως, αν το commit A διορθώνει ένα bug που εισήχθη από το commit B, τότε αυτό θα πρέπει να αναφερθεί στο μήνυμα του commit A.
-
Αν ένα commit πρέπει να γίνει squash σε ένα άλλο commit, χρησιμοποιείτε τα
--squashκαι--fixupflags αντίστοιχα, έτσι ώστε να φαίνεται ξεκάθαρα το γεγονός:$ git commit --squash f387cab2
(Tip: Χρησιμοποιείτε το
--autosquashflag όταν κάνετε rebase και μαρκαρισμένα commits θα γίνουν αυτόματα squash.)
-
Μην κάνετε rewrite το ιστορικό του git. Το ιστορικό ενός repository είναι πολύτιμη πληροφορία από μόνο του και είναι πολύ σημαντικό να φαίνεται τί πραγματικά συνέβη. Το να αλλάζει κάποιος ένα ήδη δημοσιευμένο ιστορικό, είναι πολύ συχνή πηγή προβλημάτων για όσους δουλεύουν στο ίδιο project.
-
Παρόλα αυτά, υπάρχουν περιπτώσεις όπου το να κάνεις rewrite το ιστορικό είναι θεμιτό. Αυτό συμβαίνει συνήθως όταν:
-
Είστε ο μόνος που δουλεύει στο branch και δεν γίνεται ακόμα review απο κάποιον
-
Θέλετε να καθαρίσετε το branch σας (π.χ. να κάνετε squash τα commits) ή rebase πάνω στο master, έτσι ώστε να το κάνετε αργότερα merge.
Ωστόσο, ποτέ μην κάνετε rewrite το ιστορικό του "master" branch ή οποιουδήποτε άλλου "σημαντικού" branch (π.χ. κάποιου που χρησιμοποιείται στο production ή σε CI servers).
-
-
Κρατάτε το ιστορικό καθαρό και απλό. Αμέσως πριν γίνει merge το branch:
-
Βεβαιωθείτε ότι συμμορφώνεται με το style guide και αν δε το κάνει, εκτελέστε τις απαραίτητες ενέργειες (squash/αναδιαξτε τα commits, αναδιατυπώστε τα σχόλια κ.ά.)
-
Kάντε το rebase πάνω στο branch στο οποίο πρόκειται να γίνει merge:
[my-branch] $ git fetch [my-branch] $ git rebase origin/master # then mergeΑυτό έχει ως αποτέλεσμα ένα branch που μπορεί να εφαρμοστεί κατευθείαν στο τέλος του "master" branch και έχει ως αποτέλεσμα ένα απλό, γραμμικό ιστορικό.
(Σημείωση: Αυτή η προσέγγιση ταιριάζει καλύτερα σε projects με βραχυπρόθεσμα branches. Διαφορετικά, ίσως είναι καλύτερο να κάνετε περιστασιακά merge το "master" branch αντί να κάνετε rebase πάνω σ' αυτό.)
-
Αν το branch αποτελείται από περισσότερα από ένα commit, μην το κάνετε merge με fast-forward:
# καλό - δημιουργείται merge commit $ git merge --no-ff my-branch # λάθος $ git merge my-branch
-
Υπάρχουν διάφορα workflows και καθένα από αυτά έχει πλεονεκτήματα και μειονεκτήματα. Το αν ένα workflow ταιριάζει στην περίπτωσή σας, εξαρτάται από την ομάδα, το project και τις διαδικασίες που χρησιμοποιείτε στο development.
Ωστόσο, είναι σημαντικό να επιλέξετε μια ροή εργασίας και να την εφαρμόζετε με συνέπεια.
-
Να είστε συνεπείς. Αυτό σχετίζεται με το workflow αλλά έχει να κάνει και με πράγματα όπως commit messages, ονόματα branch και tags. Το να είστε συνεπείς κάνει πιο εύκολο το να καταλάβει κανείς τι ακριβώς έγινε και γιατί, απλά κοιτάζοντας το ιστορικό, ένα commit message κτλ.
-
Τρέξτε τα tests πριν κάνετε push. Μην κάνετε push μη ολοκληρωμένη δουλειά.
-
Χρησιμοποιείτε annotated tags για να μαρκάρετε release versions ή άλλα σημαντικά σημεία στο ιστορικό. Προτιμάτε lightweight tags για προσωπική χρήση, όπως π.χ. για να μαρκάρετε commits για να μπορείτε μελλοντικά να ανατρέξετε σε αυτά.
-
Κρατάτε τα repository σας σε καλή κατάσταση με το να εκτελείτε τις παρακάτω εντολές συντήρησης, ανά τακτά χρονικά διαστήματα:
Αυτό το έργο χορηγείται με άδεια Creative Commons Attribution 4.0 International license.
Agis Anastasopoulos / @agisanast / http://agis.io
Μετάφραση στα Ελληνικά:
Grigoria Pontiki / @grigoriap / http://grigoria.gr