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

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

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

# 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

# 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

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 – High-level contribution instructions, CLA details, and translation workflow.

• AGENTS.md – Project architecture overview, setup commands, and development workflow.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}