Συμβολή στον κώδικα

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

Διαδικασία

Για να συνεισφέρετε στον κώδικα, είναι απαραίτητο να έχετε έναν λογαριασμό στο GitHub και να είστε εξοικειωμένοι με τα βασικά στοιχεία της εργασίας με το σύστημα ελέγχου εκδόσεων Git. Αν δεν είστε εξοικειωμένοι με το Git, μπορείτε να διαβάσετε το git – the simple guide και να εξετάσετε το ενδεχόμενο να χρησιμοποιήσετε έναν από τους πολλούς γραφικούς πελάτες.

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

  1. Στο GitHub, δημιουργήστε μια διακλάδωση του αποθετηρίου πακέτων που σκοπεύετε να τροποποιήσετε
  2. Κλωνοποιήστε αυτό το αποθετήριο στον υπολογιστή σας
  3. Εγκαταστήστε τις εξαρτήσεις, συμπεριλαμβανομένου του Nette Tester, χρησιμοποιώντας την εντολή composer install
  4. Επαληθεύστε ότι οι δοκιμές λειτουργούν εκτελώντας την εντολή composer tester
  5. Δημιουργήστε έναν νέο κλάδο με βάση την τελευταία έκδοση που κυκλοφόρησε

Εφαρμογή των δικών σας αλλαγών

Τώρα μπορείτε να κάνετε τις δικές σας προσαρμογές στον κώδικα:

  1. Εφαρμόστε τις επιθυμητές αλλαγές και μην ξεχνάτε τις δοκιμές
  2. Βεβαιωθείτε ότι οι δοκιμές εκτελούνται με επιτυχία χρησιμοποιώντας composer tester
  3. Ελέγξτε αν ο κώδικας πληροί τα πρότυπα κωδικοποίησης
  4. Αποθηκεύστε (commit) τις αλλαγές με μια περιγραφή αυτής της μορφής

Μπορείτε να δημιουργήσετε πολλαπλές δεσμεύσεις, μία για κάθε λογικό βήμα. Κάθε commit θα πρέπει να έχει νόημα από μόνο του.

Υποβολή αλλαγών

Αφού είστε ικανοποιημένοι με τις αλλαγές, μπορείτε να τις υποβάλετε:

  1. Σπρώξτε τις αλλαγές στο GitHub στο fork σας
  2. Από εκεί, υποβάλετε τις στο αποθετήριο Nette δημιουργώντας ένα pull request (PR)
  3. Παρέχετε επαρκείς πληροφορίες στην περιγραφή

Ενσωμάτωση ανατροφοδότησης

Οι δεσμεύσεις σας είναι τώρα ορατές στους άλλους. Είναι σύνηθες να λαμβάνετε σχόλια με προτάσεις:

  1. Να παρακολουθείτε τις προτεινόμενες αλλαγές
  2. Ενσωματώστε τις ως νέες commits ή συγχωνεύστε τις με προηγούμενες
  3. Υποβάλετε εκ νέου τα commits στο GitHub, και θα εμφανιστούν αυτόματα στο pull request

Ποτέ μην δημιουργείτε νέο pull request για να τροποποιήσετε ένα υπάρχον.

Τεκμηρίωση

Εάν έχετε αλλάξει τη λειτουργικότητα ή έχετε προσθέσει μια νέα, μην ξεχάσετε να την προσθέσετε και στην τεκμηρίωση.

Νέος κλάδος

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

git checkout -b new_branch_name v3.2.1

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

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

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

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

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Περιγραφή δέσμευσης

Στη Nette, τα θέματα των δεσμεύσεων έχουν την ακόλουθη μορφή: Presenter: fixed AJAX detection [Closes #69]

  • περιοχή ακολουθούμενη από άνω και κάτω τελεία
  • σκοπός της δέσμευσης σε παρελθοντικό χρόνο- αν είναι δυνατόν, αρχίστε με λέξεις όπως: added, fixed, refactored, changed, removed
  • αν η δέσμευση σπάει την προς τα πίσω συμβατότητα, προσθέστε “BC break”
  • οποιαδήποτε σύνδεση με τον ανιχνευτή ζητημάτων, όπως (#123) ή [Closes #69]
  • μετά το θέμα, μπορεί να υπάρχει μία κενή γραμμή, ακολουθούμενη από μία πιο λεπτομερή περιγραφή, συμπεριλαμβανομένων, για παράδειγμα, συνδέσμων προς το φόρουμ

Περιγραφή αιτήματος μετακίνησης

Κατά τη δημιουργία ενός pull request, η διεπαφή του GitHub θα σας επιτρέψει να εισαγάγετε έναν τίτλο και μια περιγραφή. Δώστε έναν συνοπτικό τίτλο και συμπεριλάβετε όσο το δυνατόν περισσότερες πληροφορίες στην περιγραφή σχετικά με τους λόγους της αλλαγής σας.

Επίσης, προσδιορίστε στην επικεφαλίδα αν πρόκειται για νέο χαρακτηριστικό ή διόρθωση σφάλματος και αν μπορεί να προκαλέσει προβλήματα συμβατότητας προς τα πίσω (BC break). Αν υπάρχει σχετικό θέμα, παραπέμψτε σε αυτό, ώστε να κλείσει με την έγκριση του pull request.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->
  1. Τεκμηρίωση
  2. Γίνε Συνεργάτης στο Nette
  3. Συμβολή στον κώδικα