Γράφοντας Αναφορές Προβλημάτων για το FreeBSD

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

Αυτό το κείμενο είναι μια προσπάθεια να περιγράψουμε πως μπορείτε να γράφετε καλές αναφορές προβλημάτων. Τι είναι, θα αναρωτιέστε, μια καλή αναφορά προβλήματος; Λοιπόν, για να είμαστε ακριβείς, μια καλή αναφορά προβλήματος είναι αυτή που μπορεί να αναλυθεί και να τη χειριστεί κάποιος γρήγορα, με αποτέλεσμα την ικανοποίηση τόσο του αποστολέα όσο και του προγραμματιστή που την ανέλαβε.

Το κυριότερο μέρος αυτού του άρθρου αναφέρεται στις αναφορές προβλημάτων του FreeBSD. Τα πιο πολλά από όσα θα πούμε εδώ ισχύουν όμως και γενικότερα, για πολλά άλλα πράγματα.

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

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

Τότε λοιπόν, πώς μπορείτε να αποφασίσετε αν κάτι είναι πρόβλημα ή όχι; Ένας απλός κανόνας είναι ότι το πρόβλημά σας δεν είναι bug αν μπορεί να εκφραστεί σαν ερώτηση (συνήθως της μορφής "Πώς κάνω το Χ;" ή "Πού μπορώ να βρω το Ψ;"). Δεν είναι πάντα τόσο άσπρο-μαύρο τα πράγματα βέβαια, αλλά ο κανόνας της ερώτησης καλύπτει την μεγαλύτερη πλειοψηφία των περιπτώσεων. Αν αυτό που ψάχνετε είναι κάποια απάντηση, ίσως είναι καλύτερα να στείλετε την ερώτησή σας στην ηλεκτρονική λίστα γενικών ερωτήσεων του FreeBSD.

Κάποιες περιπτώσεις που πιθανόν να είναι καλή ιδέα να στείλετε μια αναφορά προβλήματος για κάτι που δεν είναι bug, είναι:

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

Για να αποφασίσετε σε ποιά κατηγορία προβλημάτων ανήκει η αναφορά σας, πρέπει να έχετε κατά νου τα διάφορα μέρη του λογισμικού από το οποίο αποτελείται το FreeBSD:

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

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

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

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

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

Αν χρησιμοποιείτε το πρόγραμμα send-pr(1), σιγουρευτείτε ότι η μεταβλητή περιβάλλοντος VISUAL (ή η μεταβλητή περιβάλλοντος EDITOR αν δεν είναι ορισμένη η VISUAL) έχει κάποια λογική τιμή.

Ελέγξτε επίσης ότι η αποστολή ηλεκτρονικής αλληλογραφίας λειτουργεί σωστά. Το πρόγραμμα send-pr(1) χρησιμοποιεί μηνύματα ηλεκτρονικής αλληλογραφίας για την αποστολή και την παρακολούθηση των αναφορών προβλημάτων. Αν δε μπορείτε να στείλετε μηνύματα ηλεκτρονικής αλληλογραφίας από το μηχάνημα στο οποίο χρησιμοποιείτε το πρόγραμμα send-pr(1), το μήνυμά σας και η αναφορά δε θα φτάσει ποτέ στη βάση αναφορών προβλημάτων του FreeBSD. Για λεπτομέρειες σχετικά με τη ρύθμιση της ηλεκτρονικής αλληλογραφίας στο FreeBSD δείτε το κεφάλαιο περί "Ηλεκτρονικής Αλληλογραφίας" στο Εγχειρίδιο του FreeBSD στη διεύθυνση Electronic Mail.

Σιγουρευτείτε ότι το πρόγραμμα αλληλογραφίας το οποίο χρησιμοποιείτε δεν θα αλλάξει ούτε το περιεχόμενο ούτε τη μορφή του κειμένου που στέλνετε πριν αυτό φτάσει στο σύστημα GNATS του FreeBSD. Πιο συγκεκριμένα, αν το πρόγραμμα αλληλογραφίας σας αποφασίζει αυτόματα για το μήκος κάθε γραμμής κειμένου, αλλάζει τους χαρακτήρες στηλοθέτη με κενά ή επεμβαίνει στους χαρακτήρες αλλαγής γραμμής, τότε κάθε patch που στέλνετε μπορεί να είναι εντελώς άχρηστο. Από την άλλη, στα πεδία της αναφοράς προβλήματος τα οποία περιέχουν απλό κείμενο είναι πιο βολικό να έχει περίπου 70 στήλες η κάθε γραμμή. Έτσι διαβάζεται πιο εύκολα το κείμενο της αναφοράς μέσα από το web interface μας.

Παρόμοια προσοχή χρειάζεται και όταν, αντί για το εργαλείο send-pr(1), χρησιμοποιείτε τη φόρμα υποβολής αναφορών που έχει η ιστοσελίδα μας. Η αντιγραφή και επικόλληση κειμένου μπορεί να επηρεάσει τη μορφοποίηση του κειμένου. Σε μερικές περιπτώσεις μπορεί να χρειαστεί ακόμα και το εργαλείο uuencode(1) για να είστε σίγουροι ότι ένα patch φτάνει ως εμάς χωρίς αλλαγές.

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

Το πρόγραμμα send-pr(1) έχει την δυνατότητα να επισυνάψει αρχεία σε μια αναφορά προβλήματος. Μπορείτε να επισυνάψετε όσα αρχεία θέλετε, αρκεί το καθένα να έχει μοναδικό βασικό όνομα (το όνομα του αρχείου χωρίς την διαδρομή). Απλά χρησιμοποιήστε την παράμετρο -a στην γραμμή εντολών για να καταδείξετε τα ονόματα των αρχείων που θέλετε να επισυνάψετε:

Δεν χρειάζεται να ανησυχείτε για τα αρχεία που δεν είναι κείμενο. Θα κωδικοποιηθούν κατάλληλα για να μην τα αλλάξει το πρόγραμμα αποστολής ηλεκτρονικής αλληλογραφίας που χρησιμοποιείτε.

Αν μαζί με την αναφορά στείλετε και κάποιο patch, φροντίστε να χρησιμοποιήσετε την επιλογή -c ή την -u στην εντολή diff(1) για να δημιουργήσετε ένα context ή unified αρχείο διαφορών, και μην ξεχάσετε να σημειώσετε τις ακριβείς εκδόσεις των αρχείων που αλλάξατε έτσι ώστε οι προγραμματιστές που θα διαβάσουν την αναφορά σας να μπορούν να κάνουν τις ίδιες αλλαγές εύκολα. Για τα προβλήματα που αφορούν τον πυρήνα ή τα εργαλεία του βασικού συστήματος είναι προτιμότερο το patch σας να βασίζεται στο FreeBSD-CURRENT (το HEAD branch του CVS) αφού όλες οι αλλαγές πρέπει πρώτα να γίνονται σε αυτό το branch για να δοκιμαστούν. Αφού περάσει κάποιος καιρός κι οι αλλαγές δοκιμαστούν αρκετά μόνο τότε ενσωματώνονται/μεταφέρονται οι αλλαγές στο FreeBSD-STABLE branch.

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

Μη στέλνετε τα patches σας ως επισυνάψεις με την κωδικοποίηση Content-Transfer-Encoding: quoted-printable. Αυτή η κωδικοποίηση αλλάζει κάποιους χαρακτήρες με αποτέλεσμα να είναι άχρηστο ολόκληρο το patch.

Γενικά, πάντως, δεν τρέχει τίποτα αν ενσωματώσετε κάποιο μικρό patch στην αναφορά σας-ειδικά αν είναι φανερό πως διορθώνει το πρόβλημα που περιγράφεται στην αναφορά. Τα πιο μεγάλα patches, κυρίως κώδικας που μπορεί να απαιτεί λεπτομερή ανάλυση και δοκιμές πριν γίνει commit, είναι καλύτερα να τα ανεβάζετε σε κάποιο web ή ftp server και να περιλαμβάνετε στην αναφορά σας το URL για να τα βρίσκει ο αναγνώστης της αναφοράς αντί να ενσωματώνετε το ίδιο το patch. Πολλές φορές τα patches καταστρέφονται όταν είναι μέρος ενός email, ειδικά όταν περνούν από το πρόγραμμα GNATS, κι όσο πιο μεγάλο είναι το patch τόσο πιο δύσκολο θα είναι για όποιον ενδιαφέρεται να το διορθώσει για να το δοκιμάσει. Ένα άλλο καλό που έχει η διανομή ενός patch μέσω web ή ftp είναι ότι μπορείτε να αλλάξετε το patch χωρίς να χρειάζεται να το ξαναστείλετε όλο σαν μέρος μιας απάντησης στην αρχική αναφορά. Τα μεγάλα patches αυξάνουν μόνιμα το μέγεθος της βάσης αναφορών, αφού ακόμη κι όταν διορθωθεί ένα πρόβλημα και κλείσει η αντίστοιχη αναφορά προβλήματος δε σβήνεται τίποτα από τη βάση αναφορών, αλλά απλά σημειώνεται ως closed.

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

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

Στην κορυφή της φόρμας, κάτω από τις γραμμές που αρχίζουν με SEND-PR: υπάρχουν οι επικεφαλίδες ενός γράμματος. Συνήθως δεν χρειάζετε να κάνετε κάποια αλλαγή σε αυτές, εκτός κι αν στέλνετε την αναφορά από κάποιο μηχάνημα το οποίο μπορεί να στείλει email αλλά δεν μπορεί να λάβει, που θα πρέπει να προσέξετε οι γραμμές From: και Reply-To: να έχουν την πραγματική σας email διεύθυνση. Μπορείτε φυσικα να στείλετε στον εαυτό σας ή κάποιον άλλο ένα αντίγραφο της αναφοράς προβλήματος προσθέτοντας τις κατάλληλες Cc: γραμμές.

Μετά θα δείτε μια σειρά από πεδία μιας γραμμής:

Τέλος, υπάρχει μια σειρά από πεδία με περισσότερες από μια γραμμές το καθένα:

Όταν τελειώσετε με το γράψιμο, την συμπλήρωση της φόρμας, και σώσετε το κείμενο της αναφοράς σε ένα αρχείο, το πρόγραμμα send-pr(1) θα σας δείξει μια προτροπή s)end, e)dit or a)bort?. Μπορείτε τότε να πατήσετε s για να συνεχίσετε και να σταλεί η αναφορά, e για να ξεκινήσετε πάλι τον κειμενογράφο σας, ή a για να εγκαταλείψετε. Αν επιλέξετε το τελευταίο, το κείμενο της αναφοράς σας θα παραμείνει στο δίσκο (η send-pr(1) θα γράψει το όνομα του αρχείου πριν τερματίσει), οπότε μπορείτε να το επεξεργαστείτε με την ησυχία σας αργότερα ή να το μεταφέρετε σε κάποιο σύστημα με καλύτερη σύνδεση δικτύου, πριν να το στείλετε με την επιλογή -F της send-pr(1):

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

Μόλις η αναφορά σας καταχωρηθεί, θα πάρετε μια απάντηση μέσω email που θα περιλαμβάνει τον αριθμό που έχει σχετιστεί με την αναφορά σας και μια διεύθυνση URL όπου μπορείτε να διαβάσετε την αναφορά και την κατάστασή της. Με λίγη τύχη, κάποιος θα ενδιαφερθεί για την αναφορά σας και θα προσπαθήσει να λύσει το πρόβλημα ή τουλάχιστον, ανάλογα με την περίπτωση, να σας εξηγήσει γιατί δεν είναι πρόβλημα. Θα ειδοποιήστε αυτόματα για κάθε αλλαγή στην κατάσταση της αναφοράς, και θα παίρνετε αντίγραφα μέσω αλληλογραφίας με οποιαδήποτε σχόλια ή patches στέλνει κάποιος σαν απάντηση στην αναφορά σας.

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

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

Παρακάτω θα βρείτε κάποιες πηγές που είναι σχετικές με το θέμα των αναφορών προβλήματος. Δεν είναι μια πλήρης ή επαρκής λίστα, φυσικά.