# AGENTS.md ## Επισκόπηση Έργου Αυτό είναι ένα αποθετήριο εκπαιδευτικού προγράμματος για τη διδασκαλία των βασικών αρχών ανάπτυξης ιστοσελίδων σε αρχάριους. Το πρόγραμμα είναι ένα ολοκληρωμένο 12-εβδομαδιαίο μάθημα που έχει αναπτυχθεί από τους Microsoft Cloud Advocates, περιλαμβάνοντας 24 πρακτικά μαθήματα που καλύπτουν JavaScript, CSS και HTML. ### Βασικά Στοιχεία - **Εκπαιδευτικό Περιεχόμενο**: 24 δομημένα μαθήματα οργανωμένα σε έργα - **Πρακτικά Έργα**: Terrarium, Παιχνίδι Πληκτρολόγησης, Επέκταση Περιηγητή, Παιχνίδι Διαστήματος, Εφαρμογή Τραπεζικής, Επεξεργαστής Κώδικα και Βοηθός Συνομιλίας AI - **Διαδραστικά Κουίζ**: 48 κουίζ με 3 ερωτήσεις το καθένα (πριν/μετά το μάθημα) - **Υποστήριξη Πολλών Γλωσσών**: Αυτόματες μεταφράσεις για 50+ γλώσσες μέσω GitHub Actions - **Τεχνολογίες**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (για έργα AI) ### Αρχιτεκτονική - Εκπαιδευτικό αποθετήριο με δομή βασισμένη σε μαθήματα - Κάθε φάκελος μαθήματος περιέχει README, παραδείγματα κώδικα και λύσεις - Αυτόνομα έργα σε ξεχωριστούς φακέλους (quiz-app, διάφορα έργα μαθημάτων) - Σύστημα μετάφρασης μέσω GitHub Actions (co-op-translator) - Τεκμηρίωση που εξυπηρετείται μέσω Docsify και διαθέσιμη ως PDF ## Εντολές Ρύθμισης Αυτό το αποθετήριο προορίζεται κυρίως για κατανάλωση εκπαιδευτικού περιεχομένου. Για εργασία με συγκεκριμένα έργα: ### Ρύθμιση Κύριου Αποθετηρίου ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` ### Ρύθμιση Εφαρμογής Κουίζ (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # Start development server npm run build # Build for production npm run lint # Run ESLint ``` ### API Τραπεζικού Έργου (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # Start API server npm run lint # Run ESLint npm run format # Format with Prettier ``` ### Έργα Επέκτασης Περιηγητή ```bash cd 5-browser-extension/solution npm install # Follow browser-specific extension loading instructions ``` ### Έργα Παιχνιδιού Διαστήματος ```bash cd 6-space-game/solution npm install # Open index.html in browser or use Live Server ``` ### Έργο Συνομιλίας (Python Backend) ```bash cd 9-chat-project/solution/backend/python pip install openai # Set GITHUB_TOKEN environment variable python api.py ``` ## Ροή Εργασίας Ανάπτυξης ### Για Συνεισφέροντες Περιεχομένου 1. **Κάντε fork το αποθετήριο** στον λογαριασμό σας στο GitHub 2. **Κλωνοποιήστε το fork σας** τοπικά 3. **Δημιουργήστε ένα νέο branch** για τις αλλαγές σας 4. Κάντε αλλαγές στο περιεχόμενο των μαθημάτων ή στα παραδείγματα κώδικα 5. Δοκιμάστε τις αλλαγές κώδικα στους αντίστοιχους φακέλους έργων 6. Υποβάλετε pull requests ακολουθώντας τις οδηγίες συνεισφοράς ### Για Μαθητές 1. Κάντε fork ή κλωνοποιήστε το αποθετήριο 2. Πλοηγηθείτε στους φακέλους μαθημάτων με τη σειρά 3. Διαβάστε τα αρχεία README για κάθε μάθημα 4. Ολοκληρώστε τα κουίζ πριν το μάθημα στο https://ff-quizzes.netlify.app/web/ 5. Εργαστείτε στα παραδείγματα κώδικα στους φακέλους μαθημάτων 6. Ολοκληρώστε τις εργασίες και τις προκλήσεις 7. Κάντε τα κουίζ μετά το μάθημα ### Ζωντανή Ανάπτυξη - **Τεκμηρίωση**: Εκτελέστε `docsify serve` στη ρίζα (port 3000) - **Εφαρμογή Κουίζ**: Εκτελέστε `npm run dev` στον φάκελο quiz-app - **Έργα**: Χρησιμοποιήστε την επέκταση Live Server του VS Code για έργα HTML - **API Έργα**: Εκτελέστε `npm start` στους αντίστοιχους φακέλους API ## Οδηγίες Δοκιμών ### Δοκιμή Εφαρμογής Κουίζ ```bash cd quiz-app npm run lint # Check for code style issues npm run build # Verify build succeeds ``` ### Δοκιμή API Τραπεζικού Έργου ```bash cd 7-bank-project/api npm run lint # Check for code style issues node server.js # Verify server starts without errors ``` ### Γενική Προσέγγιση Δοκιμών - Αυτό είναι ένα εκπαιδευτικό αποθετήριο χωρίς ολοκληρωμένες αυτοματοποιημένες δοκιμές - Η χειροκίνητη δοκιμή επικεντρώνεται σε: - Εκτέλεση παραδειγμάτων κώδικα χωρίς σφάλματα - Σωστή λειτουργία συνδέσμων στην τεκμηρίωση - Επιτυχής ολοκλήρωση κατασκευών έργων - Συμμόρφωση παραδειγμάτων με βέλτιστες πρακτικές ### Έλεγχοι Πριν την Υποβολή - Εκτελέστε `npm run lint` στους φακέλους με package.json - Επαληθεύστε ότι οι σύνδεσμοι markdown είναι έγκυροι - Δοκιμάστε παραδείγματα κώδικα σε περιηγητή ή Node.js - Ελέγξτε ότι οι μεταφράσεις διατηρούν τη σωστή δομή ## Οδηγίες Στυλ Κώδικα ### JavaScript - Χρησιμοποιήστε σύγχρονη σύνταξη ES6+ - Ακολουθήστε τις τυπικές ρυθμίσεις ESLint που παρέχονται στα έργα - Χρησιμοποιήστε κατανοητά ονόματα μεταβλητών και συναρτήσεων για εκπαιδευτική σαφήνεια - Προσθέστε σχόλια που εξηγούν έννοιες για τους μαθητές - Μορφοποιήστε χρησιμοποιώντας Prettier όπου έχει ρυθμιστεί ### HTML/CSS - Χρησιμοποιήστε σημασιολογικά στοιχεία HTML5 - Εφαρμόστε αρχές σχεδιασμού για ανταπόκριση - Χρησιμοποιήστε σαφείς συμβάσεις ονοματοδοσίας κλάσεων - Προσθέστε σχόλια που εξηγούν τεχνικές CSS για τους μαθητές ### Python - Ακολουθήστε τις οδηγίες στυλ PEP 8 - Παρέχετε σαφή, εκπαιδευτικά παραδείγματα κώδικα - Χρησιμοποιήστε τύπους όπου είναι χρήσιμοι για μάθηση ### Τεκμηρίωση Markdown - Σαφής ιεραρχία επικεφαλίδων - Μπλοκ κώδικα με καθορισμό γλώσσας - Σύνδεσμοι σε πρόσθετους πόρους - Στιγμιότυπα οθόνης και εικόνες στους φακέλους `images/` - Εναλλακτικό κείμενο για εικόνες για προσβασιμότητα ### Οργάνωση Αρχείων - Μαθήματα αριθμημένα διαδοχικά (1-getting-started-lessons, 2-js-basics, κ.λπ.) - Κάθε έργο έχει φακέλους `solution/` και συχνά `start/` ή `your-work/` - Εικόνες αποθηκευμένες σε φακέλους `images/` συγκεκριμένων μαθημάτων - Μεταφράσεις στη δομή `translations/{language-code}/` ## Κατασκευή και Ανάπτυξη ### Ανάπτυξη Εφαρμογής Κουίζ (Azure Static Web Apps) Η εφαρμογή quiz-app είναι ρυθμισμένη για ανάπτυξη σε Azure Static Web Apps: ```bash cd quiz-app npm run build # Creates dist/ folder # Deploys via GitHub Actions workflow on push to main ``` Ρύθμιση Azure Static Web Apps: - **Τοποθεσία εφαρμογής**: `/quiz-app` - **Τοποθεσία εξόδου**: `dist` - **Ροή εργασίας**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### Δημιουργία PDF Τεκμηρίωσης ```bash npm install # Install docsify-to-pdf npm run convert # Generate PDF from docs ``` ### Τεκμηρίωση Docsify ```bash npm install -g docsify-cli # Install Docsify globally docsify serve # Serve on localhost:3000 ``` ### Κατασκευές Ειδικών Έργων Κάθε φάκελος έργου μπορεί να έχει τη δική του διαδικασία κατασκευής: - Έργα Vue: `npm run build` δημιουργεί παραγωγικά πακέτα - Στατικά έργα: Χωρίς βήμα κατασκευής, εξυπηρετήστε αρχεία απευθείας ## Οδηγίες Pull Request ### Μορφή Τίτλου Χρησιμοποιήστε σαφείς, περιγραφικούς τίτλους που υποδεικνύουν την περιοχή αλλαγής: - `[Quiz-app] Προσθήκη νέου κουίζ για το μάθημα X` - `[Lesson-3] Διόρθωση τυπογραφικού στο έργο terrarium` - `[Translation] Προσθήκη ισπανικής μετάφρασης για το μάθημα 5` - `[Docs] Ενημέρωση οδηγιών ρύθμισης` ### Απαιτούμενοι Έλεγχοι Πριν την υποβολή PR: 1. **Ποιότητα Κώδικα**: - Εκτελέστε `npm run lint` στους επηρεαζόμενους φακέλους έργων - Διορθώστε όλα τα σφάλματα και τις προειδοποιήσεις linting 2. **Επαλήθευση Κατασκευής**: - Εκτελέστε `npm run build` αν είναι απαραίτητο - Βεβαιωθείτε ότι δεν υπάρχουν σφάλματα κατασκευής 3. **Επαλήθευση Συνδέσμων**: - Δοκιμάστε όλους τους συνδέσμους markdown - Επαληθεύστε ότι οι αναφορές εικόνων λειτουργούν 4. **Ανασκόπηση Περιεχομένου**: - Ελέγξτε για ορθογραφικά και γραμματικά λάθη - Βεβαιωθείτε ότι τα παραδείγματα κώδικα είναι σωστά και εκπαιδευτικά - Επαληθεύστε ότι οι μεταφράσεις διατηρούν το αρχικό νόημα ### Απαιτήσεις Συνεισφοράς - Συμφωνήστε με το Microsoft CLA (αυτοματοποιημένος έλεγχος στο πρώτο PR) - Ακολουθήστε τον [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) - Δείτε το [CONTRIBUTING.md](./CONTRIBUTING.md) για λεπτομερείς οδηγίες - Αναφέρετε αριθμούς ζητημάτων στην περιγραφή PR αν είναι απαραίτητο ### Διαδικασία Ανασκόπησης - Τα PR ανασκοπούνται από συντηρητές και την κοινότητα - Δίνεται προτεραιότητα στη εκπαιδευτική σαφήνεια - Τα παραδείγματα κώδικα πρέπει να ακολουθούν τις τρέχουσες βέλτιστες πρακτικές - Οι μεταφράσεις ανασκοπούνται για ακρίβεια και πολιτισμική καταλληλότητα ## Σύστημα Μετάφρασης ### Αυτόματη Μετάφραση - Χρησιμοποιεί GitHub Actions με ροή εργασίας co-op-translator - Μεταφράζει αυτόματα σε 50+ γλώσσες - Αρχεία πηγής στους κύριους φακέλους - Μεταφρασμένα αρχεία στη δομή `translations/{language-code}/` ### Προσθήκη Βελτιώσεων Χειροκίνητης Μετάφρασης 1. Εντοπίστε το αρχείο στο `translations/{language-code}/` 2. Κάντε βελτιώσεις διατηρώντας τη δομή 3. Βεβαιωθείτε ότι τα παραδείγματα κώδικα παραμένουν λειτουργικά 4. Δοκιμάστε οποιοδήποτε τοπικό περιεχόμενο κουίζ ### Μεταδεδομένα Μετάφρασης Τα μεταφρασμένα αρχεία περιλαμβάνουν κεφαλίδα μεταδεδομένων: ```markdown ``` ## Εντοπισμός Σφαλμάτων και Αντιμετώπιση Προβλημάτων ### Συνηθισμένα Προβλήματα **Η εφαρμογή κουίζ δεν ξεκινά**: - Ελέγξτε την έκδοση Node.js (συνιστάται v14+) - Διαγράψτε `node_modules` και `package-lock.json`, εκτελέστε ξανά `npm install` - Ελέγξτε για συγκρούσεις θύρας (προεπιλογή: Vite χρησιμοποιεί θύρα 5173) **Ο διακομιστής API δεν ξεκινά**: - Βεβαιωθείτε ότι η έκδοση Node.js πληροί το ελάχιστο (node >=10) - Ελέγξτε αν η θύρα είναι ήδη σε χρήση - Βεβαιωθείτε ότι όλες οι εξαρτήσεις έχουν εγκατασταθεί με `npm install` **Η επέκταση περιηγητή δεν φορτώνει**: - Επαληθεύστε ότι το manifest.json είναι σωστά μορφοποιημένο - Ελέγξτε την κονσόλα του περιηγητή για σφάλματα - Ακολουθήστε τις οδηγίες εγκατάστασης επέκτασης για συγκεκριμένο περιηγητή **Προβλήματα έργου συνομιλίας Python**: - Βεβαιωθείτε ότι το πακέτο OpenAI είναι εγκατεστημένο: `pip install openai` - Επαληθεύστε ότι η μεταβλητή περιβάλλοντος GITHUB_TOKEN έχει οριστεί - Ελέγξτε τα δικαιώματα πρόσβασης στα GitHub Models **Το Docsify δεν εξυπηρετεί την τεκμηρίωση**: - Εγκαταστήστε το docsify-cli παγκοσμίως: `npm install -g docsify-cli` - Εκτελέστε από τον ριζικό φάκελο του αποθετηρίου - Ελέγξτε ότι υπάρχει το `docs/_sidebar.md` ### Συμβουλές Περιβάλλοντος Ανάπτυξης - Χρησιμοποιήστε το VS Code με την επέκταση Live Server για έργα HTML - Εγκαταστήστε τις επεκτάσεις ESLint και Prettier για συνεπή μορφοποίηση - Χρησιμοποιήστε τα DevTools του περιηγητή για αποσφαλμάτωση JavaScript - Για έργα Vue, εγκαταστήστε την επέκταση Vue DevTools στον περιηγητή ### Σκέψεις Απόδοσης - Ο μεγάλος αριθμός μεταφρασμένων αρχείων (50+ γλώσσες) σημαίνει ότι οι πλήρεις κλωνοποιήσεις είναι μεγάλες - Χρησιμοποιήστε shallow clone αν εργάζεστε μόνο στο περιεχόμενο: `git clone --depth 1` - Εξαιρέστε τις μεταφράσεις από τις αναζητήσεις όταν εργάζεστε στο αγγλικό περιεχόμενο - Οι διαδικασίες κατασκευής μπορεί να είναι αργές στην πρώτη εκτέλεση (npm install, Vite build) ## Σκέψεις Ασφαλείας ### Μεταβλητές Περιβάλλοντος - Τα κλειδιά API δεν πρέπει ποτέ να δεσμεύονται στο αποθετήριο - Χρησιμοποιήστε αρχεία `.env` (ήδη στο `.gitignore`) - Τεκμηριώστε τις απαιτούμενες μεταβλητές περιβάλλοντος στα README των έργων ### Έργα Python - Χρησιμοποιήστε εικονικά περιβάλλοντα: `python -m venv venv` - Διατηρήστε τις εξαρτήσεις ενημερωμένες - Τα GitHub tokens πρέπει να έχουν τα ελάχιστα απαιτούμενα δικαιώματα ### Πρόσβαση στα GitHub Models - Απαιτούνται Personal Access Tokens (PAT) για τα GitHub Models - Τα tokens πρέπει να αποθηκεύονται ως μεταβλητές περιβάλλοντος - Ποτέ μην δεσμεύετε tokens ή διαπιστευτήρια ## Πρόσθετες Σημειώσεις ### Στόχος Κοινού - Απόλυτοι αρχάριοι στην ανάπτυξη ιστοσελίδων - Μαθητές και αυτοδίδακτοι - Εκπαιδευτικοί που χρησιμοποιούν το πρόγραμμα σε τάξεις - Το περιεχόμενο είναι σχεδιασμένο για προσβασιμότητα και σταδιακή ανάπτυξη δεξιοτήτων ### Εκπαιδευτική Φιλοσοφία - Προσέγγιση μάθησης βασισμένη σε έργα - Συχνές αξιολογήσεις γνώσεων (κουίζ) - Πρακτικές ασκήσεις κώδικα - Παραδείγματα εφαρμογών πραγματικού κόσμου - Εστίαση στα θεμελιώδη πριν από τα frameworks ### Συντήρηση Αποθετηρίου - Ενεργή κοινότητα μαθητών και συνεισφερόντων - Τακτικές ενημερώσεις εξαρτήσεων και περιεχομένου - Ζητήματα και συζητήσεις παρακολουθούνται από συντηρητές - Ενημερώσεις μεταφράσεων αυτοματοποιημένες μέσω GitHub Actions ### Σχετικοί Πόροι - [Microsoft Learn modules](https://docs.microsoft.com/learn/) - [Πόροι Student Hub](https://docs.microsoft.com/learn/student-hub/) - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub --- **Αποποίηση ευθύνης**: Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που καταβάλλουμε προσπάθειες για ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτόματες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα θα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή εσφαλμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.