configlet sync

Συγχρονισμός δεδομένων ασκήσεων με το αποθετήριο problem-specifications

Μια άσκηση εξάσκησης σε μια διαδρομή στο Exercism υλοποιείται συχνά από μια προδιαγραφή στο αποθετήριο exercism/problem-specifications.

Το Exercism απαιτεί σκόπιμα κάθε άσκηση να έχει το δικό της αντίγραφο ορισμένων αρχείων (όπως το .docs/instructions.md), ακόμα κι όταν αυτή η άσκηση υπάρχει στο problem-specifications. Γι' αυτό το configlet διαθέτει μια εντολή sync, η οποία μπορεί να ελέγξει αν τέτοιες ασκήσεις εξάσκησης σε μια διαδρομή είναι συγχρονισμένες με αυτήν την πηγή upstream, και μπορεί να τις ενημερώσει όταν υπάρχουν διαθέσιμες ενημερώσεις.

Υπάρχουν τρία είδη δεδομένων που μπορούν να ενημερωθούν από το problem-specifications: η τεκμηρίωση, τα μεταδεδομένα και οι δοκιμές. Υπάρχει επίσης ένα είδος δεδομένων που μπορεί να συμπληρωθεί από το αρχείο config.json της διαδρομής: οι διαδρομές αρχείων στα αρχεία config των ασκήσεων.

Περιγράφουμε τον έλεγχο και την ενημέρωση αυτών των ειδών δεδομένων σε ξεχωριστές ενότητες παρακάτω, αλλά ως γρήγορη σύνοψη:

  • Το configlet sync λειτουργεί μόνο σε ασκήσεις που υπάρχουν στο αρχείο config.json της διαδρομής. Επομένως, αν υλοποιείς μια νέα άσκηση σε μια διαδρομή και θέλεις να προσθέσεις τα αρχικά αρχεία με το configlet sync, πρόσθεσε πρώτα την άσκηση στο αρχείο config.json της διαδρομής. Αν η άσκηση δεν είναι ακόμα έτοιμη να είναι ορατή στους χρήστες, όρισε την τιμή status της σε wip.
  • Ένα σκέτο configlet sync δεν κάνει καμία αλλαγή στη διαδρομή και ελέγχει κάθε είδος δεδομένων για κάθε άσκηση.
  • Για να λειτουργήσεις σε ένα υποσύνολο ειδών δεδομένων, χρησιμοποίησε κάποιον συνδυασμό των επιλογών --docs, --filepaths, --metadata και --tests.
  • Για να ενημερώσεις διαδραστικά δεδομένα στη διαδρομή, χρησιμοποίησε την επιλογή --update.
  • Για να ενημερώσεις μη διαδραστικά την τεκμηρίωση, τις διαδρομές αρχείων και τα μεταδεδομένα στη διαδρομή, χρησιμοποίησε --update --yes.
  • Για να συμπεριλάβεις μη διαδραστικά κάθε δοκιμή που δεν έχει εμφανιστεί για μια δεδομένη άσκηση, χρησιμοποίησε π.χ. --update --tests include --exercise prime-factors.
  • Για να παραλείψεις τη λήψη του αποθετηρίου problem-specifications, πρόσθεσε --offline --prob-specs-dir /path/to/local/problem-specifications
  • Σημείωσε ότι το configlet sync προσπαθεί να διατηρήσει τη σειρά των κλειδιών στα αρχεία .meta/config.json των ασκήσεων όταν ενημερώνει. Για να γράψεις αυτά τα αρχεία σε κανονική μορφή χωρίς συγχρονισμό, χρησιμοποίησε την εντολή configlet fmt. Ωστόσο, το configlet sync προσθέτει (πιθανώς κενά) υποχρεωτικά κλειδιά (authors, files, blurb) όταν λείπουν. Αυτό είναι λιγότερο "σαν συγχρονισμός", αλλά πιο εργονομικό: όταν υλοποιείς μια νέα άσκηση, μπορείς να χρησιμοποιήσεις το sync για να δημιουργήσεις ένα αρχικό αρχείο .meta/config.json.
  • Το configlet sync αφαιρεί κλειδιά που δεν υπάρχουν στην προδιαγραφή. Τα προσαρμοσμένα ζεύγη κλειδιού/τιμής εξακολουθούν να υποστηρίζονται: πρέπει να γράφονται μέσα σε ένα αντικείμενο JSON με όνομα custom.
  • Ο κωδικός εξόδου είναι 0 όταν όλα τα δεδομένα που έχει δει το configlet είναι συγχρονισμένα κατά την έξοδό του, και 1 διαφορετικά.

Σημείωσε ότι στις εκδόσεις του configlet 4.0.0-alpha.34 και παλαιότερες, η εντολή sync λειτουργούσε μόνο σε δοκιμές.

Χρήση

Η εντολή sync μπορεί να χρησιμοποιηθεί για να ελέγξει ή να ενημερώσει την τεκμηρίωση, τα μεταδεδομένα και τις δοκιμές μιας άσκησης εξάσκησης από το "problem-specifications". Μπορεί επίσης να ελέγξει ή να συμπληρώσει τιμές files που λείπουν για ασκήσεις εννοιών/εξάσκησης από το "config.json" της διαδρομής.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

Τεκμηρίωση

Μια άσκηση εξάσκησης που προέρχεται από το αποθετήριο problem-specifications πρέπει να έχει ένα αρχείο .docs/instructions.md (και πιθανώς και ένα αρχείο .docs/introduction.md) που να περιέχει την τεκμηρίωση της άσκησης από το problem-specifications.

Για να ελέγξεις κάθε άσκηση εξάσκησης στη διαδρομή για διαθέσιμες ενημερώσεις τεκμηρίωσης (με έξοδο με μη μηδενικό κωδικό εξόδου αν υπάρχει τουλάχιστον μία διαθέσιμη ενημέρωση):

configlet sync --docs

Για να ενημερώσεις διαδραστικά την τεκμηρίωση για κάθε άσκηση εξάσκησης, πρόσθεσε την επιλογή --update (ή -u για συντομία):

configlet sync --docs --update

Για να ενημερώσεις μη διαδραστικά την τεκμηρίωση για κάθε άσκηση εξάσκησης, πρόσθεσε την επιλογή --yes (ή -y για συντομία):

configlet sync --docs --update --yes

Για να λειτουργήσεις σε μία μόνο άσκηση εξάσκησης, χρησιμοποίησε την επιλογή --exercise (ή -e για συντομία). Για παράδειγμα, για να ενημερώσεις μη διαδραστικά την τεκμηρίωση της άσκησης prime-factors:

configlet sync --docs -uy -e prime-factors

Μεταδεδομένα

Κάθε άσκηση σε μια διαδρομή πρέπει να έχει ένα αρχείο .meta/config.json. Για μια άσκηση εξάσκησης που προέρχεται από το αποθετήριο problem-specifications, αυτό το αρχείο πρέπει να περιέχει τα ζεύγη κλειδιού/τιμής blurb, source και source_url που υπάρχουν στο αντίστοιχο αρχείο metadata.toml upstream.

Για να ελέγξεις κάθε άσκηση εξάσκησης για διαθέσιμες ενημερώσεις μεταδεδομένων (με έξοδο με μη μηδενικό κωδικό εξόδου αν υπάρχει τουλάχιστον μία διαθέσιμη ενημέρωση):

configlet sync --metadata

Για να ενημερώσεις διαδραστικά τα μεταδεδομένα για κάθε άσκηση εξάσκησης, πρόσθεσε την επιλογή --update (ή -u για συντομία):

configlet sync --metadata --update

Για να ενημερώσεις μη διαδραστικά τα μεταδεδομένα για κάθε άσκηση εξάσκησης, πρόσθεσε την επιλογή --yes (ή -y για συντομία):

configlet sync --metadata --update --yes

Για να λειτουργήσεις σε μία μόνο άσκηση εξάσκησης, χρησιμοποίησε την επιλογή --exercise (ή -e για συντομία). Για παράδειγμα, για να ενημερώσεις μη διαδραστικά τα μεταδεδομένα της άσκησης prime-factors:

configlet sync --metadata -uy -e prime-factors

Δοκιμές

Αν μια διαδρομή υλοποιεί μια άσκηση για την οποία υπάρχουν δεδομένα δοκιμών στο αποθετήριο problem-specifications, η άσκηση πρέπει να περιέχει ένα αρχείο .meta/tests.toml. Ο σκοπός του αρχείου tests.toml είναι να παρακολουθεί ποιες δοκιμές υλοποιούνται από την άσκηση. Οι δοκιμές σε αυτό το αρχείο αναγνωρίζονται από το UUID τους και κάθε δοκιμή έχει μια τιμή Boolean (λογική τιμή) που δείχνει αν υλοποιείται από αυτήν την άσκηση.

Ένα αρχείο tests.toml έχει αυτήν τη μορφή:

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

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

Για να ελέγξεις κάθε αρχείο tests.toml άσκησης εξάσκησης για διαθέσιμες ενημερώσεις δοκιμών (με έξοδο με μη μηδενικό κωδικό εξόδου αν υπάρχει τουλάχιστον μία περίπτωση δοκιμής που εμφανίζεται στα κανονικά δεδομένα της άσκησης αλλά όχι στο tests.toml):

configlet sync --tests

Για να ενημερώσεις διαδραστικά το αρχείο tests.toml για κάθε άσκηση εξάσκησης, πρόσθεσε την επιλογή --update:

configlet sync --tests --update

Για κάθε δοκιμή που λείπει, αυτό ζητά από τον χρήστη να επιλέξει αν θα τη συμπεριλάβει, θα την αποκλείσει ή θα την παραλείψει, και ενημερώνει ανάλογα το αντίστοιχο αρχείο tests.toml. Το configlet γράφει το αρχείο tests.toml μιας άσκησης αφού ο χρήστης ολοκληρώσει τις επιλογές του για αυτήν την άσκηση. Αυτό σημαίνει ότι μπορείς να τερματίσεις το configlet σε μια ερώτηση (για παράδειγμα, πατώντας Ctrl-C στο τερματικό) και να χάσεις τις αποφάσεις συγχρονισμού για μία το πολύ άσκηση.

Για να συμπεριλάβεις μη διαδραστικά κάθε περίπτωση δοκιμής που δεν έχει εμφανιστεί, χρησιμοποίησε --tests include. Για παράδειγμα, για να το κάνεις αυτό για μια άσκηση με όνομα prime-factors:

configlet sync --tests include -u -e prime-factors

Μην ξεχάσεις να υλοποιήσεις πραγματικά αυτές τις δοκιμές στη διαδρομή!

Διαδρομές αρχείων

Τέλος, η εντολή sync χειρίζεται επίσης τον "συγχρονισμό" από μια πηγή που δεν είναι το problem-specifications: το αρχείο config.json της διαδρομής. Κάθε άσκηση εννοιών και άσκηση εξάσκησης πρέπει να έχει ένα αρχείο .meta/config.json με ένα αντικείμενο files που καθορίζει τις (σχετικές) τοποθεσίες των αρχείων που χρησιμοποιεί η άσκηση. Τέτοιες διαδρομές αρχείων ακολουθούν συνήθως ένα απλό μοτίβο, οπότε το configlet μπορεί να συμπληρώσει τις τιμές σε επίπεδο άσκησης από μοτίβα στο κλειδί files του αρχείου config.json της διαδρομής.

Για να ελέγξεις ότι κάθε άσκηση εννοιών και άσκηση εξάσκησης στη διαδρομή έχει ένα πλήρως συμπληρωμένο κλειδί files (ή τουλάχιστον ένα που δεν μπορεί να συμπληρωθεί από το κλειδί files της διαδρομής):

configlet sync --filepaths

(Σημείωσε ότι το configlet lint θα παράγει επίσης ένα σφάλμα όταν μια άσκηση έχει κλειδί files που λείπει ή είναι κενό.)

Για να συμπληρώσεις κενές ή απούσες τιμές του κλειδιού files σε επίπεδο άσκησης για κάθε άσκηση εννοιών και άσκηση εξάσκησης, από τα μοτίβα στο κλειδί files της διαδρομής:

configlet sync --filepaths --update

Για να το κάνεις αυτό μη διαδραστικά και για μία μόνο άσκηση με όνομα prime-factors:

configlet sync --filepaths -uy -e prime-factors

Χρήση του sync όταν προσθέτεις μια νέα άσκηση σε μια διαδρομή

Η εντολή sync είναι χρήσιμη όταν προσθέτεις μια νέα άσκηση σε μια διαδρομή. Αν προσθέτεις μια άσκηση εξάσκησης με όνομα foo που υπάρχει στο problem-specifications, μια πιθανή ροή εργασίας είναι:

  1. Πρόσθεσε χειροκίνητα μια καταχώριση στο αρχείο config.json της διαδρομής για την άσκηση foo. Έτσι η άσκηση γίνεται ορατή στο configlet sync.
  2. Τρέξε το configlet sync --docs --filepaths --metadata -uy -e foo για να δημιουργήσεις την τεκμηρίωση της άσκησης και ένα αρχικό αρχείο .meta/config.json με συμπληρωμένες τιμές files, blurb και ίσως source και source_url.
  3. Επεξεργάσου το αρχείο .meta/config.json της άσκησης όπως θέλεις. Για παράδειγμα, πρόσθεσε τον εαυτό σου στον πίνακα authors.
  4. Τρέξε το configlet sync --tests include -u -e foo για να δημιουργήσεις ένα αρχείο .meta/tests.toml με κάθε δοκιμή συμπεριλημμένη.
  5. Δες αυτό το αρχείο .meta/tests.toml και πρόσθεσε include = false σε κάθε περίπτωση δοκιμής που η άσκηση δεν θα υλοποιήσει.
  6. Υλοποίησε τις δοκιμές για την άσκηση ώστε να ταιριάζουν με αυτές που περιλαμβάνονται στο .meta/tests.toml.
  7. Πρόσθεσε τα άλλα απαιτούμενα αρχεία.