14 KiB

Raw Permalink Blame History

AGENTS.md

Pangkalahatang-ideya ng Proyekto

Ang Data Science for Beginners ay isang komprehensibong kurikulum na tumatagal ng 10 linggo at may 20 aralin, na ginawa ng Microsoft Azure Cloud Advocates. Ang repositoryo ay isang mapagkukunan ng pag-aaral na nagtuturo ng mga pangunahing konsepto ng data science sa pamamagitan ng mga aralin na nakabatay sa proyekto, kabilang ang mga Jupyter notebook, interactive na pagsusulit, at mga praktikal na gawain.

Pangunahing Teknolohiya:

Jupyter Notebooks: Pangunahing medium ng pag-aaral gamit ang Python 3
Python Libraries: pandas, numpy, matplotlib para sa pagsusuri at visualisasyon ng data
Vue.js 2: Aplikasyon ng pagsusulit (quiz-app folder)
Docsify: Tagabuo ng site ng dokumentasyon para sa offline na access
Node.js/npm: Pamamahala ng package para sa mga JavaScript na bahagi
Markdown: Lahat ng nilalaman ng aralin at dokumentasyon

Arkitektura:

Repositoryo na pang-edukasyon na multi-wika na may malawak na mga pagsasalin
Nakabalangkas sa mga module ng aralin (1-Introduction hanggang 6-Data-Science-In-Wild)
Ang bawat aralin ay may kasamang README, mga notebook, mga gawain, at mga pagsusulit
Standalone Vue.js na aplikasyon ng pagsusulit para sa pre/post-lesson assessments
Suporta para sa GitHub Codespaces at VS Code dev containers

Mga Utos sa Setup

Setup ng Repositoryo

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

Setup ng Python Environment

# 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

Setup ng Aplikasyon ng Pagsusulit

# 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

Docsify Documentation Server

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

Setup ng Mga Proyekto ng Visualisasyon

Para sa mga proyekto ng visualisasyon tulad ng meaningful-visualizations (lesson 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

Workflow ng Pag-develop

Paggamit ng Jupyter Notebooks

Simulan ang Jupyter sa root ng repositoryo: jupyter notebook
Mag-navigate sa nais na folder ng aralin
Buksan ang mga .ipynb file upang magtrabaho sa mga ehersisyo
Ang mga notebook ay self-contained na may mga paliwanag at code cells
Karamihan sa mga notebook ay gumagamit ng pandas, numpy, at matplotlib - tiyaking naka-install ang mga ito

Estruktura ng Aralin

Ang bawat aralin ay karaniwang naglalaman ng:

README.md - Pangunahing nilalaman ng aralin na may teorya at mga halimbawa
notebook.ipynb - Mga praktikal na ehersisyo sa Jupyter notebook
assignment.ipynb o assignment.md - Mga gawain para sa pagsasanay
solution/ folder - Mga notebook ng solusyon at code
images/ folder - Mga sumusuportang visual na materyales

Pag-develop ng Aplikasyon ng Pagsusulit

Aplikasyon ng Vue.js 2 na may hot-reload sa panahon ng pag-develop
Ang mga pagsusulit ay naka-imbak sa quiz-app/src/assets/translations/
Ang bawat wika ay may sariling folder ng pagsasalin (en, fr, es, atbp.)
Ang pagbilang ng pagsusulit ay nagsisimula sa 0 at umaabot hanggang 39 (40 pagsusulit sa kabuuan)

Pagdaragdag ng Mga Pagsasalin

Ang mga pagsasalin ay inilalagay sa translations/ folder sa root ng repositoryo
Ang bawat wika ay may kumpletong estruktura ng aralin na ginaya mula sa Ingles
Automated na pagsasalin sa pamamagitan ng GitHub Actions (co-op-translator.yml)

Mga Tagubilin sa Pagsubok

Pagsubok ng Aplikasyon ng Pagsusulit

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

Pagsubok ng Notebook

Walang automated na test framework para sa mga notebook
Manu-manong pag-validate: Patakbuhin ang lahat ng cells nang sunod-sunod upang tiyakin na walang error
Siguraduhing naa-access ang mga data file at tama ang mga output
Tiyakin na maayos ang pag-render ng mga visualisasyon

Pagsubok ng Dokumentasyon

# Verify Docsify renders correctly
docsify serve

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

Mga Pag-check ng Kalidad ng Code

# 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

Mga Alituntunin sa Estilo ng Code

Python (Jupyter Notebooks)

Sundin ang PEP 8 na mga alituntunin sa estilo para sa Python code
Gumamit ng malinaw na pangalan ng variable na nagpapaliwanag sa data na sinusuri
Maglagay ng markdown cells na may mga paliwanag bago ang mga code cells
Panatilihing nakatuon ang mga code cells sa iisang konsepto o operasyon
Gumamit ng pandas para sa manipulasyon ng data, matplotlib para sa visualisasyon

Karaniwang pattern ng import:

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

JavaScript/Vue.js

Sundin ang Vue.js 2 na gabay sa estilo at pinakamahusay na mga kasanayan
ESLint configuration sa quiz-app/package.json
Gumamit ng Vue single-file components (.vue files)
Panatilihin ang arkitektura na nakabatay sa mga bahagi
Patakbuhin ang npm run lint bago mag-commit ng mga pagbabago

Markdown Documentation

Gumamit ng malinaw na hierarchy ng mga heading (# ## ### atbp.)
Maglagay ng mga code block na may mga specifier ng wika
Magdagdag ng alt text para sa mga imahe
Mag-link sa mga kaugnay na aralin at mapagkukunan
Panatilihing maayos ang haba ng linya para sa readability

Organisasyon ng File

Nilalaman ng aralin sa mga folder na may numero (01-defining-data-science, atbp.)
Mga solusyon sa dedikadong solution/ subfolders
Ang mga pagsasalin ay ginagaya ang estruktura ng Ingles sa translations/ folder
Panatilihin ang mga data file sa data/ o mga folder na partikular sa aralin

Build at Deployment

Deployment ng Aplikasyon ng Pagsusulit

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.)

Deployment ng Azure Static Web Apps

Ang quiz-app ay maaaring i-deploy sa Azure Static Web Apps:

Gumawa ng Azure Static Web App resource
Ikonekta sa GitHub repository
I-configure ang mga setting ng build:
- Lokasyon ng app: quiz-app
- Lokasyon ng output: dist
Ang workflow ng GitHub Actions ay awtomatikong mag-deploy kapag may push

Site ng Dokumentasyon

# 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

Ang repositoryo ay may kasamang dev container configuration
Ang Codespaces ay awtomatikong nagse-set up ng Python at Node.js environment
Buksan ang repositoryo sa Codespace sa pamamagitan ng GitHub UI
Ang lahat ng dependencies ay awtomatikong naka-install

Mga Alituntunin sa Pull Request

Bago Mag-submit

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

# Test changes locally
npm run serve

Format ng PR Title

Gumamit ng malinaw, deskriptibong mga pamagat
Format: [Component] Maikling paglalarawan
Mga Halimbawa:
- [Lesson 7] Ayusin ang Python notebook import error
- [Quiz App] Magdagdag ng German translation
- [Docs] I-update ang README na may bagong prerequisites

Mga Kinakailangang Pag-check

Siguraduhing tumatakbo ang lahat ng code nang walang error
Tiyakin na ang mga notebook ay ganap na na-eexecute
Kumpirmahin na matagumpay ang pag-build ng Vue.js apps
Suriin na gumagana ang mga link ng dokumentasyon
Subukan ang aplikasyon ng pagsusulit kung binago
Siguraduhin na ang mga pagsasalin ay may pare-parehong estruktura

Mga Alituntunin sa Kontribusyon

Sundin ang umiiral na estilo ng code at mga pattern
Magdagdag ng mga paliwanag na komento para sa kumplikadong lohika
I-update ang kaugnay na dokumentasyon
Subukan ang mga pagbabago sa iba't ibang module ng aralin kung naaangkop
Suriin ang CONTRIBUTING.md file

Karagdagang Tala

Karaniwang Ginagamit na Mga Library

pandas: Manipulasyon at pagsusuri ng data
numpy: Numerical computing
matplotlib: Visualisasyon at pag-plot ng data
seaborn: Statistical data visualization (ilang aralin)
scikit-learn: Machine learning (mga advanced na aralin)

Paggamit ng Mga Data File

Ang mga data file ay matatagpuan sa data/ folder o mga direktoryo na partikular sa aralin
Karamihan sa mga notebook ay inaasahan ang mga data file sa mga relative na path
Ang mga CSV file ang pangunahing format ng data
Ang ilang aralin ay gumagamit ng JSON para sa mga halimbawa ng non-relational na data

Suporta sa Multi-Wika

40+ na pagsasalin ng wika sa pamamagitan ng automated na GitHub Actions
Workflow ng pagsasalin sa .github/workflows/co-op-translator.yml
Ang mga pagsasalin ay nasa translations/ folder na may mga code ng wika
Ang mga pagsasalin ng pagsusulit ay nasa quiz-app/src/assets/translations/

Mga Opsyon sa Development Environment

Local Development: Mag-install ng Python, Jupyter, Node.js nang lokal
GitHub Codespaces: Cloud-based na instant development environment
VS Code Dev Containers: Lokal na container-based na development
Binder: I-launch ang mga notebook sa cloud (kung naka-configure)

Mga Alituntunin sa Nilalaman ng Aralin

Ang bawat aralin ay standalone ngunit bumubuo sa mga naunang konsepto
Ang mga pre-lesson quiz ay sumusubok sa naunang kaalaman
Ang mga post-lesson quiz ay nagpapatibay ng pagkatuto
Ang mga gawain ay nagbibigay ng praktikal na pagsasanay
Ang mga sketchnotes ay nagbibigay ng visual na buod

Pag-troubleshoot ng Karaniwang Mga Isyu

Mga Isyu sa Jupyter Kernel:

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

Mga Pagkabigo sa npm Install:

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

Mga Error sa Import sa Notebook:

Siguraduhing naka-install ang lahat ng kinakailangang library
Suriin ang compatibility ng bersyon ng Python (inirerekomenda ang Python 3.7+)
Tiyakin na naka-activate ang virtual environment

Hindi Naglo-load ang Docsify:

Siguraduhing nagseserbisyo mula sa root ng repositoryo
Suriin na umiiral ang index.html
Tiyakin ang tamang network access (port 3000)

Mga Pagsasaalang-alang sa Performance

Ang malalaking dataset ay maaaring tumagal ng oras upang mag-load sa mga notebook
Ang pag-render ng visualisasyon ay maaaring mabagal para sa mga kumplikadong plot
Ang Vue.js dev server ay nagbibigay-daan sa hot-reload para sa mabilis na iterasyon
Ang mga production build ay na-optimize at minified

Mga Tala sa Seguridad

Walang sensitibong data o mga kredensyal ang dapat i-commit
Gumamit ng environment variables para sa anumang API keys sa mga cloud lessons
Ang mga aralin na may kaugnayan sa Azure ay maaaring mangailangan ng mga kredensyal ng Azure account
Panatilihing updated ang mga dependencies para sa mga security patch

Pag-aambag sa Mga Pagsasalin

Ang mga automated na pagsasalin ay pinamamahalaan sa pamamagitan ng GitHub Actions
Malugod na tinatanggap ang mga manu-manong pagwawasto para sa katumpakan ng pagsasalin
Sundin ang umiiral na estruktura ng folder ng pagsasalin
I-update ang mga link ng pagsusulit upang isama ang parameter ng wika: ?loc=fr
Subukan ang mga isinaling aralin para sa tamang pag-render

Kaugnay na Mga Mapagkukunan

Pangunahing kurikulum: https://aka.ms/datascience-beginners
Microsoft Learn: https://docs.microsoft.com/learn/
Student Hub: https://docs.microsoft.com/learn/student-hub
Discussion Forum: https://github.com/microsoft/Data-Science-For-Beginners/discussions
Iba pang kurikulum ng Microsoft: ML for Beginners, AI for Beginners, Web Dev for Beginners

Pagpapanatili ng Proyekto

Regular na pag-update upang mapanatiling kasalukuyan ang nilalaman
Malugod na tinatanggap ang mga kontribusyon ng komunidad
Ang mga isyu ay sinusubaybayan sa GitHub
Ang mga PR ay sinusuri ng mga tagapangalaga ng kurikulum
Buwanang pagsusuri at pag-update ng nilalaman

Paunawa:
Ang dokumentong ito ay isinalin gamit ang AI translation service na Co-op Translator. Bagama't sinisikap naming maging tumpak, mangyaring tandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa kanyang katutubong wika ang dapat ituring na opisyal na sanggunian. Para sa mahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na dulot ng paggamit ng pagsasaling ito.

14 KiB Raw Permalink Blame History