Πώς να συνεισφέρετε στον κώδικα

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

Διαδικασία

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

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

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

Υλοποίηση των δικών σας αλλαγών

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

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

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

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

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

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

Ενσωμάτωση σχολίων

Τα commits σας θα είναι πλέον ορατά και σε άλλους. Είναι σύνηθες να λαμβάνετε σχόλια με παρατηρήσεις:

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

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

Τεκμηρίωση

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

Νέος Κλάδος

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

git checkout -b new_branch_name v3.2.1

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

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

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

Περιγραφή του Commit

Στο Nette, τα θέματα των commits έχουν τη μορφή: Presenter: fixed AJAX detection [Closes #69]

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

Περιγραφή του Pull Request

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

Θα εμφανιστεί επίσης μια επικεφαλίδα, όπου θα καθορίσετε αν πρόκειται για νέα λειτουργία ή διόρθωση σφάλματος και αν μπορεί να προκύψει παραβίαση της προς τα πίσω συμβατότητας (BC break). Αν υπάρχει σχετικό πρόβλημα (issue), αναφερθείτε σε αυτό, ώστε να κλείσει μετά την έγκριση του 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. Πώς να συνεισφέρετε στον κώδικα