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

> Learn how to contribute to the AI for Beginners repository. Follow our guidelines on CLA, workflow, and best practices to submit your changes effectively.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: best-practices
- Published: 2026-08-22

---

**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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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:

```markdown

### 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`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) | Main contribution guide located at the repository root; contains CLA instructions and the general workflow overview. |
| [`etc/CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/etc/CONTRIBUTING.md) | Supplemental guide specifically for translation contributions and localization details. |
| [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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.