How to Contribute to Microsoft AI-For-Beginners: A Complete Guide

To contribute to microsoft/AI-For-Beginners, fork the repository, create a feature branch, set up your environment using environment.yml, make changes to lesson notebooks or the Vue.js quiz app, and submit a pull request targeting the main branch.

The microsoft/AI-For-Beginners repository is an open-source, 12-week curriculum that teaches fundamental AI concepts through hands-on Jupyter notebooks and a Vue.js quiz application. Whether you want to fix typos in lesson materials, add new example scripts, expand translations, or improve the interactive quiz interface, understanding how to contribute to microsoft/AI-For-Beginners ensures your changes meet the project's standards. This guide walks through the complete workflow from environment setup to pull request submission, referencing specific file paths and commands used in the repository.

Setting Up Your Development Environment

Before modifying the curriculum, configure your local environment using either Conda or pip, and install Node.js dependencies if you plan to edit the quiz application.

Python and Jupyter Setup

The repository supports both Conda and pip workflows. For Conda users, the environment.yml file defines the required Python packages including TensorFlow and PyTorch:

conda env create -f environment.yml
conda activate ai4beg

Alternatively, install dependencies via pip using requirements.txt:

python -m pip install -r requirements.txt

Vue.js Quiz Application Setup

Located in etc/quiz-app/, the interactive quiz is a Vue.js application defined by etc/quiz-app/package.json. Navigate to the directory and install dependencies:

cd etc/quiz-app
npm install
npm run serve

The development server launches at http://localhost:8080. If you modify Vue components in etc/quiz-app/src/**/*.vue, run npm run lint to execute ESLint and auto-fix code style issues.

Documentation Preview Setup

For contributors modifying markdown documentation, use Docsify to preview changes locally:

npm install -g docsify-cli
docsify serve .

The local documentation server runs at http://localhost:3000.

Creating Your Contribution

The contribution workflow follows a standard fork-and-branch model targeting the main branch.

Forking and Branching Strategy

First, fork the repository on GitHub, then clone your fork locally:

git clone https://github.com/<YOUR-USERNAME>/AI-For-Beginners.git
cd AI-For-Beginners

Create a descriptive, lower-case branch name that explains your change:

git checkout -b fix-lesson-3-perceptron

Valid branch names include patterns like add-mnist-example, update-translation-fr, or add-german-translation-lesson-5.

Making Changes to Lessons or Code

The curriculum organizes content into modular lesson directories. Edit Jupyter notebooks in lessons/<module>/<lesson>/<file>.ipynb, Python examples in examples/*.py, or example notebooks in examples/*.ipynb to fix code cells, clarify explanations, or add new demonstrations. For translation work, modify files in translations/<lang>/... and update the index in etc/TRANSLATIONS.md to reflect your additions.

Commit Standards and Push

After verifying your changes execute without errors, commit using a clear message:

git add .
git commit -m "Add German translation for Lesson 5 (CNN basics)"
git push origin <descriptive-branch-name>

Navigate to your fork on GitHub and open a pull request targeting the main branch of microsoft/AI-For-Beginners. The PR template (located in .github/ISSUE_TEMPLATE/lesson_correction.yml) reminds contributors to verify end-to-end execution, check Docsify documentation builds, and confirm translations are indexed.

Repository Structure for Contributors

Understanding the file hierarchy helps you locate the correct targets for different contribution types.

Core Curriculum Files

Lesson content resides in lessons/<module>/<lesson>/ directories containing .ipynb notebooks and supporting Python scripts. Example scripts are stored in examples/*.py or examples/*.ipynb. When adding new examples, ensure they run end-to-end without runtime errors.

Translation Infrastructure

Multilingual support is managed through the translations/ directory. Each language folder mirrors the main lesson structure. Contributors must also update etc/TRANSLATIONS.md to register new translations or modifications, ensuring the curriculum remains navigable for international learners.

CI/CD and Development Environment

GitHub Actions workflows in .github/workflows/ run automated checks including Scorecard and CodeQL analysis. Issue templates in .github/ISSUE_TEMPLATE/ guide bug reports and lesson corrections. For a reproducible development environment, VS Code users can leverage the configuration in .devcontainer/.

Testing and Validation

Validating changes before submission prevents CI failures and ensures curriculum reliability.

Running Notebook Validation

While the repository lacks an automated test suite for Python notebooks, manually execute all cells in Jupyter to catch runtime errors. Verify that any new dependencies you introduce are added to both environment.yml and requirements.txt.

Linting the Quiz Application

Before submitting changes to the Vue.js frontend, run the linting command from the quiz directory:

cd etc/quiz-app
npm run lint

This command runs ESLint and automatically fixes style violations where possible.

Summary

• Fork the repository and clone it locally before starting work.
• Use environment.yml or requirements.txt to set up Python dependencies for the Jupyter curriculum.
• Target the main branch when opening pull requests.
• Update etc/TRANSLATIONS.md when contributing translations to the translations/ directory.
• Run npm run lint in etc/quiz-app/ before submitting Vue.js changes.
• Sign the Contributor License Agreement (CLA) if prompted by the PR template.

Frequently Asked Questions

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

Yes, the repository requires a signed Contributor License Agreement for contributions that modify licensing or legal terms. The PR template automatically provides a link to the CLA signing process when required.

Which branch should I target for pull requests?

Always target the main branch in the upstream microsoft/AI-For-Beginners repository. Create your feature branch from an up-to-date main branch in your fork to avoid merge conflicts.

How do I add a new translation to the curriculum?

Add translated lesson files to a new or existing subdirectory within translations/<lang>/, mirroring the structure in lessons/. Then update etc/TRANSLATIONS.md to index your translation so learners can discover the localized content.

What testing is required before submitting a PR?

Execute all modified Jupyter notebooks to verify they run without errors. If you modified the Vue.js quiz app in etc/quiz-app/, run npm run lint to ensure code quality. GitHub Actions will automatically run Scorecard and CodeQL checks after you push.

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