Οδηγίες χρήσης του Code Repository

O darklynx ετοίμασε τις παρακάτω αναλυτικές οδηγίες για όσους επιθυμούν να χρησιμοποιήσουν code repository μέσω SVN για να βελτιώσουν και να επεκτείνουν το κώδικα των παραδειγμάτων των tutorials. Τον ευχαριστώ ιδιαίτερα για αυτό και για την γενικότερη προσπάθεια που έχει καταβάλει στο στήσιμο του project αυτού.

Θέλω να επισημάνω ότι αν κάποιος αναγνώστης δεν επιθυμεί να εμπλακεί στην διαδικασία αυτή, μπορεί και πάλι να βρει σε zip το κώδικα του κάθε tutorial στην ιστοσελίδα του Code Repository.

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

Θυμίζω ότι για να ανεβάσετε το δικό σας κώδικα στο Repository, πρέπει να έχετε δημιουργήσει ένα λογαριασμό στο Google (gmail) και να μας στείλετε το google email μαζί με το όνομα σας μέσω της φόρμας επικοινωνίας του blog.

Επίσης καλό θα ήταν να ενημερώνετε το σχετικό post του Videogames Laboratory Forum με ότι αλλαγές και προσθήκες έχετε κάνει στο Code Repository. Με τον τρόπο αυτό θα μπορούν οι ενδιαφερόμενοι να πληροφορηθούν γρήγορα για την κίνηση στο Repository.

Ακολουθούν λοιπόν οι οδηγίες χρήσης του Code Repository μέσω SVN:

————————————————————————————————

To code repository του blog που γίνεται host στο Google Code αξιοποιεί το SVN Version Control System για εύκολη και διακριτή παρουσίαση τόσο της εξέλιξης του κώδικα κατά την εξέλιξη ενός μαθήματος, όσο και των προσθηκών από τους αναγνώστες που εμπλουτίζουν με τις ιδέες τους το περιεχόμενο του μαθήματος.

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

Το SVN είναι ένας πολύ ισχυρός τρόπος να δουλεύουν πολλοί χρήστες πάνω στα ίδια αρχεία και φακέλους. Ο κάθε χρήστης μπορεί να έχει μια εκδοχή του κάθε αρχείου πάνω στο οποίο δουλεύει και να στέλνει τις αλλαγές που κάνει στο repository (commit) ή να λαμβάνει τις αλλαγές που έχουν κάνει άλλοι (update). Κάθε αλλαγή αποθηκεύεται ως νέο revision, το οποίο περιέχει το νέο directory tree και το όνομα και τα σχόλια του συντάκτη.

Για να τα κάνετε όλα αυτά είναι απαραίτητη η ύπαρξη ενός SVN Client στον υπολογιστή σας. Αν δεν χρησιμοποιείτε ήδη έναν τότε συστήνεται να κατεβάσετε και να εγκαταστήσετε τον πολύ καλό TortoiseSVN . Μετά το απαραίτητο restart ώστε να εφαρμοστούν οι αλλαγές στο Windows shell είμαστε έτοιμοι να τον χρησιμοποιήσουμε (αν έχετε όρεξη κοιτάξτε το documentation του Tortoise SVN που είναι πολύ καλό και κατατοπιστικό):

1) Πρώτα από όλα πρέπει να φτιάξουμε ένα σημείο στο οποίο θα στεγάσουμε την τοπική εκδοχή του project (τα λεγόμενα working copies). Φτιάξτε λοιπόν ένα νέο φάκελο στον υπολογιστή σας και δώστε του ένα όνομα  (έστω VideoGamesLab). Κάντε τώρα δεξί κλικ  στο φάκελο και παρατηρήστε ότι προστέθηκαν νέες επιλογές στο right-click menu. Αυτή που μας ενδιαφέρει για αρχή είναι η SVN Checkout… η οποία θα κατεβάσει την πρόσφατη εκδοχή του κώδικα των μαθημάτων. Το στοιχείο που μας ενδιαφέρει στο dialog που εμφανίζεται είναι το url που θα βάλουμε. Έχετε δύο επιλογές ανάλογα με το αν είστε εγγεγραμμένοι στο repository ή όχι:
α) Αν είστε ανώνυμοι χρήστες μπορείτε να κατεβάσετε μια readonly (δηλαδή δεν μπορείτε να αλλάξετε τον κώδικα στο repository αλλά είστε ελεύθεροι να τον χρησιμοποιήσετε στις εφαρμογές σας όπως θέλετε) εκδοχή βάζοντας ως url  http://videogameslab.googlecode.com/svn/trunk/.
β) Αν είστε εγγεγραμμένοι τότε το πρώτο βήμα είναι να μάθετε τα στοιχεία σας.Κάντε λοιπόν sign in στο Google account σας, μπείτε στο Profile σας πάνω δεξιά και σημειώστε τα εξής: i) το user id σας ii) από το tab Settings το Googlecode.com password. Επιστρέφουμε λοιπόν στο dialog του SVN Checkout και βάζουμε ως url το
https://videogameslab.googlecode.com/svn/trunk/. Όταν σας ζητηθεί id και password βάλτε αυτά που μόλις σημειώσατε και αν επιθυμείτε αποθηκεύστε το authentication σας, ώστε να μην χρειάζεται να ξανατυπώνεται τα στοιχεία σας κάθε φορά που κάνετε κάποια ενέργεια.

Σημειωτέον ότι μόλις εξοικειωθείτε με την διαδικασία θα μάθετε εύκολα να κατεβάζετε μέρος μόνο ενός project (π.χ  https://videogameslab.googlecode.com/svn/trunk/XNA Lessons) ή τον κώδικα των αναγνωστών (https://videogameslab.googlecode.com/svn/branches) απλά αλλάζοντας το url κάθε φορά. Στη σελίδα του project στο tab source επιλέξτε browse για να εξοικειωθείτε σταδιακά με το πως είναι οργανωμένα τα αρχεία.

Κρατήστε το φάκελο για ευκολία. Αν τον σβήσετε τότε πρέπει να επαναλάβετε τα παραπάνω.

2) Καθώς τα μαθήματα θα προχωράνε ο κώδικας θα εξελίσσεται, πρέπει λοιπόν η τοπική σας εκδοχή να είναι ενημερωμένη. Ανά τακτά διαστήματα λοιπόν αυτό που πρέπει να κάνετε είναι να κάνετε δεξί κλικ στον φάκελο που φυλάξατε (τον VideoGamesLab δηλαδή) και να επιλέγετε TortoiseSVN->SVN Update. Πατήστε OK και αν σας ζητηθεί βάλτε το id και το password σας.

3) Καθώς διαβάζετε τον κώδικα των μαθημάτων είναι πολύ πιθανό να σας έρθει μια καλή ιδέα που να τον βελτιώνει, ή να προσθέτει καινούργια χαρακτηριστικά. Αλλά πως θα τα ανεβάσετε στο repository σε ένα διακριτό σημείο δίχως να μπερδεύεται με τον κώδικα των μαθημάτων ή με προσθήκες άλλων χρηστών; Η λύση είναι να κάνετε Commit τις αλλαγές σας σε ένα νέο παρακλάδι (branch) του project. Μπορείτε λοιπόν είτε να κάνετε τροποποιήσεις απευθείας στον φάκελο όπως επιθυμείτε είτε καλύτερα ακολουθώντας το βήμα 1 να φτιάξετε ένα νέο φάκελο (όχι μέσα στο VideoGamesLab) που να περιέχει το project και να δουλεύετε ξεχωριστά σε αυτόν. Θυμηθείτε όμως να κάνετε ένα Update πριν ξεκινήσετε ώστε η δουλειά σας να είναι στο τελευταίο μάθημα (αν αυτό επιθυμείτε φυσικά).Οι αλλαγές σε ήδη υπάρχοντα αρχεία ανιχνεύονται αυτόματα δίχως άλλες ενέργειες από μέρους σας. Αν όμως χρειαστεί να προσθέσετε αρχεία ή φακέλους κάντε δεξί κλικ πάνω τους και επιλέξτε TortoiseSVN->Add… και επιλέξτε τα νέα στοιχεία. Καλό είναι σε αυτό το σημείο να εξοικειωθείτε με τα εικονίδια που το πρόγραμμα προσθέτει στα αρχεία, ώστε να καταλάβετε τις αλλαγές που έχουν συμβεί ή θα συμβούν.

Όταν είστε λοιπόν έτοιμοι με τις αλλαγές σας είναι η ώρα για να φτιάξετε το καινούριο branch. Επειδή πιθανότατα κάνατε αλλαγές στον κώδικα ενός μόνο μαθήματος επιλέξτε μόνο το μάθημα που ασχοληθήκατε (π.χ τον φάκελο Pong στα XNA Lessons). Κάντε δεξί κλικ και επιλέξτε TortoiseSVN->Branch/Tag… Στο πεδίο To url θα πρέπει να πληκτρολογήσετε https://videogameslab.googlecode.com/svn/branches/MyBranchName, όπου mybranchname το όνομα του νέου σας branch. Μια καλή ιδέα είναι να βάζετε το user name σας ως branch name.Βάλτε επίσης στο textbox που δέχεται τα comments μια μικρή περιγραφή του τι αλλαγές κάνατε  (είπαμε μικρή ). Στο Create copy in the repository from: επιλέξτε Working Copy ώστε να αντιγραφούν οι δικές σας αλλαγές στο branch που θα δημιουργηθεί. Τέλος αν ακολουθήσατε τη συμβουλή μου και φτιάξατε νέο φάκελο με το project πιθανόν να επιθυμείτε αυτός ο φάκελος να αλλάξει και να επικοινωνεί πλεόν με το branch αντί για το trunk. Αν ναι επιλέξτε Switch working copy to new branch/tag. Αν δεν το επιλέξετε ο φάκελος δεν θα επηρεαστεί οπότε μην ανησυχείτε. Πατήστε OK και αν σας ζητηθεί βάλτε το id και password.

4) Πως θα χειριστείτε όμως το νέο branch στο μέλλον; Έχετε τις εξής επιλογές:
i) Θέλετε ένα νέο φάκελο στον υπολογιστή σας με τα περιεχόμενα του branch; Δουλέψτε με την SVN Checkout… βάζοντας ως URL αυτό του branch.
ii) Θέλετε να κάνετε update τον φάκελό σας που περιέχει μια παλιά έκδοση ενός branch ώστε να συμπεριληφθούν οι αλλαγές άλλων χρηστών (παρόλο που αποθαρρύνονται οι χρήστες να “πειράζουν” άλλα branches); Εκτελέστε μια SVN Update εντολή με το url του branch.
iii) Θέλετε να στείλετε τις αλλαγές σας στο branch σας; Κάντε δεξί κλικ και επιλέξτε SVN Commit…Αν δεν βλέπετε την επιλογή είναι πιθανό ότι ο φάκελος δεν είχε πριν συσχετιστεί με το branch είτε με το Branch/Tag… είτε με το Checkout.

Savoire vivre του repository:
Το SVN σύστημα είναι φτιαγμένο ώστε να φαίνεται εύκολα ποιος έκανε αλλαγές και που. Όμως για να γλυτώσουμε τους υπόλοιπους από το να χρειάζεται να κάνουν διαρκείς ελέγχους παρακαλείστε να ακολουθείτε τις εξής κατευθυντήριες γραμμές:
α) Μην κάνετε Commit τις αλλαγές σας στο trunk.Ο συγγραφέας του blog θα καταλάβει τις αλλαγές αλλά εσείς πιθανόν όχι. Όταν χρειαστεί λοιπόν να δουλέψετε στις προηγούμενες αλλαγές σας ενδέχεται να τις κάνετε overwrite με τον κώδικα του συγγραφέα χωρίς καν να το καταλάβετε.Φτιάξτε ένα νέο branch και δουλέψτε εκεί δίχως ενόχληση.
β) Αν διαβάζοντας ένα branch ενός άλλου αναγνώστη σας έρθουν ιδέες για την βελτίωσή του μην τις κάνετε Commit στο δικό του branch. Είναι πιθανό να μπερδευτείτε και οι δυο σας ή ακόμα χειρότερα ένας νέος επισκέπτης του repository. Αντ’αυτού φτιάξτε ένα νέο branch και βάλτε ως σχόλιο ένα link στο branch το οποίο σας ενέπνευσε.

Πιθανόν νιώθετε ήδη έντονο πονοκέφαλο παρότι καλύψαμε μόνο τις πιο συνηθισμένες λειτουργίες . Θα διαπιστώσετε γρήγορα όμως πως τα παραπάνω θα σας σώσουν από μεγαλύτερους πονοκέφαλους στο εγγύς μέλλον. Φυσικά οι administrators θα αναλάβουν να σας ξελασπώσουν σε όποια προβλήματα αντιμετωπίσετε. Καλό programming λοιπόν!