Conventional Commits 1.0.0

Περίληψη

Η προδιαγραφή Conventional Commits είναι μια ελαφριά σύμβαση για τα μηνύματα commit. Παρέχει ένα εύκολο σύνολο κανόνων για τη δημιουργία ενός σαφούς ιστορικού των commits, διευκολύνοντας έτσι τη δημιουργία αυτοματοποιημένων εργαλείων. Αυτή η σύμβαση συμβαδίζει με το SemVer, περιγράφοντας τα χαρακτηριστικά, τις διορθώσεις και τις αλλαγές που σπάνε τη συμβατότητα (breaking changes) στα μηνύματα των commits.

Το μήνυμα commit πρέπει να έχει την ακόλουθη δομή:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Το commit περιέχει τα ακόλουθα δομικά στοιχεία, για να επικοινωνήσει την πρόθεση στους καταναλωτές της βιβλιοθήκης σας:

fix: ένα commit τύπου (type) fix διορθώνει ένα σφάλμα στον κώδικά σας (αυτό αντιστοιχεί σε PATCH στο Semantic Versioning).
feat: ένα commit τύπου (type) feat εισάγει ένα νέο χαρακτηριστικό στον κώδικα (αυτό αντιστοιχεί σε MINOR στο Semantic Versioning).
BREAKING CHANGE: ένα commit που έχει υποσέλιδο (footer) BREAKING CHANGE:, ή προσαρτά ένα ! μετά τον τύπο/scope, εισάγει μια αλλαγή που σπάει τη συμβατότητα του API (breaking change) (αντιστοιχεί σε MAJOR στο Semantic Versioning). Μια αλλαγή που σπάει τη συμβατότητα (BREAKING CHANGE) μπορεί να είναι μέρος οποιουδήποτε τύπου commit.
Τύποι (types) εκτός από fix: και feat: επιτρέπονται. Για παράδειγμα, το @commitlint/config-conventional (βασισμένο στη σύμβαση της Angular) συνιστά τη χρήση των: build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, και άλλων.
Υποσέλιδα (footers) εκτός από το BREAKING CHANGE: <description> μπορούν να παρέχονται και να ακολουθούν μια σύμβαση παρόμοια με το git trailer format.

Η χρήση πρόσθετων τύπων δεν επιβάλλεται από την προδιαγραφή Conventional Commits και δεν επηρεάζει το Semantic Versioning (εκτός αν περιλαμβάνουν μια αλλαγή που σπάει τη συμβατότητα - BREAKING CHANGE). Ένα scope (πεδίο εφαρμογής) μπορεί να δοθεί στον τύπο ενός commit για να παρέχει πρόσθετες πληροφορίες πλαισίου και περικλείεται σε παρενθέσεις, π.χ., feat(parser): add ability to parse arrays.

Παραδείγματα

Μήνυμα commit με περιγραφή και υποσέλιδο για breaking change

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Μήνυμα commit με `!` για την επισήμανση μιας breaking change

feat!: send an email to the customer when a product is shipped

Μήνυμα commit με scope και `!` για την επισήμανση μιας breaking change

feat(api)!: send an email to the customer when a product is shipped

Μήνυμα commit με `!` και υποσέλιδο BREAKING CHANGE

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Μήνυμα commit χωρίς σώμα

docs: correct spelling of CHANGELOG

Μήνυμα commit με scope

feat(lang): add Polish language

Μήνυμα commit με σώμα πολλαπλών παραγράφων και πολλαπλά υποσέλιδα

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Προδιαγραφή

Οι λέξεις-κλειδιά “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, και “OPTIONAL” σε αυτό το έγγραφο πρέπει να ερμηνεύονται όπως περιγράφεται στο RFC 2119.

Τα Commits ΠΡΕΠΕΙ να ξεκινούν με ένα πρόθεμα τύπου, το οποίο αποτελείται από ένα ουσιαστικό, feat, fix, κ.λπ., ακολουθούμενο από το ΠΡΟΑΙΡΕΤΙΚΟ scope (πεδίο εφαρμογής), το ΠΡΟΑΙΡΕΤΙΚΟ !, και την ΑΠΑΙΤΟΥΜΕΝΗ άνω και κάτω τελεία και κενό διάστημα.
Ο τύπος feat ΠΡΕΠΕΙ να χρησιμοποιείται όταν ένα commit προσθέτει ένα νέο χαρακτηριστικό στην εφαρμογή ή τη βιβλιοθήκη σας.
Ο τύπος fix ΠΡΕΠΕΙ να χρησιμοποιείται όταν ένα commit αντιπροσωπεύει μια διόρθωση σφάλματος για την εφαρμογή σας.
Ένα scope ΜΠΟΡΕΙ να δοθεί μετά από έναν τύπο. Ένα scope ΠΡΕΠΕΙ να αποτελείται από ένα ουσιαστικό που περιγράφει ένα τμήμα του κώδικα, περικλειόμενο σε παρενθέσεις, π.χ., fix(parser):
Μια περιγραφή ΠΡΕΠΕΙ να ακολουθεί αμέσως την άνω και κάτω τελεία και το κενό μετά το πρόθεμα τύπου/scope. Η περιγραφή είναι μια σύντομη περίληψη των αλλαγών του κώδικα, π.χ., fix: array parsing issue when multiple spaces were contained in string.
Ένα μεγαλύτερο σώμα commit ΜΠΟΡΕΙ να δοθεί μετά τη σύντομη περιγραφή, παρέχοντας πρόσθετες πληροφορίες πλαισίου σχετικά με τις αλλαγές του κώδικα. Το σώμα ΠΡΕΠΕΙ να ξεκινά μία κενή γραμμή μετά την περιγραφή.
Ένα σώμα commit είναι ελεύθερης μορφής και ΜΠΟΡΕΙ να αποτελείται από οποιονδήποτε αριθμό παραγράφων που χωρίζονται με νέα γραμμή.
Ένα ή περισσότερα υποσέλιδα ΜΠΟΡΕΙ να δοθούν μία κενή γραμμή μετά το σώμα. Κάθε υποσέλιδο ΠΡΕΠΕΙ να αποτελείται από ένα token λέξης-κλειδιού, ακολουθούμενο είτε από ένα διαχωριστικό :<space> είτε <space>#, ακολουθούμενο από μια τιμή τύπου string (αυτό είναι εμπνευσμένο από τη σύμβαση git trailer).
Το token λέξης-κλειδιού ενός υποσέλιδου ΠΡΕΠΕΙ να χρησιμοποιεί - αντί για κενά διαστήματα, π.χ., Acked-by (αυτό βοηθά στη διαφοροποίηση του τμήματος του υποσέλιδου από ένα σώμα πολλαπλών παραγράφων). Εξαίρεση γίνεται για το BREAKING CHANGE, το οποίο ΜΠΟΡΕΙ επίσης να χρησιμοποιηθεί ως token λέξης-κλειδιού.
Η τιμή ενός υποσέλιδου ΜΠΟΡΕΙ να περιέχει κενά και νέες γραμμές, και η διαδικασία parsing ΠΡΕΠΕΙ να τερματίζεται όταν εντοπιστεί το επόμενο έγκυρο ζεύγος token λέξης-κλειδιού/διαχωριστικού.
Οι αλλαγές που σπάνε τη συμβατότητα (breaking changes) ΠΡΕΠΕΙ να υποδεικνύονται στο πρόθεμα τύπου/scope ενός commit, ή ως εγγραφή στο υποσέλιδο.
Εάν περιλαμβάνεται ως υποσέλιδο, μια αλλαγή που σπάει τη συμβατότητα ΠΡΕΠΕΙ να αποτελείται από το κεφαλαίο κείμενο BREAKING CHANGE, ακολουθούμενο από άνω και κάτω τελεία, κενό και περιγραφή, π.χ., BREAKING CHANGE: οι μεταβλητές περιβάλλοντος έχουν πλέον προτεραιότητα έναντι των αρχείων διαμόρφωσης.
Εάν περιλαμβάνεται στο πρόθεμα τύπου/scope, οι αλλαγές που σπάνε τη συμβατότητα ΠΡΕΠΕΙ να υποδεικνύονται με ένα ! αμέσως πριν από το :. Εάν χρησιμοποιείται το !, το BREAKING CHANGE: ΜΠΟΡΕΙ να παραλειφθεί από το τμήμα του υποσέλιδου, και η περιγραφή του commit ΠΡΕΠΕΙ να χρησιμοποιείται για την περιγραφή της αλλαγής που σπάει τη συμβατότητα.
Τύποι εκτός από feat και fix ΜΠΟΡΕΙ να χρησιμοποιηθούν στα μηνύματα commit σας, π.χ., docs: update ref docs.
Για τα στοιχεία που συνθέτουν τα Conventional Commits ΔΕΝ ΠΡΕΠΕΙ να γίνεται διάκριση πεζών-κεφαλαίων από τους υλοποιητές, με εξαίρεση το BREAKING CHANGE που ΠΡΕΠΕΙ να είναι με κεφαλαία γράμματα.
Το BREAKING-CHANGE ΠΡΕΠΕΙ να είναι συνώνυμο με το BREAKING CHANGE, όταν χρησιμοποιείται ως token λέξης-κλειδιού σε ένα υποσέλιδο.

Γιατί να χρησιμοποιήσετε τα Conventional Commits

Αυτόματη δημιουργία CHANGELOGs.
Αυτόματος προσδιορισμός μιας αύξησης της σημασιολογικής έκδοσης (με βάση τους τύπους των commits που έχουν ενσωματωθεί).
Επικοινωνία της φύσης των αλλαγών στους συμπαίκτες, το κοινό και άλλους ενδιαφερόμενους.
Ενεργοποίηση διαδικασιών build και publish.
Διευκόλυνση της συνεισφοράς άλλων στα έργα σας, επιτρέποντάς τους να εξερευνήσουν ένα πιο δομημένο ιστορικό των commits.

Συχνές Ερωτήσεις

Πώς πρέπει να χειρίζομαι τα μηνύματα commit στην αρχική φάση ανάπτυξης;

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

Οι τύποι στον τίτλο του commit είναι κεφαλαίοι ή πεζοί;

Μπορεί να χρησιμοποιηθεί οποιαδήποτε μορφή (πεζά ή κεφαλαία), αλλά είναι καλύτερο να είστε συνεπείς.

Τι κάνω αν το commit συμμορφώνεται με περισσότερους από έναν από τους τύπους commit;

Προσπαθήστε να δημιουργήσετε πολλαπλά commits όποτε είναι δυνατόν. Μέρος του οφέλους των Conventional Commits είναι η ικανότητά του να μας οδηγεί στο να κάνουμε πιο οργανωμένα commits και PRs.

Αυτό δεν αποθαρρύνει την ταχεία ανάπτυξη και τη γρήγορη επανάληψη;

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

Μπορεί τα Conventional Commits να οδηγήσουν τους προγραμματιστές να περιορίσουν τον τύπο των commits που κάνουν επειδή θα σκέφτονται με τους παρεχόμενους τύπους;

Τα Conventional Commits μας ενθαρρύνουν να κάνουμε περισσότερους από ορισμένους τύπους commits, όπως διορθώσεις. Πέρα από αυτό, η ευελιξία των Conventional Commits επιτρέπει στην ομάδα σας να δημιουργήσει τους δικούς της τύπους και να τους αλλάξει με την πάροδο του χρόνου.

Πώς σχετίζεται αυτό με το SemVer;

Τα commits τύπου fix πρέπει να μεταφράζονται σε PATCH εκδόσεις. Τα commits τύπου feat πρέπει να μεταφράζονται σε MINOR εκδόσεις. Τα commits με BREAKING CHANGE στα commits, ανεξάρτητα από τον τύπο, πρέπει να μεταφράζονται σε MAJOR εκδόσεις.

Πώς πρέπει να εκδίδω τις επεκτάσεις μου στην Προδιαγραφή Conventional Commits, π.χ. `@jameswomack/conventional-commit-spec`;

Συνιστούμε τη χρήση του SemVer για την κυκλοφορία των δικών σας επεκτάσεων σε αυτήν την προδιαγραφή (και σας ενθαρρύνουμε να κάνετε αυτές τις επεκτάσεις!)

Τι κάνω αν κατά λάθος χρησιμοποιήσω λάθος τύπο commit;

Όταν χρησιμοποιήσατε έναν τύπο που είναι της προδιαγραφής αλλά όχι ο σωστός τύπος, π.χ. `fix` αντί για `feat`

Πριν από τη συγχώνευση ή την κυκλοφορία του λάθους, συνιστούμε τη χρήση του git rebase -i για την επεξεργασία του ιστορικού των commits. Μετά την κυκλοφορία, η διόρθωση θα είναι διαφορετική ανάλογα με τα εργαλεία και τις διαδικασίες που χρησιμοποιείτε.

Όταν χρησιμοποιήσατε έναν τύπο όχι της προδιαγραφής, π.χ. `feet` αντί για `feat`

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

Πρέπει όλοι οι συνεισφέροντες μου να χρησιμοποιούν την προδιαγραφή Conventional Commits;

Όχι! Εάν χρησιμοποιείτε μια ροή εργασίας βασισμένη στο squash στο Git, οι κύριοι συντηρητές μπορούν να επεξεργαστούν τα μηνύματα των commits καθώς τα συγχωνεύουν—χωρίς να προσθέτουν φόρτο εργασίας στους περιστασιακούς συνεισφέροντες. Μια κοινή ροή εργασίας για αυτό είναι το σύστημά σας git να κάνει αυτόματα squash τα commits από ένα pull request και να παρουσιάζει μια φόρμα στον κύριο συντηρητή για να εισαγάγει το σωστό μήνυμα git commit για τη συγχώνευση.

Πώς χειρίζονται τα Conventional Commits τα revert commits;

Η αναίρεση κώδικα μπορεί να είναι περίπλοκη: αναιρείτε πολλαπλά commits; αν αναιρέσετε ένα χαρακτηριστικό, θα πρέπει η επόμενη έκδοση να είναι patch;

Τα Conventional Commits δεν προσπαθούν ρητά να ορίσουν τη συμπεριφορά αναίρεσης. Αντ’ αυτού, το αφήνουμε στους δημιουργούς εργαλείων να χρησιμοποιήσουν την ευελιξία των τύπων (types) και των υποσέλιδων (footers) για να αναπτύξουν τη λογική τους για το χειρισμό των αναιρέσεων.

Μια σύσταση είναι να χρησιμοποιήσετε τον τύπο revert και ένα υποσέλιδο που αναφέρεται στα SHA των commits που αναιρούνται:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Conventional Commits