22 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Επισκόπηση Έργου

Αυτό είναι ένα εκπαιδευτικό αποθετήριο προγράμματος σπουδών για τη διδασκαλία των βασικών της ανάπτυξης ιστοσελίδων σε αρχάριους. Το πρόγραμμα σπουδών είναι ένα ολοκληρωμένο μάθημα 12 εβδομάδων που αναπτύχθηκε από τους Microsoft Cloud Advocates, με 24 πρακτικά μαθήματα που καλύπτουν JavaScript, CSS και HTML.

Κύρια Στοιχεία

Εκπαιδευτικό Περιεχόμενο: 24 δομημένα μαθήματα οργανωμένα σε μονάδες βασισμένες σε έργα
Πρακτικά Έργα: Terrarium, Παιχνίδι Πληκτρολόγησης, Επέκταση Περιηγητή, Παιχνίδι Διαστήματος, Τραπεζική Εφαρμογή, Κώδικας Επεξεργαστή και Βοηθός Συνομιλίας με Τεχνητή Νοημοσύνη
Διαδραστικά Κουίζ: 48 κουίζ με 3 ερωτήσεις το καθένα (αξιολογήσεις πριν/μετά το μάθημα)
Υποστήριξη Πολλαπλών Γλωσσών: Αυτόματες μεταφράσεις για πάνω από 50 γλώσσες μέσω GitHub Actions
Τεχνολογίες: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (για έργα ΤΝ)

Αρχιτεκτονική

Εκπαιδευτικό αποθετήριο με δομή βάσει μαθημάτων
Οφάκελοι κάθε μαθήματος περιέχουν README, παραδείγματα κώδικα και λύσεις
Αυτόνομα έργα σε ξεχωριστούς φακέλους (quiz-app, διάφορα έργα μαθημάτων)
Σύστημα μετάφρασης μέσω GitHub Actions (co-op-translator)
Τεκμηρίωση διατίθεται μέσω Docsify και ως PDF

Εντολές Ρύθμισης

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

Ρύθμιση Κύριου Αποθετηρίου

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Ρύθμιση Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Εκκίνηση διακομιστή ανάπτυξης
npm run build      # Δημιουργία για παραγωγή
npm run lint       # Εκτέλεση ESLint

API Τραπεζικού Έργου (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Εκκίνηση διακομιστή API
npm run lint       # Εκτέλεση ESLint
npm run format     # Μορφοποίηση με Prettier

Έργα Επέκτασης Περιηγητή

cd 5-browser-extension/solution
npm install
# Ακολουθήστε τις οδηγίες φόρτωσης επεκτάσεων που είναι ειδικές για τον περιηγητή

Έργα Παιχνιδιού Διαστήματος

cd 6-space-game/solution
npm install
# Ανοίξτε το index.html σε πρόγραμμα περιήγησης ή χρησιμοποιήστε Live Server

Έργο Συνομιλίας (Backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Ορισμός μεταβλητής περιβάλλοντος GITHUB_TOKEN
python api.py

Ροή Ανάπτυξης

Για Συνεισφέροντες Περιεχομένου

Δημιουργήστε fork του αποθετηρίου στον λογαριασμό σας στο GitHub
Κλωνοποιήστε το fork τοπικά
Δημιουργήστε νέο κλαδί για τις αλλαγές σας
Κάντε αλλαγές στο περιεχόμενο των μαθημάτων ή τα παραδείγματα κώδικα
Δοκιμάστε τις αλλαγές κώδικα στους αντίστοιχους φακέλους έργων
Υποβάλετε pull requests ακολουθώντας τις οδηγίες συνεισφοράς

Για Μαθητές

Κάντε fork ή κλωνοποιήστε το αποθετήριο
Πλοηγηθείτε διαδοχικά στους φακέλους των μαθημάτων
Διαβάστε τα αρχεία README κάθε μαθήματος
Ολοκληρώστε τα προ-μαθήματος κουίζ στο https://ff-quizzes.netlify.app/web/
Επεξεργαστείτε τα παραδείγματα κώδικα στους φακέλους μαθημάτων
Ολοκληρώστε εργασίες και προκλήσεις
Πραγματοποιήστε τα μετα-μαθήματος κουίζ

Ζωντανή Ανάπτυξη

Τεκμηρίωση: Εκτελέστε docsify serve από τη ρίζα (θύρα 3000)
Quiz App: Εκτελέστε npm run dev στον φάκελο quiz-app
Έργα: Χρησιμοποιήστε το Live Server extension του VS Code για έργα HTML
API Έργα: Εκτελέστε npm start στους αντίστοιχους φακέλους API

Οδηγίες Δοκιμών

Δοκιμές Quiz App

cd quiz-app
npm run lint       # Έλεγχος για θέματα στυλ κώδικα
npm run build      # Επαλήθευση επιτυχίας κατασκευής

Δοκιμές Bank API

cd 7-bank-project/api
npm run lint       # Έλεγχος για θέματα στυλ κώδικα
node server.js     # Επιβεβαίωση ότι ο διακομιστής ξεκινά χωρίς σφάλματα

Γενική Προσέγγιση Δοκιμών

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

Έλεγχοι Πριν την Υποβολή

Εκτελέστε npm run lint στους φακέλους με package.json
Επαληθεύστε ότι οι σύνδεσμοι markdown είναι έγκυροι
Δοκιμάστε παραδείγματα κώδικα στον περιηγητή ή Node.js
Ελέγξτε ότι οι μεταφράσεις διατηρούν τη σωστή δομή

Οδηγίες Στυλ Κώδικα

JavaScript

Χρησιμοποιήστε τον σύγχρονο σύνταξη ES6+
Ακολουθήστε τις τυπικές ρυθμίσεις ESLint που παρέχονται στα έργα
Χρησιμοποιήστε ουσιαστικά ονόματα μεταβλητών και συναρτήσεων για εκπαιδευτική σαφήνεια
Προσθέστε σχόλια που εξηγούν έννοιες για τους μαθητές
Μορφοποιήστε με Prettier όπου είναι ρυθμισμένο

HTML/CSS

Σημαντικά στοιχεία HTML5
Αρχές σχεδιασμού προσαρμοστικής εμφάνισης (responsive)
Καθαρούς κανόνες ονοματολογίας κλάσεων
Σχόλια που εξηγούν τεχνικές CSS για μαθητές

Python

Χρήση οδηγιών στυλ PEP 8
Καθαρά, εκπαιδευτικά παραδείγματα κώδικα
Χρήση δηλώσεων τύπων όπου βοηθούν στην εκμάθηση

Τεκμηρίωση σε Markdown

Σαφή ιεραρχία επικεφαλίδων
Μπλοκ κώδικα με καθορισμένη γλώσσα
Σύνδεσμοι για επιπλέον πόρους
Στιγμιότυπα και εικόνες στους φακέλους images/
Εναλλακτικό κείμενο (alt text) για τις εικόνες για προσβασιμότητα

Οργάνωση Αρχείων

Μαθήματα με αριθμημένη ακολουθία (1-getting-started-lessons, 2-js-basics κ.ά.)
Κάθε έργο έχει φακέλους solution/ και συχνά start/ ή your-work/
Εικόνες φυλαγμένες σε φακέλους images/ κάθε μαθήματος
Μεταφράσεις σε δομή translations/{language-code}/

Κατασκευή και Ανάπτυξη

Ανάπτυξη Quiz App (Azure Static Web Apps)

Το quiz-app είναι ρυθμισμένο για ανάπτυξη σε Azure Static Web Apps:

cd quiz-app
npm run build      # Δημιουργεί φάκελο dist/
# Αναπτύσσει μέσω ροής εργασίας GitHub Actions κατά την ώθηση στο main

Ρυθμίσεις Azure Static Web Apps:

Τοποθεσία εφαρμογής: /quiz-app
Τοποθεσία εξόδου: dist
Ροή εργασίας: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Δημιουργία PDF Τεκμηρίωσης

npm install                    # Εγκαταστήστε το docsify-to-pdf
npm run convert               # Δημιουργία PDF από docs

Τεκμηρίωση Docsify

npm install -g docsify-cli    # Εγκαταστήστε το Docsify παγκοσμίως
docsify serve                 # Εκτελέστε στον localhost:3000

Κατασκευές ανά Έργο

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

Έργα Vue: npm run build δημιουργεί παραγωγικά πακέτα
Στατικά έργα: Δεν απαιτείται βήμα κατασκευής, σερβίρονται απευθείας τα αρχεία

Οδηγίες Pull Request

Μορφή Τίτλου

Χρησιμοποιήστε σαφείς, περιγραφικούς τίτλους που υποδεικνύουν την περιοχή αλλαγής:

[Quiz-app] Προσθήκη νέου κουίζ για μάθημα Χ
[Lesson-3] Διόρθωση τυπογραφικού λάθους στο έργο terrarium
[Translation] Προσθήκη ισπανικής μετάφρασης για το μάθημα 5
[Docs] Ενημέρωση οδηγιών ρύθμισης

Απαιτούμενοι Έλεγχοι

Πριν από την υποβολή PR:

Ποιότητα Κώδικα:
- Εκτελέστε npm run lint στους επηρεασμένους φακέλους έργων
- Διορθώστε όλα τα σφάλματα και προειδοποιήσεις linting
Επαλήθευση Κατασκευής:
- Εκτελέστε npm run build εάν ισχύει
- Βεβαιωθείτε ότι δεν υπάρχουν σφάλματα κατασκευής
Επαλήθευση Συνδέσμων:
- Δοκιμάστε όλους τους συνδέσμους markdown
- Επαληθεύστε ότι οι αναφορές εικόνων λειτουργούν
Αναθεώρηση Περιεχομένου:
- Διόρθωση ορθογραφίας και γραμματικής
- Επιβεβαίωση ότι τα παραδείγματα κώδικα είναι σωστά και εκπαιδευτικά
- Επαλήθευση σωστής διατήρησης νοήματος στις μεταφράσεις

Απαιτήσεις Συνεισφοράς

Αποδοχή του Microsoft CLA (αυτόματος έλεγχος στην πρώτη PR)
Ακολουθήστε τον Κώδικα Συμπεριφοράς Ανοιχτού Κώδικα της Microsoft
Διαβάστε το CONTRIBUTING.md για λεπτομερείς οδηγίες
Αναφέρετε αριθμούς ζητημάτων στην περιγραφή PR αν ισχύει

Διαδικασία Αναθεώρησης

Οι PR ελέγχονται από συντηρητές και την κοινότητα
Προτεραιότητα στην εκπαιδευτική σαφήνεια
Τα παραδείγματα κώδικα να ακολουθούν τις τρέχουσες βέλτιστες πρακτικές
Οι μεταφράσεις ελέγχονται για ακρίβεια και πολιτισμική καταλληλότητα

Σύστημα Μετάφρασης

Αυτόματη Μετάφραση

Χρησιμοποιεί GitHub Actions με ροή εργασίας co-op-translator
Μεταφράζει σε πάνω από 50 γλώσσες αυτόματα
Αρχεία πηγής σε κύριους φακέλους
Τα μεταφρασμένα αρχεία βρίσκονται σε translations/{language-code}/

Προσθήκη Χειροκίνητων Βελτιώσεων Μετάφρασης

Εντοπίστε το αρχείο σε translations/{language-code}/
Κάντε βελτιώσεις διατηρώντας τη δομή
Εξασφαλίστε ότι τα παραδείγματα κώδικα παραμένουν λειτουργικά
Δοκιμάστε όλο το τοπικοποιημένο περιεχόμενο κουίζ

Μεταδεδομένα Μετάφρασης

Τα μεταφρασμένα αρχεία περιλαμβάνουν κεφαλίδα μεταδεδομένων:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Αντιμετώπιση και Επίλυση Προβλημάτων

Συνήθη Θέματα

Η εφαρμογή Quiz δεν ξεκινά:

Ελέγξτε την έκδοση Node.js (συνιστάται v14+)
Διαγράψτε node_modules και package-lock.json, εκτελέστε ξανά npm install
Ελέγξτε για σύγκρουση θυρών (προεπιλογή: Vite χρησιμοποιεί θύρα 5173)

Ο διακομιστής API δεν ξεκινά:

Επαληθεύστε ότι η έκδοση Node.js είναι ≥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 extension για έργα HTML
Εγκαταστήστε τις επεκτάσεις ESLint και Prettier για ομοιόμορφη μορφοποίηση
Χρησιμοποιήστε τα DevTools του περιηγητή για αποσφαλμάτωση JavaScript
Για έργα Vue, εγκαταστήστε την επέκταση Vue DevTools για περιηγητές

Θέματα Απόδοσης

Ο μεγάλος αριθμός μεταφρασμένων αρχείων (50+ γλώσσες) κάνει τα πλήρη κλωνοποιημένα αρχεία μεγάλα
Χρησιμοποιήστε επιφανειακό κλώνο αν εργάζεστε μόνο με το περιεχόμενο: git clone --depth 1
Εξαιρέστε τις μεταφράσεις από αναζητήσεις όταν δουλεύετε σε αγγλικό περιεχόμενο
Οι διαδικασίες κατασκευής μπορεί να είναι αργές στην πρώτη εκτέλεση (npm install, κατασκευή Vite)

Θέματα Ασφαλείας

Μεταβλητές Περιβάλλοντος

Τα κλειδιά 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
Πόροι Student Hub
GitHub Copilot συνιστάται για μαθητές
Πρόσθετα μαθήματα: Γενετική ΤΝ, Επιστήμη Δεδομένων, ML, IoT διαθέσιμα

Εργασία με Συγκεκριμένα Έργα

Για λεπτομερείς οδηγίες για κάθε έργο, ανατρέξτε στα README αρχεία:

quiz-app/README.md - Εφαρμογή quiz Vue 3
7-bank-project/README.md - Τραπεζική εφαρμογή με ταυτοποίηση
5-browser-extension/README.md - Ανάπτυξη επέκτασης περιηγητή
6-space-game/README.md - Ανάπτυξη παιχνιδιού με καμβά
9-chat-project/README.md - Έργο βοηθού συνομιλίας με ΤΝ

Δομή Monorepo

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

Κάθε μάθημα είναι αυτόνομο
Τα έργα δεν μοιράζονται εξαρτήσεις
Εργαστείτε σε μεμονωμένα έργα χωρίς να επηρεάζετε τα άλλα
Κλωνοποιήστε ολόκληρο το αποθετήριο για πλήρη εμπειρία προγράμματος σπουδών

Αποποίηση ευθυνών:
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI Co-op Translator. Παρόλο που προσπαθούμε για ακρίβεια, παρακαλούμε να γνωρίζετε ότι οι αυτοματοποιημένες μεταφράσεις μπορεί να περιέχουν σφάλματα ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για οποιεσδήποτε παρερμηνείες ή παρανοήσεις προκύψουν από τη χρήση αυτής της μετάφρασης.

22 KiB Raw Permalink Blame History Unescape Escape