12 KiB

Raw Permalink Blame History

AGENTS.md

Muhtasari wa Mradi

Data Science for Beginners ni mtaala wa kina wa wiki 10, masomo 20 ulioundwa na Microsoft Azure Cloud Advocates. Hifadhi hii ni rasilimali ya kujifunza inayofundisha dhana za msingi za sayansi ya data kupitia masomo yanayotegemea miradi, ikijumuisha Jupyter notebooks, maswali ya maingiliano, na mazoezi ya vitendo.

Teknolojia Muhimu:

Jupyter Notebooks: Njia kuu ya kujifunza kwa kutumia Python 3
Maktaba za Python: pandas, numpy, matplotlib kwa uchambuzi wa data na uonyeshaji
Vue.js 2: Programu ya maswali (folda ya quiz-app)
Docsify: Jenereta ya tovuti ya nyaraka kwa ufikiaji wa nje ya mtandao
Node.js/npm: Usimamizi wa vifurushi kwa vipengele vya JavaScript
Markdown: Yote yaliyomo kwenye masomo na nyaraka

Muundo:

Hifadhi ya elimu ya lugha nyingi yenye tafsiri nyingi
Imeundwa katika moduli za masomo (1-Introduction hadi 6-Data-Science-In-Wild)
Kila somo linajumuisha README, notebooks, mazoezi, na maswali
Programu ya maswali ya Vue.js inayojitegemea kwa tathmini kabla/baada ya somo
Msaada wa GitHub Codespaces na kontena za maendeleo za VS Code

Amri za Usanidi

Usanidi wa Hifadhi

# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners

Usanidi wa Mazingira ya Python

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

Usanidi wa Programu ya Maswali

# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint

Seva ya Nyaraka ya Docsify

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

Usanidi wa Miradi ya Uonyeshaji

Kwa miradi ya uonyeshaji kama meaningful-visualizations (somo la 13):

# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint

Mtiririko wa Maendeleo

Kufanya Kazi na Jupyter Notebooks

Anzisha Jupyter katika mzizi wa hifadhi: jupyter notebook
Tembelea folda ya somo unalotaka
Fungua faili za .ipynb ili kufanya mazoezi
Notebooks ni za kujitegemea zikiwa na maelezo na seli za msimbo
Notebooks nyingi zinatumia pandas, numpy, na matplotlib - hakikisha zimesakinishwa

Muundo wa Somo

Kila somo kwa kawaida lina:

README.md - Yaliyomo kuu ya somo na nadharia na mifano
notebook.ipynb - Mazoezi ya vitendo ya Jupyter notebook
assignment.ipynb au assignment.md - Mazoezi ya mazoezi
Folda ya solution/ - Notebooks za suluhisho na msimbo
Folda ya images/ - Vifaa vya kuonyesha vinavyosaidia

Maendeleo ya Programu ya Maswali

Programu ya Vue.js 2 yenye upakiaji wa haraka wakati wa maendeleo
Maswali yamehifadhiwa katika quiz-app/src/assets/translations/
Kila lugha ina folda yake ya tafsiri (en, fr, es, nk.)
Nambari ya maswali inaanza 0 na inaendelea hadi 39 (maswali 40 kwa jumla)

Kuongeza Tafsiri

Tafsiri zinawekwa katika folda ya translations/ kwenye mzizi wa hifadhi
Kila lugha ina muundo kamili wa somo unaolingana na Kiingereza
Tafsiri za kiotomatiki kupitia GitHub Actions (co-op-translator.yml)

Maelekezo ya Kupima

Upimaji wa Programu ya Maswali

cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve

Upimaji wa Notebooks

Hakuna mfumo wa upimaji wa kiotomatiki kwa notebooks
Uthibitishaji wa mwongozo: Endesha seli zote kwa mpangilio ili kuhakikisha hakuna makosa
Hakikisha faili za data zinapatikana na matokeo yanazalishwa kwa usahihi
Angalia kwamba uonyeshaji unachorwa vizuri

Upimaji wa Nyaraka

# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation

Ukaguzi wa Ubora wa Msimbo

# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors

Miongozo ya Mtindo wa Msimbo

Python (Jupyter Notebooks)

Fuata miongozo ya mtindo wa PEP 8 kwa msimbo wa Python
Tumia majina ya kutofautisha yanayoelezea data inayochambuliwa
Jumuisha seli za markdown zenye maelezo kabla ya seli za msimbo
Weka seli za msimbo zikilenga dhana moja au operesheni moja
Tumia pandas kwa uendeshaji wa data, matplotlib kwa uonyeshaji

Muundo wa kawaida wa uingizaji:

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

JavaScript/Vue.js

Fuata mwongozo wa mtindo wa Vue.js 2 na mazoea bora
Usanidi wa ESLint katika quiz-app/package.json
Tumia vipengele vya faili moja vya Vue (.vue files)
Dumisha muundo wa vipengele
Endesha npm run lint kabla ya kuwasilisha mabadiliko

Nyaraka za Markdown

Tumia uongozi wa wazi wa vichwa (# ## ### nk.)
Jumuisha vizuizi vya msimbo na viainishi vya lugha
Ongeza maandishi mbadala kwa picha
Unganisha masomo na rasilimali zinazohusiana
Weka urefu wa mistari kuwa wa kusomeka

Mpangilio wa Faili

Yaliyomo ya somo katika folda zenye nambari (01-defining-data-science, nk.)
Suluhisho katika folda ndogo ya solution/
Tafsiri zinaakisi muundo wa Kiingereza katika folda ya translations/
Weka faili za data katika data/ au folda maalum za somo

Ujenzi na Uwekaji

Uwekaji wa Programu ya Maswali

cd quiz-app

# Build production version
npm run build

# Output is in dist/ folder
# Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.)

Uwekaji wa Azure Static Web Apps

Programu ya quiz-app inaweza kuwekwa kwenye Azure Static Web Apps:

Unda rasilimali ya Azure Static Web App
Unganisha na hifadhi ya GitHub
Sanidi mipangilio ya ujenzi:
- Eneo la programu: quiz-app
- Eneo la matokeo: dist
Mtiririko wa kazi wa GitHub Actions utaweka kiotomatiki unapofanya push

Tovuti ya Nyaraka

# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify

GitHub Codespaces

Hifadhi inajumuisha usanidi wa kontena la maendeleo
Codespaces huweka kiotomatiki mazingira ya Python na Node.js
Fungua hifadhi katika Codespace kupitia UI ya GitHub
Vifurushi vyote vinasakinishwa kiotomatiki

Miongozo ya Maombi ya Kuvuta (Pull Request)

Kabla ya Kuwasilisha

# For Vue.js changes in quiz-app
cd quiz-app
npm run lint
npm run build

# Test changes locally
npm run serve

Muundo wa Kichwa cha PR

Tumia vichwa vya wazi, vya kuelezea
Muundo: [Sehemu] Maelezo mafupi
Mifano:
- [Somo la 7] Rekebisha hitilafu ya uingizaji wa notebook ya Python
- [Programu ya Maswali] Ongeza tafsiri ya Kijerumani
- [Nyaraka] Sasisha README na mahitaji mapya

Ukaguzi Unaohitajika

Hakikisha msimbo wote unafanya kazi bila makosa
Thibitisha notebooks zinaendeshwa kikamilifu
Hakikisha programu za Vue.js zinajengwa kwa mafanikio
Angalia kwamba viungo vya nyaraka vinafanya kazi
Jaribu programu ya maswali ikiwa imebadilishwa
Thibitisha tafsiri zinadumisha muundo thabiti

Miongozo ya Mchango

Fuata mtindo wa msimbo uliopo na mifumo
Ongeza maoni ya kuelezea kwa mantiki ngumu
Sasisha nyaraka husika
Jaribu mabadiliko katika moduli tofauti za somo ikiwa inafaa
Soma faili ya CONTRIBUTING.md

Vidokezo vya Ziada

Maktaba za Kawaida Zinazotumika

pandas: Uendeshaji na uchambuzi wa data
numpy: Uhesabu wa namba
matplotlib: Uonyeshaji wa data na uchoraji
seaborn: Uonyeshaji wa data wa takwimu (masomo fulani)
scikit-learn: Kujifunza kwa mashine (masomo ya juu)

Kufanya Kazi na Faili za Data

Faili za data ziko katika folda ya data/ au folda maalum za somo
Notebooks nyingi zinatarajia faili za data katika njia za jamaa
Faili za CSV ni muundo wa msingi wa data
Masomo fulani yanatumia JSON kwa mifano ya data isiyo ya uhusiano

Msaada wa Lugha Nyingi

Tafsiri 40+ za lugha kupitia GitHub Actions za kiotomatiki
Mtiririko wa tafsiri katika .github/workflows/co-op-translator.yml
Tafsiri katika folda ya translations/ yenye misimbo ya lugha
Tafsiri za maswali katika quiz-app/src/assets/translations/

Chaguo za Mazingira ya Maendeleo

Maendeleo ya Ndani: Sakinisha Python, Jupyter, Node.js ndani
GitHub Codespaces: Mazingira ya maendeleo ya papo hapo ya wingu
VS Code Dev Containers: Maendeleo ya ndani kwa kutumia kontena
Binder: Fungua notebooks katika wingu (ikiwa imewekwa)

Miongozo ya Yaliyomo ya Somo

Kila somo ni la kujitegemea lakini linajenga dhana za awali
Maswali ya kabla ya somo yanapima maarifa ya awali
Maswali ya baada ya somo yanasisitiza kujifunza
Mazoezi yanatoa mazoezi ya vitendo
Sketchnotes zinatoa muhtasari wa kuona

Kutatua Masuala ya Kawaida

Masuala ya Kernel ya Jupyter:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

Hitilafu za Usakinishaji wa npm:

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Hitilafu za Uingizaji katika Notebooks:

Thibitisha maktaba zote zinazohitajika zimesakinishwa
Angalia utangamano wa toleo la Python (Python 3.7+ inapendekezwa)
Hakikisha mazingira ya kawaida yamewezeshwa

Docsify Haipakii:

Thibitisha unahudumia kutoka mzizi wa hifadhi
Angalia kwamba index.html ipo
Hakikisha ufikiaji sahihi wa mtandao (bandari 3000)

Mazingatio ya Utendaji

Seti kubwa za data zinaweza kuchukua muda kupakia katika notebooks
Uchoraji wa uonyeshaji unaweza kuwa polepole kwa michoro ngumu
Seva ya maendeleo ya Vue.js inawezesha upakiaji wa haraka kwa kurudia haraka
Ujenzi wa uzalishaji umeboreshwa na umepunguzwa

Vidokezo vya Usalama

Hakuna data nyeti au hati za siri zinapaswa kuwasilishwa
Tumia vigezo vya mazingira kwa funguo zozote za API katika masomo ya wingu
Masomo yanayohusiana na Azure yanaweza kuhitaji hati za akaunti ya Azure
Weka maktaba zikiwa zimesasishwa kwa viraka vya usalama

Kuchangia Tafsiri

Tafsiri za kiotomatiki zinasimamiwa kupitia GitHub Actions
Marekebisho ya mwongozo yanakaribishwa kwa usahihi wa tafsiri
Fuata muundo wa folda ya tafsiri uliopo
Sasisha viungo vya maswali ili kujumuisha parameter ya lugha: ?loc=fr
Jaribu masomo yaliyotafsiriwa ili kuhakikisha yanachapishwa vizuri

Rasilimali Zinazohusiana

Mtaala kuu: https://aka.ms/datascience-beginners
Microsoft Learn: https://docs.microsoft.com/learn/
Student Hub: https://docs.microsoft.com/learn/student-hub
Jukwaa la Majadiliano: https://github.com/microsoft/Data-Science-For-Beginners/discussions
Mitaala mingine ya Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners

Matengenezo ya Mradi

Sasisho za mara kwa mara ili kuweka yaliyomo kuwa ya sasa
Michango ya jamii inakaribishwa
Masuala yanafuatiliwa kwenye GitHub
PRs zinakaguliwa na waangalizi wa mtaala
Mapitio na sasisho za yaliyomo kila mwezi

Kanusho:
Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI Co-op Translator. Ingawa tunajitahidi kuhakikisha usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kutokuwa sahihi. Hati ya asili katika lugha yake ya awali inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatutawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii.

12 KiB Raw Permalink Blame History