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

> Learn how to contribute to AI-For-Beginners easily. Fork the repo, edit lessons or translations, and submit your pull request to collaborate on this open-source AI project.

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

---

**To contribute to AI-For-Beginners, fork the repository, create a feature branch, edit content in `lessons/` or `translations/`, verify notebooks run end-to-end, and submit a pull request that passes the Microsoft CLA check and automated CI tests.**

The **microsoft/AI-For-Beginners** repository is an open-source educational resource that combines Jupyter notebooks, a Vue.js quiz application, and multilingual translations. Whether you are fixing typos in lesson content, adding a new language translation, or improving the interactive quiz interface, this guide outlines the exact workflow and file structure you need to follow to contribute successfully.

## Understanding the Three Contribution Pillars

The repository organizes contributions into three distinct areas. Each follows the same pull request workflow but targets different directories.

### Lesson Content and Notebook Fixes

The `lessons/` directory contains 24 instructional notebooks covering AI fundamentals. Contributors can correct typos, update code snippets, improve explanations, or fix broken links in these `.ipynb` files. Each notebook is self-contained, with cells that execute independently, making local testing straightforward.

### Multilingual Translations

All language versions live under `translations/`. To add a new language or update an existing one, mirror the English folder structure (e.g., `translations/es/` for Spanish). You must translate the markdown content, quiz strings in `src/assets/translations/`, and update the language-specific [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) to reflect translation status.

### Quiz Application Enhancements

The interactive quiz resides in `etc/quiz-app/`. This Vue 2.x application accepts improvements to components, styling, or internationalization. The source follows a classic component layout under `src/components/`, with ESLint configuration defined in [`package.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/package.json).

## Step-by-Step Contribution Workflow

All contributions to AI-For-Beginners require adherence to the Microsoft Contributor License Agreement (CLA). When you open a pull request, the CLA-bot automatically checks whether you have signed the agreement and annotates the PR accordingly.

1. **Fork the repository** on GitHub to create your own copy.

2. **Create a new branch** with a descriptive name (e.g., `fix-typo-perceptron` or `add-spanish-translation`).

3. **Make your changes** to notebooks, markdown files, or translation files.

4. **Verify notebook execution** by running the modified notebooks end-to-end using `jupyter notebook` to ensure all cells execute without errors.

5. **Commit and push** your changes using `git add`, `git commit -m "descriptive message"`, and `git push origin <branch-name>`.

6. **Open a pull request** targeting the `main` branch with a clear title and description.

7. **Complete CLA verification** if prompted by the CLA-bot.

8. **Pass CI checks** which include linting (`npm run lint` for the quiz app) and notebook execution validation.

9. **Await maintainer review** and merge upon approval.

## Repository Architecture Overview

Understanding the file structure helps you navigate the codebase efficiently.

- **`lessons/`** – Hierarchical folders (`0-course-setup/`, `1-Intro/`, etc.) containing Jupyter notebooks and supporting data files.

- **`etc/quiz-app/`** – Vue 2.x application with source code in `src/components/` and `src/assets/`. The production build outputs to `etc/quiz-app/dist/`.

- **`translations/`** – Mirrors the English content structure for each supported language.

- **`.github/workflows/`** – GitHub Actions pipelines that enforce CLA compliance, run notebook tests, and lint the Vue application.

## Practical Contribution Examples

### Fix a Typo in a Notebook

```bash

# 1. Fork & clone

git clone https://github.com/<your-username>/AI-For-Beginners.git
cd AI-For-Beginners

# 2. Create a branch

git checkout -b fix-typo-perceptron

# 3. Edit the notebook (e.g., lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb)

#    Open with Jupyter Lab and correct the typo

# 4. Verify the notebook runs

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

# 5. Commit & push

git add lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb
git commit -m "Fix typo in Perceptron notebook"
git push origin fix-typo-perceptron

# 6. Open a PR on GitHub

```

### Add a New Spanish Translation

```bash

# 1. Create a branch for the translation

git checkout -b add-spanish-translation

# 2. Copy the English folder structure

cp -r translations/en/ translations/es/

# 3. Translate markdown files under translations/es/

#    e.g., lessons/1-Intro/01-WhatIsAI/WhatIsAI.md

# 4. Update the translation index

#    Edit translations/es/README.md to reflect status

# 5. Commit & push

git add translations/es/
git commit -m "Add Spanish translation for introductory lessons"
git push origin add-spanish-translation

# 6. Open a PR

```

### Improve the Quiz UI

```bash
cd etc/quiz-app

# Install dependencies

npm install

# Start the development server

npm run serve

# Edit a component, e.g., src/components/Quiz.vue

# Run lint to auto-fix style issues

npm run lint

# Build the production bundle

npm run build

# Commit & push the changes

git add src/components/Quiz.vue
git commit -m "Refactor Quiz component layout"
git push origin <branch-name>

```

## Key Contribution Files

These files define the contribution standards and automation:

- **[`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)** – High-level contribution instructions, CLA details, and translation workflow.

- **[`AGENTS.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/AGENTS.md)** – Project architecture overview, setup commands, and development workflow.

- **[`etc/quiz-app/package.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/quiz-app/package.json)** – Defines Vue dependencies and ESLint configuration.

- **`.github/workflows/`** – CI pipelines for CLA enforcement, notebook testing, and Vue app linting.

## Summary

- **AI-For-Beginners** accepts contributions through three main channels: lesson notebooks, translations, and the Vue.js quiz app.
- All contributions require signing the **Microsoft Contributor License Agreement (CLA)**, verified automatically by the CLA-bot.
- **Always verify notebook execution** locally before submitting changes to the `lessons/` directory.
- **Translations** must mirror the English folder structure under `translations/<language-code>/`.
- The **quiz app** uses Vue 2.x with ESLint; run `npm run lint` before committing UI changes.
- Pull requests must target the `main` branch and pass automated CI checks including notebook execution and linting.

## Frequently Asked Questions

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

Yes. The repository uses the Microsoft Contributor License Agreement (CLA) to ensure all contributions can be legally merged. When you open a pull request, the CLA-bot automatically checks your status and will prompt you to sign the agreement if you have not already done so.

### How do I test notebook changes before submitting a PR?

Open the modified `.ipynb` file using Jupyter Lab or Jupyter Notebook and execute all cells end-to-end. The CI pipeline also runs notebook execution checks, so verifying locally prevents automated build failures. Ensure all code cells run without errors and outputs render correctly.

### What is the process for adding a new language translation?

Create a new folder under `translations/` using the appropriate language code (e.g., `translations/de/` for German). Copy the English folder structure from `translations/en/` and translate the markdown content, quiz strings in `src/assets/translations/`, and update the language-specific [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md). Submit these changes as a single pull request targeting the `main` branch.

### How are changes to the quiz app validated?

The quiz app in `etc/quiz-app/` uses GitHub Actions to run `npm run lint` for style enforcement and `npm run build` to verify the production bundle compiles successfully. Ensure your changes pass linting locally before pushing, and verify the app builds without errors using the Vue CLI development server (`npm run serve`).