AGENTS.md

1# AGENTS.md
2 
3## Proje Genel Bakışı
4 
5Bu, yeni başlayanlara web geliştirme temellerini öğretmek için hazırlanmış eğitim amaçlı bir müfredat deposudur. Müfredat, Microsoft Cloud Advocates tarafından geliştirilen kapsamlı 12 haftalık bir kurstur ve JavaScript, CSS ve HTML'i kapsayan 24 uygulamalı dersten oluşur.
6 
7### Ana Bileşenler
8 
9- **Eğitim İçeriği**: Proje tabanlı modüllerde düzenlenmiş 24 yapılandırılmış ders
10- **Pratik Projeler**: Terrarium, Yazma Oyunu, Tarayıcı Uzantısı, Uzay Oyunu, Banka Uygulaması, Kod Editörü ve AI Sohbet Asistanı
11- **Etkileşimli Testler**: Her biri 3 sorudan oluşan 48 test (ders öncesi/sonrası değerlendirmeleri)
12- **Çok Dilli Destek**: GitHub Actions aracılığıyla 50+ dilde otomatik çeviriler
13- **Teknolojiler**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projeleri için)
14 
15### Mimari
16 
17- Ders tabanlı yapıya sahip eğitim deposu
18- Her ders klasörü README, kod örnekleri ve çözümler içerir
19- Bağımsız projeler ayrı dizinlerde (quiz-app, çeşitli ders projeleri)
20- GitHub Actions kullanan çeviri sistemi (co-op-translator)
21- Docsify ile sunulan ve PDF olarak da erişilebilir belge
22 
23## Kurulum Komutları
24 
25Bu depo öncelikle eğitim içeriklerini tüketmek içindir. Belirli projelerle çalışmak için:
26 
27### Ana Depo Kurulumu
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz Uygulaması Kurulumu (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Geliştirme sunucusunu başlat
40npm run build      # Üretim için derle
41npm run lint       # ESLint'i çalıştır
42```
43 
44### Banka Projesi API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # API sunucusunu başlat
50npm run lint       # ESLint çalıştır
51npm run format     # Prettier ile biçimlendir
52```
53 
54### Tarayıcı Uzantısı Projeleri
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Tarayıcıya özgü eklenti yükleme talimatlarını izleyin
60```
61 
62### Uzay Oyunu Projeleri
63 
64```bash
65cd 6-space-game/solution
66npm install
67# index.html dosyasını tarayıcıda açın veya Canlı Sunucu'yu kullanın
68```
69 
70### Sohbet Projesi (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# GITHUB_TOKEN ortam değişkenini ayarlayın
76python api.py
77```
78 
79## Geliştirme İş Akışı
80 
81### İçerik Katkı Sağlayıcılar için
82 
831. Depoyu GitHub hesabınıza **forklayın**
842. Forkladığınız depoyu **yerel olarak klonlayın**
853. Değişiklikleriniz için **yeni bir dal oluşturun**
864. Ders içeriği veya kod örneklerinde değişiklik yapın
875. İlgili proje dizinlerinde kod değişikliklerini test edin
886. Katkı yönergelerine uygun şekilde pull request gönderin
89 
90### Öğrenenler için
91 
921. Depoyu forklayın veya klonlayın
932. Ders dizinlerinde sırasıyla gezin
943. Her ders için README dosyalarını okuyun
954. https://ff-quizzes.netlify.app/web/ adresinde ders öncesi testleri tamamlayın
965. Ders klasörlerindeki kod örneklerinde çalışın
976. Ödevleri ve zorlukları tamamlayın
987. Ders sonrası testleri yapın
99 
100### Canlı Geliştirme
101 
102- **Dokümantasyon**: Kök dizinde `docsify serve` komutunu çalıştırın (port 3000)
103- **Quiz Uygulaması**: `quiz-app` dizininde `npm run dev` komutunu çalıştırın
104- **Projeler**: HTML projeleri için VS Code Live Server uzantısını kullanın
105- **API Projeleri**: İlgili API dizinlerinde `npm start` komutunu çalıştırın
106 
107## Test Talimatları
108 
109### Quiz Uygulaması Testi
110 
111```bash
112cd quiz-app
113npm run lint       # Kod stil sorunlarını kontrol et
114npm run build      # Derlemenin başarılı olduğunu doğrula
115```
116 
117### Bank API Testi
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Kod stili sorunlarını kontrol et
122node server.js     # Sunucunun hatasız başlayıp başlamadığını doğrula
123```
124 
125### Genel Test Yaklaşımı
126 
127- Bu eğitim deposunda kapsamlı otomatik testler yoktur
128- Manuel testler şunlara odaklanır:
129  - Kod örneklerinin hatasız çalışması
130  - Dokümantasyondaki bağlantıların doğru çalışması
131  - Proje derlemelerinin başarıyla tamamlanması
132  - Örneklerin en iyi uygulamalara uygunluğu
133 
134### Gönderim Öncesi Kontroller
135 
136- Paket.json içeren dizinlerde `npm run lint` komutunu çalıştırın
137- Markdown bağlantılarını doğrulayın
138- Kod örneklerini tarayıcı veya Node.js'de test edin
139- Çevirilerin yapısını düzgün koruduğunu kontrol edin
140 
141## Kod Stili Kılavuzu
142 
143### JavaScript
144 
145- Modern ES6+ sözdizimi kullanın
146- Projelerde sağlanan standart ESLint yapılandırmalarına uyun
147- Eğitim amaçlı anlamlı değişken ve fonksiyon adları kullanın
148- Öğrenenler için kavramları açıklayan yorumlar ekleyin
149- Yapılandırılmış yerlerde Prettier kullanarak biçimlendirin
150 
151### HTML/CSS
152 
153- Anlamsal HTML5 elemanları
154- Duyarlı tasarım prensipleri
155- Açık sınıf isimlendirme kuralları
156- CSS tekniklerini açıklayan yorumlar
157 
158### Python
159 
160- PEP 8 stil yönergeleri
161- Açık, eğitim odaklı kod örnekleri
162- Öğrenme için yardımcı olduğunda tür ipuçları
163 
164### Markdown Dokümantasyonu
165 
166- Açık başlık hiyerarşisi
167- Dil belirtmeli kod blokları
168- Ek kaynaklara bağlantılar
169- `images/` dizinlerinde ekran görüntüleri ve resimler
170- Erişilebilirlik için resimlere alt metin
171 
172### Dosya Organizasyonu
173 
174- Dersler sırasıyla numaralandırılmış (1-getting-started-lessons, 2-js-basics vb.)
175- Her projenin `solution/` ve genellikle `start/` veya `your-work/` dizinleri var
176- Derslere özgü `images/` klasörlerinde görseller saklanır
177- Çeviriler `translations/{language-code}/` yapısındadır
178 
179## Derleme ve Yayınlama
180 
181### Quiz Uygulaması Yayınlama (Azure Static Web Apps)
182 
183quiz-app Azure Static Web Apps yayını için yapılandırılmıştır:
184 
185```bash
186cd quiz-app
187npm run build      # dist/ klasörü oluşturur
188# Ana dala push yapıldığında GitHub Actions iş akışı ile dağıtım yapar
189```
190 
191Azure Static Web Apps yapılandırması:
192- **Uygulama konumu**: `/quiz-app`
193- **Çıktı konumu**: `dist`
194- **İş akışı**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Dokümantasyon PDF Oluşturma
197 
198```bash
199npm install                    # docsify-to-pdf yükle
200npm run convert               # Belgelerden PDF oluştur
201```
202 
203### Docsify Dokümantasyonu
204 
205```bash
206npm install -g docsify-cli    # Docsify'i global olarak kur
207docsify serve                 # localhost:3000 üzerinde sun
208```
209 
210### Proje Bazlı Derlemeler
211 
212Her proje dizininin kendi derleme süreci olabilir:
213- Vue projeleri: `npm run build` ile prodüksiyon paketleri oluşturur
214- Statik projeler: Derleme adımı yok, dosyalar doğrudan sunulur
215 
216## Pull Request Yönergeleri
217 
218### Başlık Formatı
219 
220Değişiklik alanını belirten net, açıklayıcı başlıklar kullanın:
221- `[Quiz-app] Ders X için yeni quiz ekle`
222- `[Lesson-3] Terrarium projesindeki yazım hatasını düzelt`
223- `[Translation] Ders 5 için İspanyolca çeviri ekle`
224- `[Docs] Kurulum talimatlarını güncelle`
225 
226### Gerekli Kontroller
227 
228PR göndermeden önce:
229 
2301. **Kod Kalitesi**:
231   - Etkilenen proje dizinlerinde `npm run lint` çalıştırın
232   - Tüm lint hatalarını ve uyarılarını düzeltin
233 
2342. **Derleme Doğrulaması**:
235   - Varsa `npm run build` komutunu çalıştırın
236   - Derleme hatası olmadığından emin olun
237 
2383. **Link Doğrulama**:
239   - Tüm markdown bağlantılarını test edin
240   - Resim referanslarının çalıştığını kontrol edin
241 
2424. **İçerik İncelemesi**:
243   - Yazım ve dilbilgisini gözden geçirin
244   - Kod örneklerinin doğru ve eğitici olduğundan emin olun
245   - Çevirilerin orijinal anlamı koruduğunu doğrulayın
246 
247### Katkı Gereksinimleri
248 
249- Microsoft CLA'ya (ilk PR'de otomatik kontrol)
250- [Microsoft Açık Kaynak Davranış Kuralları](https://opensource.microsoft.com/codeofconduct/) uyumu
251- Detaylı yönergeler için [CONTRIBUTING.md](./CONTRIBUTING.md)
252- PR açıklamasında ilgili sorun numarasına referans verin (varsa)
253 
254### İnceleme Süreci
255 
256- PR'lar bakımcılar ve topluluk tarafından incelenir
257- Eğitim açıklığı ön plandadır
258- Kod örnekleri güncel en iyi uygulamalara uygun olmalıdır
259- Çeviriler doğruluk ve kültürel uygunluk açısından gözden geçirilir
260 
261## Çeviri Sistemi
262 
263### Otomatik Çeviri
264 
265- GitHub Actions ile co-op-translator iş akışı kullanılır
266- 50+ dile otomatik çeviri yapılır
267- Kaynak dosyalar ana dizinlerde
268- Çevrilmiş dosyalar `translations/{language-code}/` dizinlerinde
269 
270### Manuel Çeviri İyileştirmeleri Ekleme
271 
2721. `translations/{language-code}/` içinde dosyayı bulun
2732. Yapıyı koruyarak iyileştirmeler yapın
2743. Kod örneklerinin işlevselliğini sağlayın
2754. Yerelleştirilmiş test içeriklerini test edin
276 
277### Çeviri Meta Verisi
278 
279Çevrilmiş dosyalar meta veri başlığı içerir:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Hata Ayıklama ve Sorun Giderme
293 
294### Yaygın Sorunlar
295 
296**Quiz uygulaması başlamıyor**:
297- Node.js sürümünü kontrol edin (v14+ önerilir)
298- `node_modules` ve `package-lock.json` dosyalarını silip tekrar `npm install` yapın
299- Port çakışmalarını kontrol edin (varsayılan: Vite 5173 portunu kullanır)
300 
301**API sunucusu başlamıyor**:
302- Node.js sürümünün minimum şartları sağladığını kontrol edin (node >=10)
303- Portun kullanımda olup olmadığını kontrol edin
304- Tüm bağımlılıkların `npm install` ile yüklendiğinden emin olun
305 
306**Tarayıcı uzantısı yüklenmiyor**:
307- manifest.json dosyasının doğru formatta olduğunu doğrulayın
308- Tarayıcı konsolunda hata olup olmadığını kontrol edin
309- Tarayıcıya özgü uzantı yükleme talimatlarını izleyin
310 
311**Python sohbet projesi sorunları**:
312- OpenAI paketi kurulu mu: `pip install openai`
313- GITHUB_TOKEN ortam değişkeni ayarlı mı kontrol edin
314- GitHub Modeller erişim izinlerini doğrulayın
315 
316**Docsify dokümanları sunmuyor**:
317- docsify-cli global olarak kurun: `npm install -g docsify-cli`
318- Depo kök dizininden çalıştırın
319- `docs/_sidebar.md` dosyasının var olduğundan emin olun
320 
321### Geliştirme Ortamı İpuçları
322 
323- HTML projeleri için VS Code Live Server uzantısı kullanın
324- Tutarlı biçimlendirme için ESLint ve Prettier uzantılarını kurun
325- JavaScript hata ayıklama için tarayıcı Geliştirici Araçlarını kullanın
326- Vue projeleri için Vue DevTools tarayıcı uzantısını yükleyin
327 
328### Performans Dikkatleri
329 
330- Çok sayıda çeviri dosyası (50+ dil) tam klonları büyük yapar
331- Sadece içerikle çalışıyorsanız derinliği 1 olan klon kullanın: `git clone --depth 1`
332- İngilizce içerik üzerinde çalışırken çevirileri aramalardan hariç tutun
333- İlk çalıştırmada derleme ve yükleme işlemleri yavaş olabilir (npm install, Vite build)
334 
335## Güvenlik Dikkatleri
336 
337### Ortam Değişkenleri
338 
339- API anahtarları asla depoya gönderilmemelidir
340- `.env` dosyalarını kullanın (zaten `.gitignore` içinde)
341- Gerekli ortam değişkenlerini proje README'lerinde belgeleyin
342 
343### Python Projeleri
344 
345- Sanal ortam kullanın: `python -m venv venv`
346- Bağımlılıkları güncel tutun
347- GitHub tokenları minimum gerekli izinlere sahip olmalıdır
348 
349### GitHub Modeller Erişimi
350 
351- GitHub Modeller için Kişisel Erişim Tokenları (PAT) gereklidir
352- Tokenlar ortam değişkeni olarak saklanmalıdır
353- Tokenlar veya kimlik bilgileri asla depoya gönderilmemelidir
354 
355## Ek Notlar
356 
357### Hedef Kitle
358 
359- Web geliştirmeye tamamen yeni başlayanlar
360- Öğrenciler ve kendi kendine öğrenenler
361- Müfredatı sınıflarında kullanan öğretmenler
362- İçerik erişilebilirlik ve kademeli beceri geliştirmeye yönelik
363 
364### Eğitim Felsefesi
365 
366- Proje tabanlı öğrenme yaklaşımı
367- Sık bilgi ölçme testleri (quizler)
368- Uygulamalı kodlama egzersizleri
369- Gerçek dünya uygulama örnekleri
370- Frameworklerden önce temel bilgilere odaklanma
371 
372### Depo Bakımı
373 
374- Aktif öğrenci ve katkı sağlayıcı topluluğu
375- Bağımlılıklar ve içerik düzenli olarak güncellenir
376- Sorunlar ve tartışmalar bakımcılar tarafından izlenir
377- Çeviri güncellemeleri GitHub Actions ile otomatik yapılır
378 
379### İlgili Kaynaklar
380 
381- [Microsoft Learn modülleri](https://docs.microsoft.com/learn/)
382- [Student Hub kaynakları](https://docs.microsoft.com/learn/student-hub/)
383- Öğrenenler için önerilen [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
384- Ek dersler: Üretken AI, Veri Bilimi, ML, IoT müfredatları mevcut
385 
386### Belirli Projeler ile Çalışma
387 
388Bireysel projeler için ayrıntılı talimatlar aşağıdaki README dosyalarında:
389- `quiz-app/README.md` - Vue 3 quiz uygulaması
390- `7-bank-project/README.md` - Kimlik doğrulamalı banka uygulaması
391- `5-browser-extension/README.md` - Tarayıcı uzantısı geliştirme
392- `6-space-game/README.md` - Canvas tabanlı oyun geliştirme
393- `9-chat-project/README.md` - AI sohbet asistanı projesi
394 
395### Monorepo Yapısı
396 
397Geleneksel bir monorepo olmasa da, bu depo birden çok bağımsız proje içerir:
398- Her ders kendi başına tamamlanabilir
399- Projeler bağımlılık paylaşmaz
400- Bireysel projeler üzerinde diğerlerini etkilemeden çalışabilirsiniz
401- Tam müfredat deneyimi için tüm depo klonlanabilir
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Feragatname**:  
407Bu belge [Co-op Translator](https://github.com/Azure/co-op-translator) adlı AI çeviri hizmeti kullanılarak çevrilmiştir. Doğruluk için çaba göstersek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayın. Orijinal belge, kendi ana dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu oluşabilecek yanlış anlamalar veya yorum hatalarından sorumlu değiliz.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->