# Best Practices for Developers Contributing to AI For Beginners: A Complete Guide

> Learn best practices for contributing to Microsoft's AI For Beginners. Follow repo org, notebook style, dependency management, and PR etiquette for a beginner-friendly curriculum.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: best-practices
- Published: 2026-08-02

---

**Contributors to Microsoft's AI For Beginners should follow strict repository organization, notebook style conventions, dependency management via [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml), translation workflows, and pull request etiquette to maintain a stable, beginner-friendly curriculum.**

The [microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) repository serves as one of the most popular open-source AI curricula on GitHub, blending Jupyter notebooks, lesson markdown, and a Vue-based quiz application. Whether you're fixing a typo, adding a new lesson, or translating content, following the established best practices for developers ensures your contributions integrate smoothly and preserve the learning experience for thousands of beginners worldwide.

## Repository Layout and Folder Organization

The AI For Beginners curriculum follows a strict top-level folder structure that separates content by purpose. Adhering to this layout prevents tangled dependencies and makes navigation intuitive for learners.

### Required Top-Level Folders

- **`lessons/`** — Core curriculum modules organized by topic (1-Intro, 2-History, 3-NeuralNetworks, etc.)
- **`examples/`** — Standalone demo scripts for absolute beginners
- **`etc/quiz-app/`** — Vue.js quiz application source code
- **`translations/`** — Language-specific lesson packs (e.g., `translations/es/`, `translations/zh/`)

As documented in [[`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md), this separation lets learners navigate the curriculum logically and enables maintainers to add new lessons or translations without breaking existing content.

## Lesson Structure Standards for AI For Beginners

Every lesson must follow a consistent three-part structure to ensure predictable learning flow. This convention is enforced throughout the `lessons/` directory and documented in the main README.

### Required Lesson Components

1. **Pre-reading markdown file** ([`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)) — Theory and links to external resources
2. **Executable Jupyter notebook(s)** — Hands-on code in PyTorch and/or TensorFlow
3. **Optional `lab/` sub-folder** — Additional practice exercises

When creating a new lesson, scaffold it following this pattern:

```bash

# Create the lesson folder matching the existing numbering scheme

mkdir -p lessons/5-NLP/22-NewTopic

# Add the markdown scaffold with proper headings

cat > lessons/5-NLP/22-NewTopic/README.md <<'EOF'

# New Topic: Sentiment Analysis with Transformers

This lesson introduces fine-tuning BERT for sentiment classification.

## Theory

<!-- Add links to MS Learn or external articles -->

## Notebook

- **PyTorch:** [SentimentBERT.ipynb](SentimentBERT.ipynb)
- **TensorFlow:** [SentimentBERT_TF.ipynb](SentimentBERT_TF.ipynb)
EOF

# Copy an existing notebook as a template

cp lessons/5-NLP/18-Transformers/TransformersPyTorch.ipynb \
   lessons/5-NLP/22-NewTopic/SentimentBERT.ipynb

```

Always update the curriculum table in [[`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) around line 83 when adding or removing lessons.

## Notebook Style Guidelines for AI For Beginners Contributors

The Jupyter notebooks in AI For Beginners are the primary learning vehicle. Following these style conventions ensures beginners can execute code step-by-step without confusion.

### Notebook Best Practices

- **Clear hierarchical headings** — Use markdown headings (`#`, `##`, `###`) to structure content
- **Inline comments for every non-trivial code block** — Explain *why*, not just *what*
- **Self-contained cells** — Avoid hidden state; each cell should run independently
- **Exact dependency versions** — Pin packages in [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) to prevent version drift

The [[`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file at repository root defines all Python dependencies. When adding new libraries:

1. Add the package with explicit version to [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)
2. Test the notebook in a fresh conda environment
3. Verify execution on Binder or GitHub Codespaces

```bash

# Create fresh environment from pinned dependencies

conda env create -f environment.yml -n ai4beg-test
conda activate ai4beg-test

# Validate notebook execution

jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb

```

## Dependency Management in AI For Beginners

All Python dependencies are centralized in [[`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml). This single source of truth simplifies setup for contributors and guarantees reproducibility across platforms.

When modifying dependencies:

- **Add new packages** with explicit version constraints (e.g., `torch==2.0.0`)
- **Never commit** [`requirements.txt`](https://github.com/microsoft/AI-For-Beginners/blob/main/requirements.txt) files in lesson folders
- **Test locally** before submitting PRs

This centralized approach ensures that Binder, GitHub Codespaces, and local conda installs all produce identical environments for learners.

## Translation Workflow for AI For Beginners Localization

The AI For Beginners project supports multiple languages through a structured translation system integrated with automated CI pipelines.

### Translation Folder Structure

Place new language packs under `translations/<lang-code>/` mirroring the English lesson hierarchy exactly:

```

translations/
├── es/          # Spanish

│   └── lessons/
│       └── 5-NLP/
│           └── 22-NewTopic/
│               └── README.md   # Translated from English

├── zh/          # Chinese

└── ...

```

### Translation Best Practices

- **Preserve file names and folder layout** — The Co-op Translator CI pipeline depends on path matching
- **Translate only content files** — Do not translate code outputs or notebook execution results
- **Maintain heading structure** — Keep `#`, `##` hierarchy identical for automated TOC generation

```bash

# Example: Adding Spanish translation for a new lesson

cd translations/es/lessons/5-NLP/22-NewTopic
cp ../../../../../../lessons/5-NLP/22-NewTopic/README.md README.md

# Edit README.md with translated content, preserving all markdown structure

```

The CI system automatically detects new translation files and updates language badges in the main README.

## Quiz App Integration Standards

The Vue.js quiz application in `etc/quiz-app/` provides interactive assessments for each lesson. Changes to lesson content may require corresponding quiz updates.

### Quiz App Maintenance Steps

1. **Update JSON quiz files** in `etc/quiz-app/src/assets/quizzes/` when adding new questions
2. **Run linting** with `npm run lint` to maintain code style
3. **Local testing** with `npm run serve` before deployment

```bash
cd etc/quiz-app

# Add new question to existing quiz file

jq '.questions += [{
  "question": "What does BERT stand for?",
  "options": [
    "Bidirectional Encoder Representations from Transformers",
    "Binary Encoding Recurrent Transformer"
  ],
  "answer": 0
}]' src/assets/quizzes/nlp.json > tmp && mv tmp src/assets/quizzes/nlp.json

# Validate code style

npm run lint

# Test UI functionality locally

npm run serve

```

The quiz app deploys to Azure Static Web Apps; these validation steps prevent runtime errors in production.

## Pull Request Etiquette for AI For Beginners

Following proper PR workflow ensures efficient review and avoids merge conflicts in this high-traffic repository.

### PR Requirements

| Checklist Item | Implementation |
|----------------|----------------|
| Single logical change per PR | Don't combine typo fixes with new lessons |
| Fork-based workflow | Create feature branches on your fork, not the main repo |
| Template compliance | Use the appropriate template from [[`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) |
| CLA signature | Microsoft CLA-bot will prompt automatically; required before merge |

The [[`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) file categorizes contributions into:
- **Typo fixes** — Minimal review, fast merge
- **Lesson updates** — Technical review required
- **Translation additions** — Language consistency check

## Testing and Validation Procedures

All contributions must pass local validation before submission to prevent breaking the learning pipeline.

### Required Testing Steps

**For notebook changes:**

```bash
conda activate ai4beg
jupyter notebook

# Execute all cells in the modified notebook; expect no errors

```

**For quiz app changes:**

```bash
cd etc/quiz-app
npm run serve

# Verify UI renders correctly and new questions function

```

**For documentation changes:**
- Render markdown preview to check link validity
- Verify curriculum table updates in [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)

## Documentation Consistency Requirements

Maintain the [[`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) as the single source of truth for project navigation.

### Required README Updates

- **Curriculum table** — Add/remove entries when lesson structure changes
- **"Key Files" section** — Keep file descriptions current
- **Setup instructions** — Reflect any [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) modifications

These updates ensure learners and contributors always have accurate project orientation.

## Summary

Following these best practices for developers in AI For Beginners maintains curriculum quality and contribution velocity:

- **Repository layout** — Use `lessons/`, `examples/`, `etc/quiz-app/`, `translations/` exclusively
- **Lesson structure** — Always provide README markdown, Jupyter notebook(s), and optional lab folder
- **Notebook style** — Self-contained cells, clear comments, pinned dependencies via [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)
- **Translations** — Mirror English hierarchy exactly under `translations/<lang-code>/`
- **Quiz app** — Update JSON files, run `npm run lint` and `npm run serve` for validation
- **Pull requests** — Single logical change, fork workflow, CLA signature, template compliance
- **Testing** — Local notebook execution and quiz app verification before submission

## Frequently Asked Questions

### What folder should I use when adding a new lesson to AI For Beginners?

Place new lessons under the appropriate topic folder in `lessons/` using the existing numbering scheme (e.g., `lessons/5-NLP/22-NewTopic/`). The first number indicates the curriculum section, and the second number provides lesson ordering. Always update the curriculum table in [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) when adding lessons.

### How do I add a new Python dependency to AI For Beginners?

Add the package with exact version to the root [[`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file, not to individual lesson folders. Test your notebook in a fresh conda environment created from this file to ensure reproducibility. The centralized dependency management supports Binder, Codespaces, and local development equally.

### Can I translate AI For Beginners content into a new language?

Yes. Create a new folder under `translations/` using the standard language code (e.g., `translations/de/` for German), then mirror the exact folder structure and file names from the English `lessons/` directory. The Co-op Translator CI pipeline will automatically detect and process your translations if the structure matches precisely.

### What testing is required before submitting a pull request to AI For Beginners?

Execute all modified notebooks locally with `jupyter notebook` to verify error-free cell execution. For quiz app changes, run `npm run lint` and `npm run serve` in `etc/quiz-app/` to validate UI functionality. These steps prevent breaking the learning experience for other contributors and thousands of learners.