Πρόταση αλλαγής του κώδικα

Το Nette Framework χρησιμοποιεί το Git και το GitHub για τη συντήρηση της βάσης κώδικα. Ο καλύτερος τρόπος για να συνεισφέρετε είναι να δεσμεύσετε τις αλλαγές σας στο δικό σας fork και στη συνέχεια να κάνετε ένα pull request στο GitHub. Αυτό το έγγραφο συνοψίζει τα κύρια βήματα για την επιτυχή συνεισφορά.

Προετοιμασία περιβάλλοντος

Ξεκινήστε με το forking του Nette στο GitHub. Ρυθμίστε προσεκτικά το τοπικό σας περιβάλλον Git, ρυθμίστε το όνομα χρήστη και το email σας, αυτά τα διαπιστευτήρια θα αναγνωρίσουν τις αλλαγές σας στο ιστορικό του Nette Framework.

Επεξεργασία του Patch σας

Πριν ξεκινήσετε να εργάζεστε πάνω στο patch σας, δημιουργήστε ένα νέο κλάδο για τις αλλαγές σας.

git checkout -b new_branch_name

Μπορείτε να εργαστείτε πάνω στην αλλαγή του κώδικά σας.

Αν είναι δυνατόν, κάντε αλλαγές από την τελευταία έκδοση που κυκλοφόρησε.

Δοκιμή των αλλαγών σας

Πρέπει να εγκαταστήσετε το Nette Tester. Ο ευκολότερος τρόπος είναι να καλέσετε το composer install στη ρίζα του αποθετηρίου. Τώρα θα πρέπει να είστε σε θέση να εκτελέσετε δοκιμές με το ./vendor/bin/tester στο τερματικό.

Ορισμένες δοκιμές μπορεί να αποτύχουν λόγω έλλειψης του php.ini. Επομένως, θα πρέπει να καλέσετε το runner με την παράμετρο -c και να καθορίσετε τη διαδρομή προς το php.ini, για παράδειγμα ./vendor/bin/tester -c ./tests/php.ini.

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

Πρότυπα κωδικοποίησης

Ο κώδικάς σας πρέπει να ακολουθεί τα πρότυπα κωδικοποίησης που χρησιμοποιούνται στο Nette Framework. Είναι εύκολο επειδή υπάρχει αυτοματοποιημένος ελεγκτής & διορθωτής. Μπορεί να εγκατασταθεί μέσω του Composer στον παγκόσμιο κατάλογο που έχετε επιλέξει:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Τώρα θα πρέπει να είστε σε θέση να εκτελέσετε το εργαλείο στο τερματικό. Για παράδειγμα, αυτή η εντολή ελέγχει και διορθώνει τον κώδικα στους φακέλους src και tests στον τρέχοντα κατάλογο:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Μεταφορά των αλλαγών

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

Παρακαλούμε, ελέγξτε δύο φορές ότι ο κώδικάς σας ταιριάζει με τους κανόνες:

  • Ο κώδικας δεν παράγει σφάλματα
  • Ο κώδικάς σας δεν παραβιάζει καμία δοκιμή.
  • Η αλλαγή του κώδικά σας είναι δοκιμασμένη.
  • Δεν διαπράττετε άχρηστες αλλαγές λευκού χώρου.

Το μήνυμα δέσμευσης πρέπει να ακολουθεί τη μορφή Latte: fixed multi template rendering [Closes # 69] δηλ:

  • μια περιοχή ακολουθούμενη από μια άνω και κάτω τελεία
  • ο σκοπός της δέσμευσης στο παρελθόν, αν είναι δυνατόν, ξεκινήστε με “added.”, “fixed.”, “refactored.”, changed, removed
  • ενδεχόμενος σύνδεσμος προς τον ιχνηλάτη ζητημάτων
  • αν η δέσμευση ακυρώνει την προς τα πίσω συμβατότητα, προσθέστε “BC break”
  • μπορεί να υπάρχει μια ελεύθερη γραμμή μετά το θέμα και μια πιο λεπτομερής περιγραφή, συμπεριλαμβανομένων των συνδέσμων προς το φόρουμ.

Pull-Requesting των Commits

Αν είστε ικανοποιημένοι με τις αλλαγές και τις δεσμεύσεις του κώδικά σας, πρέπει να προωθήσετε τις δεσμεύσεις σας στο GitHub.

git push origin new_branch_name

Οι αλλαγές είναι παρούσες δημόσια, ωστόσο, πρέπει να προτείνετε τις αλλαγές σας για ενσωμάτωση στον κύριο κλάδο του Nette. Για να το κάνετε αυτό, κάντε ένα pull request. Κάθε pull request έχει έναν τίτλο και μια περιγραφή. Παρακαλούμε δώστε κάποιον περιγραφικό τίτλο. Συχνά είναι παρόμοιος με το όνομα του κλάδου, για παράδειγμα “Securing signals against CSRF attack”.

Η περιγραφή του pull request θα πρέπει να περιέχει κάποιες πιο συγκεκριμένες πληροφορίες σχετικά με τις αλλαγές στον κώδικά σας:

- bug fix? yes/no   <!-- #issue numbers, if any -->
- new feature? yes/no
- BC break? yes/no
- doc PR: nette/docs#???  <!-- highly welcome, see https://nette.org/en/writing -->

Παρακαλούμε αλλάξτε τον πίνακα πληροφοριών ώστε να ταιριάζει στο pull request σας. Σχόλια σε κάθε στοιχείο του καταλόγου:

  • Λέει αν το pull request προσθέτει feature ή είναι bugfix.
  • Παραπέμπει τελικά σε σχετικό θέμα, το οποίο θα κλείσει μετά τη συγχώνευση του pull request.
  • Λέει αν το pull request χρειάζεται τις αλλαγές τεκμηρίωσης, αν ναι, παρέχετε παραπομπές στα κατάλληλα pull requests. Δεν χρειάζεται να παρέχετε αμέσως την αλλαγή τεκμηρίωσης, ωστόσο, το pull request δεν θα συγχωνευθεί αν η αλλαγή τεκμηρίωσης είναι απαραίτητη. Η αλλαγή τεκμηρίωσης πρέπει να προετοιμαστεί για την αγγλική τεκμηρίωση, οι μεταλλάξεις άλλων γλωσσών είναι προαιρετικές.
  • Λέει αν το pull request δημιουργεί ένα σπάσιμο της BC. Παρακαλώ, θεωρήστε οτιδήποτε αλλάζει τη δημόσια διεπαφή ως BC break.

Ο τελικός πίνακας θα μπορούσε να μοιάζει ως εξής:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Επεξεργασία των αλλαγών σας

Είναι πολύ συνηθισμένο να λαμβάνετε σχόλια για την αλλαγή του κώδικά σας. Παρακαλούμε, προσπαθήστε να ακολουθήσετε τις προτεινόμενες αλλαγές και επεξεργαστείτε τις δεσμεύσεις σας για να το κάνετε αυτό. Μπορείτε να δεσμεύσετε τις προτεινόμενες αλλαγές ως νέες δεσμεύσεις και στη συνέχεια να τις συμπιέσετε με τις προηγούμενες. Ανατρέξτε στο κεφάλαιο Interactive rebase στο GitHub. Αφού επαναπροσδιορίσετε τις αλλαγές σας, προωθήστε τις αλλαγές σας με δύναμη στην απομακρυσμένη διχάλα σας, όλα θα διαδοθούν αυτόματα στο pull request.