Contribution Workflow for AI For Beginners: A Step-by-Step Guide

The contribution workflow for AI For Beginners requires forking the repository, creating a descriptive branch, editing curriculum files in lessons/ or translation files in translations/, and submitting a Pull Request against the main branch to trigger automated CLA verification and maintainer review.

The Microsoft AI For Beginners repository is an open-source curriculum designed to make artificial intelligence accessible to newcomers. Understanding the proper contribution workflow ensures that fixes, translations, and improvements are efficiently reviewed and merged according to the project’s guidelines in CONTRIBUTING.md and etc/CONTRIBUTING.md.

Step-by-Step Contribution Process

The AI For Beginners project follows a standard GitHub workflow optimized for educational content and multilingual support. Each step targets specific directories and automated checks to maintain curriculum quality.

Fork the Repository and Create a Branch

Begin by creating your own copy of the repository through GitHub’s fork functionality. Once forked, clone your local copy and create a descriptive branch name that indicates your intent, such as fix-typo-lesson-3 or add-es-translation. While the documentation focuses on the editing process, branching remains the standard GitHub workflow for isolating changes.

Make Targeted Changes

The repository organizes content into two primary locations where contributors should focus their edits:

• Fixing typos or code errors – Edit the relevant Jupyter notebook or markdown file located under the lessons/ directory. These files contain the core curriculum content, including Python examples and explanatory text.
• Adding translations – Create new language folders under translations/ following the existing structure. For example, Spanish translations belong in translations/es/, mirroring the directory hierarchy found in lessons/.

Commit and Open a Pull Request

After editing, commit your changes with a clear description explaining what you changed and why. Push your branch to your fork and submit a Pull Request (PR) against the main branch of the upstream microsoft/AI-For-Beginners repository. The PR description should reference any related issues and specify whether you are correcting content or adding translations.

CLA Verification and Review

When you submit a PR, an automated CLA-bot checks whether you have signed the Microsoft Contributor License Agreement. If required, the bot labels the PR and provides signing instructions. This verification step is required only once per contributor across all Microsoft open-source repositories. After CLA confirmation, project maintainers review the changes, may request minor adjustments, and merge the PR once it meets the contribution guidelines outlined in etc/CONTRIBUTING.md.

Key Files and Directories for Contributors

Understanding the repository structure ensures you modify the correct files during the contribution workflow for AI For Beginners:

• CONTRIBUTING.md – Located in the repository root, this file contains the primary contribution guide covering how to fork, fix typos, and submit PRs.
• etc/CONTRIBUTING.md – This file provides detailed CLA instructions and lists active contribution topics requiring community help.
• lessons/ – Contains all curriculum notebooks and markdown files. When correcting technical errors or typos, target the specific lesson files within this directory.
• translations/ – Houses community-provided translations for every lesson. New language contributions must follow the established folder structure (e.g., translations/de/, translations/fr/).

Practical Examples for Common Contributions

Example 1: Fixing a Typo in a Lesson Notebook

When correcting text in the curriculum, locate the specific Jupyter notebook under lessons/ and edit the markdown cells directly. For instance, fixing a spelling error in the Perceptron lesson involves updating the notebook located at lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb:

# Before (in lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb)

# "The perceptron learnig rate is set to 0.01"

# After fixing the typo

# "The perceptron learning rate is set to 0.01"

Example 2: Adding a Spanish Translation

To add a new language translation, replicate the lessons/ directory structure under translations/ using the appropriate language code. The following commands create the necessary directory structure for a Spanish translation of the Perceptron lesson:

# Create the directory structure matching the lessons folder

mkdir -p translations/es/lessons/3-NeuralNetworks/03-Perceptron

# Copy the original notebook as a starting point

cp lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb \
   translations/es/lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb

# Open the copied notebook and translate all markdown cells into Spanish

Summary

• Fork and branch the repository before making any changes to the AI For Beginners curriculum.
• Edit files in lessons/ for typo fixes and code corrections, or create structured folders under translations/ for new language support.
• Submit PRs against the main branch and include clear commit messages describing your changes.
• Complete the Microsoft CLA when prompted by the automated bot—this is a one-time requirement for all Microsoft open-source contributions.
• Reference CONTRIBUTING.md and etc/CONTRIBUTING.md for detailed guidelines and CLA specifics before starting work.

Frequently Asked Questions

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

Yes, the Microsoft Contributor License Agreement is required for all contributions. When you open a Pull Request, an automated CLA-bot checks your status and provides signing instructions if needed. You only need to complete this step once, and it applies across all Microsoft open-source repositories.

What types of contributions does the AI For Beginners project accept?

The project welcomes corrections to typos and code errors in the lessons/ directory, as well as new translations in the translations/ folder. Major content changes or new lessons typically require discussion with maintainers first, while minor fixes and translations follow the standard contribution workflow for AI For Beginners outlined in CONTRIBUTING.md.

How do I add a new language translation to AI For Beginners?

Create a new folder under translations/ using the standard language code (e.g., translations/it/ for Italian), then mirror the directory structure found in lessons/. Copy the original notebooks or markdown files into the appropriate subdirectories and translate the content while preserving code cells and structure. Submit these changes via a Pull Request targeting the main branch.

Which branch should I target when opening a Pull Request?

All contributions must target the main branch of the upstream microsoft/AI-For-Beginners repository. Ensure your feature branch is up-to-date with main before submitting to avoid merge conflicts, and verify that your changes follow the file organization patterns documented in the repository’s contribution guidelines.

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