# How to Contribute to Microsoft AI-For-Beginners: A Complete Guide

> Learn how to contribute to Microsoft AI-For-Beginners. Follow this guide to fork the repo, set up your environment, make changes, and submit a pull request.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-24

---

**To contribute to microsoft/AI-For-Beginners, fork the repository, create a feature branch, set up your environment using [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml), make changes to lesson notebooks or the Vue.js quiz app, and submit a pull request targeting the `main` branch.**

The **microsoft/AI-For-Beginners** repository is an open-source, 12-week curriculum that teaches fundamental AI concepts through hands-on Jupyter notebooks and a Vue.js quiz application. Whether you want to fix typos in lesson materials, add new example scripts, expand translations, or improve the interactive quiz interface, understanding how to contribute to microsoft/AI-For-Beginners ensures your changes meet the project's standards. This guide walks through the complete workflow from environment setup to pull request submission, referencing specific file paths and commands used in the repository.

## Setting Up Your Development Environment

Before modifying the curriculum, configure your local environment using either Conda or pip, and install Node.js dependencies if you plan to edit the quiz application.

### Python and Jupyter Setup

The repository supports both Conda and pip workflows. For Conda users, the [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file defines the required Python packages including TensorFlow and PyTorch:

```bash
conda env create -f environment.yml
conda activate ai4beg

```

Alternatively, install dependencies via pip using [`requirements.txt`](https://github.com/microsoft/AI-For-Beginners/blob/main/requirements.txt):

```bash
python -m pip install -r requirements.txt

```

### Vue.js Quiz Application Setup

Located in `etc/quiz-app/`, the interactive quiz is a Vue.js application defined by [`etc/quiz-app/package.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/package.json). Navigate to the directory and install dependencies:

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

```

The development server launches at `http://localhost:8080`. If you modify Vue components in `etc/quiz-app/src/**/*.vue`, run `npm run lint` to execute ESLint and auto-fix code style issues.

### Documentation Preview Setup

For contributors modifying markdown documentation, use Docsify to preview changes locally:

```bash
npm install -g docsify-cli
docsify serve .

```

The local documentation server runs at `http://localhost:3000`.

## Creating Your Contribution

The contribution workflow follows a standard fork-and-branch model targeting the `main` branch.

### Forking and Branching Strategy

First, fork the repository on GitHub, then clone your fork locally:

```bash
git clone https://github.com/<YOUR-USERNAME>/AI-For-Beginners.git
cd AI-For-Beginners

```

Create a descriptive, lower-case branch name that explains your change:

```bash
git checkout -b fix-lesson-3-perceptron

```

Valid branch names include patterns like `add-mnist-example`, `update-translation-fr`, or `add-german-translation-lesson-5`.

### Making Changes to Lessons or Code

The curriculum organizes content into modular lesson directories. Edit Jupyter notebooks in `lessons/<module>/<lesson>/<file>.ipynb`, Python examples in `examples/*.py`, or example notebooks in `examples/*.ipynb` to fix code cells, clarify explanations, or add new demonstrations. For translation work, modify files in `translations/<lang>/...` and update the index in [`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md) to reflect your additions.

### Commit Standards and Push

After verifying your changes execute without errors, commit using a clear message:

```bash
git add .
git commit -m "Add German translation for Lesson 5 (CNN basics)"
git push origin <descriptive-branch-name>

```

Navigate to your fork on GitHub and open a pull request targeting the `main` branch of `microsoft/AI-For-Beginners`. The PR template (located in [`.github/ISSUE_TEMPLATE/lesson_correction.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/.github/ISSUE_TEMPLATE/lesson_correction.yml)) reminds contributors to verify end-to-end execution, check Docsify documentation builds, and confirm translations are indexed.

## Repository Structure for Contributors

Understanding the file hierarchy helps you locate the correct targets for different contribution types.

### Core Curriculum Files

Lesson content resides in `lessons/<module>/<lesson>/` directories containing `.ipynb` notebooks and supporting Python scripts. Example scripts are stored in `examples/*.py` or `examples/*.ipynb`. When adding new examples, ensure they run end-to-end without runtime errors.

### Translation Infrastructure

Multilingual support is managed through the `translations/` directory. Each language folder mirrors the main lesson structure. Contributors must also update [`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md) to register new translations or modifications, ensuring the curriculum remains navigable for international learners.

### CI/CD and Development Environment

GitHub Actions workflows in `.github/workflows/` run automated checks including Scorecard and CodeQL analysis. Issue templates in `.github/ISSUE_TEMPLATE/` guide bug reports and lesson corrections. For a reproducible development environment, VS Code users can leverage the configuration in `.devcontainer/`.

## Testing and Validation

Validating changes before submission prevents CI failures and ensures curriculum reliability.

### Running Notebook Validation

While the repository lacks an automated test suite for Python notebooks, manually execute all cells in Jupyter to catch runtime errors. Verify that any new dependencies you introduce are added to both [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) and [`requirements.txt`](https://github.com/microsoft/AI-For-Beginners/blob/main/requirements.txt).

### Linting the Quiz Application

Before submitting changes to the Vue.js frontend, run the linting command from the quiz directory:

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

```

This command runs ESLint and automatically fixes style violations where possible.

## Summary

- **Fork the repository** and clone it locally before starting work.
- **Use [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) or [`requirements.txt`](https://github.com/microsoft/AI-For-Beginners/blob/main/requirements.txt)** to set up Python dependencies for the Jupyter curriculum.
- **Target the `main` branch** when opening pull requests.
- **Update [`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md)** when contributing translations to the `translations/` directory.
- **Run `npm run lint`** in `etc/quiz-app/` before submitting Vue.js changes.
- **Sign the Contributor License Agreement (CLA)** if prompted by the PR template.

## Frequently Asked Questions

### Do I need to sign a CLA to contribute to microsoft/AI-For-Beginners?

Yes, the repository requires a signed Contributor License Agreement for contributions that modify licensing or legal terms. The PR template automatically provides a link to the CLA signing process when required.

### Which branch should I target for pull requests?

Always target the `main` branch in the upstream `microsoft/AI-For-Beginners` repository. Create your feature branch from an up-to-date `main` branch in your fork to avoid merge conflicts.

### How do I add a new translation to the curriculum?

Add translated lesson files to a new or existing subdirectory within `translations/<lang>/`, mirroring the structure in `lessons/`. Then update [`etc/TRANSLATIONS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/TRANSLATIONS.md) to index your translation so learners can discover the localized content.

### What testing is required before submitting a PR?

Execute all modified Jupyter notebooks to verify they run without errors. If you modified the Vue.js quiz app in `etc/quiz-app/`, run `npm run lint` to ensure code quality. GitHub Actions will automatically run Scorecard and CodeQL checks after you push.