Σημασιολογική Δημιουργία Εκδόσεων 2.0.0 (Semantic Versioning)

Περίληψη

Δοθέντος ενός αριθμού έκδοσης ΚΥΡΙΑ.ΔΕΥΤΕΡΕΥΟΥΣΑ.ΔΙΟΡΘΩΣΗ (MAJOR.MINOR.PATCH), αυξήστε την:

  1. ΚΥΡΙΑ έκδοση, όταν κάνετε ασύμβατες αλλαγές στο API
  2. ΔΕΥΤΕΡΕΥΟΥΣΑ έκδοση, όταν προσθέτετε λειτουργικότητα με τρόπο συμβατό προς τα πίσω
  3. ΔΙΟΡΘΩΤΙΚΗ έκδοση, όταν κάνετε επιδιορθώσεις σφαλμάτων με τρόπο συμβατό προς τα πίσω

Πρόσθετες ετικέτες για μεταδεδομένα προ-κυκλοφορίας και χτισίματος, είναι διαθέσιμες ως επεκτάσεις στη μορφή ΚΥΡΙΑ.ΔΕΥΤΕΡΕΥΟΥΣΑ.ΔΙΟΡΘΩΣΗ.

Εισαγωγή

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

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

Ως μια λύση σ’ αυτό το πρόβλημα, προτείνουμε ένα απλό σετ κανόνων και απαιτήσεων που υπαγορεύουν το πως οι αριθμοί εκδόσεων καθορίζονται και αυξάνονται. Αυτοί οι κανόνες βασίζονται, αλλά δεν περιορίζονται απαραίτητα, σε προϋπάρχουσες διαδεδομένες κοινές πρακτικές σε χρήση τόσο σε κλειστό όσο και σε λογισμικό ανοιχτού κώδικα. Για να λειτουργήσει αυτό το σύστημα, πρώτα πρέπει να δηλώσετε ένα δημόσιο API. Αυτό μπορεί να αποτελείται από τεκμηρίωση ή να επιβάλλεται από τον ίδιο τον κώδικα. Όπως και να ‘χει είναι σημαντικό αυτό το API να είναι ξεκάθαρο και συγκεκριμένο. Μόλις ταυτοποιήσετε το δημόσιο API, κοινοποιείτε τις αλλαγές σ’ αυτό με συγκεκριμένες αυξήσεις στον αριθμό έκδοσης. Σκεφτείτε μία έκδοση της μορφής X.Y.Z (Κύρια.Δευτερεύουσα.Διόρθωση). Διορθώσεις σφαλμάτων που δεν επηρεάζουν το API αυξάνουν την έκδοση διόρθωσης, προσθήκες/αλλαγές στο API οι οποίες είναι συμβατές προς τα πίσω αυξάνουν τη δευτερεύουσα έκδοση, και αλλαγές ασύμβατες με το API αυξάνουν την κύρια έκδοση.

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

Προδιαγραφή της Σημασιολογικής Δημιουργίας Εκδόσεων (SemVer)

Οι λέξεις κλειδιά «ΠΡΕΠΕΙ» (MUST), «ΔΕΝ ΠΡΕΠΕΙ» (MUST NOT), «ΑΠΑΙΤΕΙΤΑΙ» (REQUIRED), «ΠΡΕΠΕΙ» (SHALL), «ΔΕΝ ΠΡΕΠΕΙ» (SHALL NOT), «ΣΥΝΙΣΤΆΤΑΙ» (SHOULD), «ΔΕ ΣΥΝΙΣΤΆΤΑΙ» (SHOULD NOT), «ΣΥΝΙΣΤΆΤΑΙ» (RECOMMENDED), «ΜΠΟΡΕΙ» (MAY), και «ΠΡΟΑΙΡΕΤΙΚΑ» (OPTIONAL) σε αυτό το έγγραφο, πρέπει να ερμηνεύονται όπως περιγράφεται στο RFC 2119.

  1. Λογισμικό που χρησιμοποιεί Σημασιολογική δημιουργία εκδόσεων ΠΡΕΠΕΙ να δηλώνει ένα δημόσιο API. Αυτό το API μπορεί να δηλωθεί στον ίδιο τον κώδικα του ή να υπάρχει αποκλειστικά στην τεκμηρίωση. Όπως και αν γίνει, ΣΥΝΙΣΤΆΤΑΙ να είναι ακριβές και εμπεριστατωμένο.

  2. Ένας φυσιολογικός αριθμός έκδοσης ΠΡΕΠΕΙ να έχει τη μορφή X.Y.Z όπου X, Y, και Z είναι μη-αρνητικοί ακέραιοι, που ΔΕΝ ΠΡΕΠΕΙ να περιέχουν προπορευόμενα μηδενικά. Το Χ είναι η κύρια έκδοση, το Υ είναι η δευτερεύουσα έκδοση, και το Ζ είναι η έκδοση διόρθωσης. Κάθε στοιχείο ΠΡΕΠΕΙ να αυξάνεται αριθμητικά. Για παράδειγμα: 1.9.0 -> 1.10.0 -> 1.11.0.

  3. Μόλις ένα πακέτο με έκδοση κυκλοφορήσει, τα περιεχόμενα αυτής της έκδοσης ΔΕΝ ΠΡΕΠΕΙ να τροποποιηθούν. Κάθε τροποποίηση ΠΡΕΠΕΙ να κυκλοφορεί με νέα έκδοση.

  4. Ο αριθμός κύριας έκδοσης μηδέν (0.y.z) είναι για την αρχική ανάπτυξη. Οτιδήποτε ΜΠΟΡΕΙ να αλλάξει οποιαδήποτε στιγμή. Το δημόσιο API ΔΕ ΣΥΝΙΣΤΆΤΑΙ να θεωρείται σταθερό.

  5. Η έκδοση 1.0.0 ορίζει το δημόσιο API. Ο τρόπος με τον οποίο ο αριθμός έκδοσης αυξάνεται μετά από κάθε κυκλοφορία, εξαρτάται από αυτό το δημόσιο API και το πως αλλάζει.

  6. Η Διορθωτική έκδοση Z (x.y.Z | x > 0) ΠΡΕΠΕΙ να αυξάνεται μόνο αν εισάγονται διορθώσεις σφαλμάτων συμβατές προς τα πίσω. Μία διόρθωση σφάλματος ορίζεται ως μια εσωτερική αλλαγή που διορθώνει μια εσφαλμένη συμπεριφορά.

  7. Η Δευτερεύουσα έκδοση Y (x.Y.z | x > 0) ΠΡΕΠΕΙ να αυξάνεται αν μια νέα, συμβατή προς τα πίσω, λειτουργικότητα, εισάγεται στο δημόσιο API. ΠΡΕΠΕΙ να αυξάνεται αν κάποια λειτουργικότητα, οποιουδήποτε δημόσιου API, χαρακτηρίζεται ως καταργημένη. ΜΠΟΡΕΙ να αυξηθεί αν σημαντική νέα λειτουργικότητα ή βελτιώσεις εισάγονται μαζί με τον ιδιωτικό κώδικα. ΜΠΟΡΕΙ να περιλαμβάνει αλλαγές επιπέδου διόρθωσης. Η έκδοση διόρθωσης ΠΡΕΠΕΙ να επανέλθει στο 0 όταν μία δευτερεύουσα έκδοση αυξάνεται.

  8. Η Κύρια έκδοση X (X.y.z | X > 0) ΠΡΕΠΕΙ να αυξάνεται αν εισάγονται στο δημόσιο API οποιεσδήποτε αλλαγές που είναι ασύμβατες προς τα πίσω. ΜΠΟΡΕΙ επίσης να συμπεριλαμβάνει δευτερεύουσες και διορθωτικές αλλαγές. Οι διορθωτικές και οι δευτερεύουσες εκδόσεις ΠΡΕΠΕΙ να επανέρχονται στο 0 όταν η κύρια έκδοση αυξάνεται.

  9. Μια έκδοση προ-κυκλοφορίας ΜΠΟΡΕΙ να επισημαίνεται επισυνάπτοντας μία παύλα και μία σειρά από αναγνωριστικά διαχωρισμένα με τελεία, αμέσως μετά την έκδοση διόρθωσης. Τα αναγνωριστικά ΠΡΕΠΕΙ να αποτελούνται μόνο από αλφαριθμητικούς χαρακτήρες ASCII και παύλες [0-9A-Za-z-]. Τα αναγνωριστικά ΔΕΝ ΠΡΕΠΕΙ να είναι κενά. Τα αριθμητικά αναγνωριστικά ΔΕΝ ΠΡΕΠΕΙ να περιλαμβάνουν προπορευόμενα μηδενικά. Οι εκδόσεις προ-κυκλοφορίας έχουν χαμηλότερη προτεραιότητα από τη συσχετιζόμενη φυσιολογική έκδοση. Μία έκδοση προ-κυκλοφορίας υποδεικνύει ότι η έκδοση είναι ασταθής και μπορεί να μην ικανοποιεί τις επιθυμητές απαιτήσεις συμβατότητας όπως επισημαίνεται από τη συσχετιζόμενη φυσιολογική έκδοση. Παραδείγματα: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

  10. Μεταδεδομένα χτισίματος ΜΠΟΡΕΙ να επισημαίνονται επισυνάπτοντας το σύμβολο της πρόσθεσης και μία σειρά από αναγνωριστικά διαχωρισμένα με τελεία, αμέσως μετά τη διόρθωση ή την έκδοση προ-κυκλοφορίας. Τα αναγνωριστικά ΠΡΕΠΕΙ να αποτελούνται μόνο από αλφαριθμητικούς χαρακτήρες ASCII και παύλες [0-9A-Za-z-]. Τα αναγνωριστικά ΔΕΝ ΠΡΕΠΕΙ να είναι κενά. Τα μεταδεδομένα χτισίματος ΠΡΕΠΕΙ να αγνοούνται όταν αποφασίζεται η προτεραιότητα έκδοσης. Συνεπώς, όταν δύο εκδόσεις διαφέρουν μόνο στα μεταδεδομένα χτισίματος, τότε έχουν την ίδια προτεραιότητα. Παραδείγματα: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

  11. Ως προτεραιότητα αναφέρεται το πως δύο εκδόσεις συγκρίνονται μεταξύ τους όταν ταξινομούνται.

    1. Η προτεραιότητα ΠΡΕΠΕΙ να υπολογίζεται διαχωρίζοντας την έκδοση στα επιμέρους κύρια, δευτερεύοντα, διορθωτικά και προ-κυκλοφορίας αναγνωριστικά, με αυτή τη σειρά (Τα μεταδεδομένα χτισίματος δε λαμβάνονται υπόψη στην προτεραιότητα).

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

      Παράδειγμα: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.

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

      Παράδειγμα: 1.0.0-alpha < 1.0.0.

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

      1. Αναγνωριστικά που αποτελούνται μόνο από ψηφία συγκρίνονται αριθμητικά.

      2. Αναγνωριστικά με γράμματα ή παύλες συγκρίνονται λεξιλογικά με σειρά ταξινόμησης ASCII.

      3. Τα αριθμητικά αναγνωριστικά πάντα έχουν χαμηλότερη προτεραιότητα από τα μη-αριθμητικά αναγνωριστικά.

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

      Παράδειγμα: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Γραμματική της Μορφής Μπάκους-Νάουρ για έγκυρες εκδόσεις SemVer

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

<version core> ::= <major> "." <minor> "." <patch>

<major> ::= <numeric identifier>

<minor> ::= <numeric identifier>

<patch> ::= <numeric identifier>

<pre-release> ::= <dot-separated pre-release identifiers>

<dot-separated pre-release identifiers> ::= <pre-release identifier>
                                          | <pre-release identifier> "." <dot-separated pre-release identifiers>

<build> ::= <dot-separated build identifiers>

<dot-separated build identifiers> ::= <build identifier>
                                    | <build identifier> "." <dot-separated build identifiers>

<pre-release identifier> ::= <alphanumeric identifier>
                           | <numeric identifier>

<build identifier> ::= <alphanumeric identifier>
                     | <digits>

<alphanumeric identifier> ::= <non-digit>
                            | <non-digit> <identifier characters>
                            | <identifier characters> <non-digit>
                            | <identifier characters> <non-digit> <identifier characters>

<numeric identifier> ::= "0"
                       | <positive digit>
                       | <positive digit> <digits>

<identifier characters> ::= <identifier character>
                          | <identifier character> <identifier characters>

<identifier character> ::= <digit>
                         | <non-digit>

<non-digit> ::= <letter>
              | "-"

<digits> ::= <digit>
           | <digit> <digits>

<digit> ::= "0"
          | <positive digit>

<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
           | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
           | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
           | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
           | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
           | "y" | "z"

Γιατί να χρησιμοποιήσετε Σημασιολογική Δημιουργία Εκδόσεων;

Αυτή δεν είναι μια νέα ή επαναστατική ιδέα. Στην πραγματικότητα, πιθανά ήδη κάνετε κάτι κοντινό σ’ αυτό. Το πρόβλημα είναι ότι το «κοντινό» δεν είναι αρκετά καλό. Χωρίς συμμόρφωση σε κάποια μορφή επίσημης προδιαγραφής, οι αριθμοί εκδόσεων είναι ουσιαστικά ανώφελοι στη διαχείριση εξαρτήσεων. Δίνοντας ένα όνομα και ξεκάθαρη ερμηνεία στις παραπάνω ιδέες, γίνεται εύκολο να κοινοποιήσετε τις προθέσεις σας στους χρήστες του λογισμικού σας. Μόλις αυτές οι προθέσεις ξεκαθαριστούν, μπορούν τελικά να κατασκευαστούν ευέλικτες (αλλά όχι πολύ ευέλικτες) προδιαγραφές εξαρτήσεων.

Ένα απλό παράδειγμα θα επιδείξει πως η Σημασιολογική Δημιουργία Εκδόσεων μπορεί να κάνει την κόλαση εξαρτήσεων παρελθόν. Σκεφτείτε μια βιβλιοθήκη που ονομάζεται «Πυροσβεστικό». Αυτή χρειάζεται ένα πακέτο που χρησιμοποιεί Σημασιολογική Δημιουργία Εκδόσεων και ονομάζεται «Σκάλα». Κατά τη χρονική στιγμή που το Πυροσβεστικό δημιουργείται, η Σκάλα είναι στην έκδοση 3.1.0. Επειδή το Πυροσβεστικό χρησιμοποιεί κάποια λειτουργικότητα που πρωτοεισάχθηκε στην 3.1.0, μπορείτε με ασφάλεια να ορίσετε την εξάρτηση από την Σκάλα ως μεγαλύτερη ή ίση με 3.1.0, αλλά μικρότερη από 4.0.0. Τώρα, όταν γίνει διαθέσιμη η έκδοση 3.1.1 και 3.2.0 της Σκάλας, μπορείτε να τις κυκλοφορήσετε στο δικό σας σύστημα διαχείρισης πακέτων, και να γνωρίζετε ότι θα είναι συμβατές με το υπάρχον εξαρτημένο λογισμικό.

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

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

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

Πώς να χειριστώ τις αλλαγές στη φάση της αρχικής ανάπτυξης 0.y.z;

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

Πώς μπορώ να γνωρίζω πότε να κυκλοφορήσω την 1.0.0;

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

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

Η κύρια έκδοση μηδέν είναι για την ταχεία ανάπτυξη. Αν αλλάζετε το API κάθε μέρα, είτε παραμείνετε στην έκδοση 0.y.z, είτε μεταβείτε σε ένα διαφορετικό κλάδο ανάπτυξης, καθώς εργάζεστε για την επόμενη κύρια έκδοση.

Αν ακόμη και η μικρότερη αλλαγή στο δημόσιο API, που είναι ασύμβατη προς τα πίσω, απαιτεί αύξηση της κύριας έκδοσης, δε θα καταλήξω στην έκδοση 42.0.0 πολύ γρήγορα;

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

Η πλήρης τεκμηρίωση του δημόσιου API είναι πολύ δουλειά!

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

Τι κάνω εάν κατά λάθος κυκλοφορήσω μια μη συμβατή αλλαγή ως δευτερεύουσα έκδοση;

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

Τι πρέπει να κάνω αν ενημερώσω τις δικές μου εξαρτήσεις χωρίς να αλλάξω το δημόσιο API;

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

Τι θα συμβεί αν κατά λάθος αλλάξω το δημόσιο API με τρόπο που δε συμμορφώνεται με την αλλαγή του αριθμού έκδοσης (δηλαδή ο κώδικας εισάγει εσφαλμένα μια κύρια ασύμβατη αλλαγή, σε μια διορθωτική κυκλοφορία);

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

Πώς πρέπει να χειριστώ τη λειτουργικότητα που καταργείται;

Η κατάργηση υπάρχουσας λειτουργικότητας είναι φυσιολογικό μέρος της ανάπτυξης λογισμικού και συχνά απαιτείται για να σημειωθεί πρόοδος. Όταν καταργείτε μέρος του δημόσιου API σας, θα πρέπει να κάνετε δύο πράγματα: (1) να ενημερώσετε την τεκμηρίωσή για να μάθουν οι χρήστες σχετικά με την αλλαγή, (2) να εκδώσετε μια νέα δευτερεύουσα κυκλοφορία με την κατάργηση. Προτού αφαιρέσετε εντελώς τη λειτουργικότητα σε μια νέα κύρια κυκλοφορία, θα πρέπει να υπάρχει τουλάχιστον μία δευτερεύουσα κυκλοφορία που να περιέχει την κατάργηση, ώστε οι χρήστες να μπορούν να μεταβούν ομαλά στο νέο API.

Έχει το SemVer όριο μεγέθους στη συμβολοσειρά έκδοσης;

Όχι, αλλά χρησιμοποιήστε καλή κρίση. Μια συμβολοσειρά έκδοσης 255 χαρακτήρων για παράδειγμα, είναι πιθανώς υπερβολική. Επίσης, συγκεκριμένα συστήματα μπορεί να επιβάλλουν τα δικά τους όρια στο μέγεθος της συμβολοσειράς.

Είναι το «v1.2.3» μια σημασιολογική έκδοση;

Όχι, το «v1.2.3» δεν είναι σημασιολογική έκδοση. Ωστόσο, το πρόθεμα μιας σημασιολογικής έκδοσης με ένα «v», είναι ένας συνηθισμένος τρόπος (στα Αγγλικά) για να δηλωθεί ότι είναι αριθμός έκδοσης. Η συντομογραφία του «version» ως «v» εμφανίζεται συχνά με τον έλεγχο εκδόσεων. Παράδειγμα: git tag v1.2.3 -m "Έκδοση κυκλοφορίας 1.2.3", στην περίπτωση αυτή το «v1.2.3» είναι το όνομα μιας ετικέτας και η σημασιολογική έκδοση είναι «1.2.3».

Υπάρχει μια προτεινόμενη κανονική έκφραση (RegEx) για τον έλεγχο μιας συμβολοσειράς SemVer;

Υπάρχουν δύο. Μία με ονοματισμένες ομάδες, named groups, για εκείνα τα συστήματα που τα υποστηρίζουν (PCRE [Perl Compatible Regular Expressions, δηλ. Perl, PHP και R], Python και Go).

Δείτε: https://regex101.com/r/Ly7O1x/3/

^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Και μία με αριθμημένες ομάδες σύληψης, capture groups, (έτσι cg1 = κύρια, cg2 = δευτερεύουσα, cg3 = διορθωτική, cg4 = προκυκλοφορία και cg5 = μεταδεδομέναχτισίματος) που είναι συμβατή με ECMA Script (JavaScript), PCRE (Perl Compatible Regular Expressions, δηλαδή Perl, PHP και R), Python και Go.

Δείτε: https://regex101.com/r/vkijKf/1/

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Περί

Η προδιαγραφή Σημασιολογικής Δημιουργίας Εκδόσεων συγγράφηκε αρχικά από τον Tom Preston-Werner, δημιουργό του Gravatar και συνιδρυτή του GitHub.

Την αρχική μετάφραση στα Ελληνικά έκανε ο Ευάγγελος Σκαρμούτσος

Αν θέλετε να αφήσετε τα σχόλιά σας, παρακαλώ ανοίξτε ένα issue στο GitHub.

Άδεια

Creative Commons ― CC BY 3.0