Contributing Guidelines for the AI for Beginners Repository: CLA, Workflow, and Best Practices

To contribute to the AI for Beginners repository, you must sign the Microsoft Contributor License Agreement (CLA), fork the repository, make your changes to lesson notebooks or translation files, and submit a Pull Request with a clear description of your modifications.

The AI for Beginners repository by Microsoft is an open-source educational curriculum designed to introduce newcomers to artificial intelligence through Jupyter notebooks and markdown lessons. Whether you are correcting a typo in a neural network tutorial or translating content into a new language, following the official contributing guidelines ensures your changes are reviewed and merged efficiently. All potential contributors should start by reviewing the requirements outlined in CONTRIBUTING.md at the root of the repository.

Prerequisites: The Microsoft Contributor License Agreement

Before any code or content can be merged, you must acknowledge the Microsoft Contributor License Agreement (CLA). This legal agreement grants the project rights to use your contributions and is required for all Microsoft-hosted open-source repositories.

When you submit your first Pull Request, an automated CLA-bot checks whether a CLA is on file. If required, the bot will add a comment or label to the PR with instructions on how to sign. This step is completed only once per contributor across all Microsoft repositories, meaning subsequent contributions to AI for Beginners will not require additional CLA paperwork.

Step-by-Step Contribution Workflow

The standard workflow for all contributions follows three concrete steps:

1. Fork the repository to your personal GitHub account.
2. Make the change by editing files directly in your fork (e.g., correct a typo, fix a broken code cell, or add a translation).
3. Open a Pull Request (PR) back to the main branch with a concise description of what was changed and why.

Once submitted, maintainers will review your PR for accuracy, formatting, and adherence to the contribution standards.

Contribution Types and Target Locations

Depending on the nature of your improvement, you will target specific directories within the repository structure.

Fixing Typos and Code Errors

For minor text corrections, bug fixes in Python code, or updates to external links, modify the relevant files under the lessons/ directory. This includes both Jupyter notebooks (*.ipynb) and accompanying markdown files. For example, a spelling correction in the neural networks introduction would target lessons/3-NeuralNetworks/01-Intro/Intro.ipynb.

Submitting Translations

To add support for a new language, create a folder under translations/ using the appropriate language code (e.g., translations/es/ for Spanish). Populate this folder with translated versions of the lesson files, maintaining the original directory structure. For detailed translation-specific conventions, consult etc/CONTRIBUTING.md, which supplements the main guide with localization standards.

Formatting and Documentation Fixes

Improvements to whitespace, markdown heading hierarchy, or list ordering should follow the same workflow as typo fixes. Target any content file under lessons/ or translations/ to ensure consistency across the curriculum.

Writing an Effective Pull Request

A well-structured PR description accelerates the review process. Use the following template, adapted from the repository's standards, when submitting your changes:

### Description

- Fixed typo in **lessons/3-NeuralNetworks/01-Intro/Intro.ipynb** where “perceptron” was misspelled.
- Updated the “References” cell to point to the correct URL.

### Checklist

- [x] Forked the repository
- [x] Created a new branch (`fix‑typo‑perceptron`)
- [x] Ran all cells to ensure the notebook executes without errors
- [x] Updated the changelog (`CHANGELOG.md`) if applicable

Replace the file paths and specific change details with your own modifications. Ensure all notebook cells execute without errors before submitting, as broken code blocks will block merging.

Key Files for Contributors

File	Purpose
CONTRIBUTING.md	Main contribution guide located at the repository root; contains CLA instructions and the general workflow overview.
etc/CONTRIBUTING.md	Supplemental guide specifically for translation contributions and localization details.
README.md	General project description and quick-start instructions for learners.
LICENSE	Legal terms governing the project's open-source usage.

Summary

• Sign the CLA before your first contribution; the CLA-bot will verify this automatically when you open a PR.
• Fork, edit, and PR is the standard workflow for all changes, whether fixing a typo or adding a full translation.
• Target the correct directory: use lessons/ for curriculum edits and translations/<language-code>/ for localization work.
• Reference etc/CONTRIBUTING.md for specific guidance on translation folder naming and structure.
• Provide clear PR descriptions using the provided template to describe what changed and why.

Frequently Asked Questions

Do I need to sign the CLA for every contribution to the AI for Beginners repository?

No, you only need to complete the Microsoft CLA once per GitHub account. After your initial signature is recorded, subsequent Pull Requests to this and other Microsoft repositories will automatically pass the CLA check without further action required.

Where should I place translated lesson files?

Translated content belongs in the translations/ directory at the repository root. Create a new subfolder using the standard ISO language code (e.g., translations/fr/ for French) and mirror the file structure found in the lessons/ directory. Consult etc/CONTRIBUTING.md for additional localization conventions.

Can I contribute new lessons or only fix existing content?

While the primary focus of the current contributing guidelines centers on corrections, translations, and formatting improvements, you may propose new lessons by opening an issue first to discuss the topic with maintainers. New content must align with the curriculum's beginner-focused scope and educational style before a PR is submitted.

How do I know if my PR passes the CLA check?

An automated CLA-bot monitors all incoming Pull Requests. If the check passes, you will see a status indicator on the PR page. If the CLA is missing, the bot will post a comment with a link to sign the agreement electronically. You cannot merge your contribution until this check shows a successful status.

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