20 KiB

Raw Blame History Unescape Escape

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

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

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

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

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

Ρύθμιση Εφαρμογής Κουίζ (Vue 3 + Vite)

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)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

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

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

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

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

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

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

Ροή Εργασίας Ανάπτυξης

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

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

Για Μαθητές

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

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

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

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

Δοκιμή Εφαρμογής Κουίζ

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

Δοκιμή API Τραπεζικού Έργου

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:

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 Τεκμηρίωσης

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Τεκμηρίωση Docsify

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:

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

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

Συμφωνήστε με το Microsoft CLA (αυτοματοποιημένος έλεγχος στο πρώτο PR)
Ακολουθήστε τον Microsoft Open Source Code of Conduct
Δείτε το 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": "..."
}
-->

Εντοπισμός Σφαλμάτων και Αντιμετώπιση Προβλημάτων

Συνηθισμένα Προβλήματα

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

Ελέγξτε την έκδοση 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
Πόροι Student Hub
[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub

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

20 KiB Raw Blame History Unescape Escape