Pull Request Requirements for Contributing to Microsoft AI-For-Beginners

To contribute to the AI-For-Beginners repository, you must sign the Microsoft CLA, fork the repository to a feature branch, provide a descriptive PR explanation, place changes in the correct directory (lessons/ or translations/), and allow the CLA-bot to apply its label.

The microsoft/AI-For-Beginners repository maintains a streamlined, educational-focused workflow for community contributions. Understanding the specific pull request requirements for contributing ensures your changes—whether typo fixes, lesson improvements, or translations—move through review efficiently. All guidelines are documented in the repository's CONTRIBUTING.md and enforced through automated bots and maintainer review.

Sign the Microsoft Contributor License Agreement (CLA)

All contributions must be covered by the Microsoft Contributor License Agreement (CLA). According to the source code in CONTRIBUTING.md, a bot automatically checks each pull request for CLA compliance.

• You only need to sign the CLA once for all Microsoft-hosted repositories.
• If you have not signed, the bot adds a label or comment with instructions.
• No manual action is required beyond following the bot's link to complete the agreement.

Fork and Branch Workflow

The repository strictly prohibits direct pushes to the main branch. You must use the standard fork-and-branch model:

1. Fork the repository on GitHub to your personal account.
2. Clone your fork locally.
3. Create a descriptive branch name (e.g., fix-typo-lesson-3 or add-spanish-translation-module-1).
4. Commit your changes with clear messages.
5. Push the branch to your fork.
6. Open a pull request against the upstream main branch.

Provide a Clear Pull Request Description

Your pull request must contain a description that explains what you changed and why. The maintainers review dozens of educational submissions, so clarity accelerates merging.

Include the following elements:

• Summary: Describe the problem (typo, formatting error, translation update).
• File list: Enumerate the specific files modified (e.g., lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb).
• Issue references: Use closing keywords like Fixes #123 to link related issues.

Example Pull Request Template

Below is the minimal structure recommended in the contribution guidelines:

## Description

Fix a typo in the "Perceptron" lesson (Lesson 3-NeuralNetworks/03-Perceptron/Perceptron.ipynb).

## Changes

- Updated cell 12: corrected "weigths" → "weights".
- Added a comment explaining the correction.

## Motivation

The typo caused confusion for learners and broke the automatic test that checks for the word "weights".

## Related Issue

Fixes #42

Follow the Repository Structure

Changes must be placed in the appropriate location according to the file organization in AI-For-Beginners.

Lesson fixes must modify the Jupyter notebook (*.ipynb) or markdown files under lessons/. The curriculum is organized by module and topic, so match the existing hierarchy exactly.

Translations belong under translations/<language-code>/. For example, Spanish content resides in translations/es/. You must follow the existing folder naming conventions and replicate the English structure within your language directory.

General documentation updates apply to README.md or other root-level markdown files.

Validate Your Changes Locally

While optional, running existing notebooks locally is strongly recommended. The project is educational-focused, and breaking the curriculum blocks learners.

• Execute the affected notebook end-to-end to verify cell outputs.
• Check that markdown renders correctly in your local viewer.
• Confirm that relative links to images or datasets remain functional.

There are no strict linting rules for lesson content, but logical errors or broken code cells will be rejected during review.

CLA-Bot Labeling Process

After opening the PR, the CLA-bot automatically applies a label or comment to indicate CLA status. As documented in both CONTRIBUTING.md and etc/CONTRIBUTING.md, you must allow this automation to complete.

• If the label shows "CLA signed," no further action is needed.
• If the label shows "CLA required," follow the link provided by the bot to sign the agreement.
• Do not remove or manually modify bot-generated labels.

Summary

• Legal requirement: Sign the Microsoft CLA once for all Microsoft repositories.
• Workflow: Fork the repository, create a branch, and avoid direct main branch pushes.
• Documentation: Write clear PR descriptions that explain changes, list files, and reference issues.
• Placement: Put lesson fixes in lessons/, translations in translations/<lang>/, and docs in root.
• Testing: Run notebooks locally to ensure curriculum integrity, though no formal linting is enforced.
• Automation: Wait for the CLA-bot to apply labels and follow its instructions if CLA is missing.

Frequently Asked Questions

Do I need to sign the CLA for every pull request to AI-For-Beginners?

No, you only need to sign the Microsoft CLA once. The agreement covers all repositories under the Microsoft organization. The CLA-bot checks each PR automatically, but once you are listed as a CLA-signed contributor, subsequent pull requests will pass this check immediately.

Can I submit a pull request that changes multiple lessons at once?

While technically possible, it is better to submit focused pull requests that address a single concern. If you are fixing a typo that appears across multiple notebooks, one PR is acceptable. However, mixing unrelated lesson updates with translation work complicates review and may delay merging. Keep changes atomic and thematically consistent.

Are there specific formatting requirements for Jupyter notebooks?

The repository does not enforce strict linting or code style checks for educational content. However, you should ensure notebooks execute without errors, cell outputs are clear (or cleared if they contain large data dumps), and markdown follows standard conventions. When submitting translations, preserve the original notebook structure including cell types and heading hierarchy.

Where can I find the complete contribution guidelines?

The primary source is CONTRIBUTING.md in the repository root. Additional project-specific notes may appear in etc/CONTRIBUTING.md, and community behavior standards are defined in etc/CODE_OF_CONDUCT.md. Always check these files before submitting, as requirements may evolve with the curriculum.

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