# AI For Beginners Versioning Guidelines: How Releases Are Managed

> Learn AI For Beginners versioning guidelines. Discover how releases are managed using semantic versioning for compatibility and reproducible learning.

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

---

**The AI For Beginners repository follows semantic versioning (MAJOR.MINOR.PATCH) with strict rules for tagging releases, maintaining backwards compatibility, and ensuring reproducible learning environments.**

This guide breaks down the complete versioning policy used by Microsoft's open-source AI curriculum. Understanding these guidelines helps contributors submit properly scoped changes and helps learners track which version of the materials they are using.

## Semantic Versioning Structure for AI For Beginners

The repository uses standard **semantic versioning** to communicate the scope of changes between releases. Every version tag follows the `MAJOR.MINOR.PATCH` format.

| Version Component | When It Bumps | Example Scenario |
|---|---|---|
| **MAJOR** | Breaking changes to lesson structure or curriculum scope | Reorganizing the entire course flow or removing deprecated lessons |
| **MINOR** | New lessons, translations, or features without disruption | Adding a chapter on diffusion models or a Spanish translation |
| **PATCH** | Bug fixes, typo corrections, or broken link repairs | Fixing a dead URL in lesson 3 or a typo in a code comment |

In [`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md), maintainers document that contributors must **never** modify version tags directly. Instead, contributors open Pull Requests targeting content changes, and maintainers apply the appropriate version bump after merge.

## Release Notes and Documentation

Every tagged release includes a **concise changelog** published to the GitHub Releases section. These release notes summarize:

- Newly added lessons or translations
- Updated Jupyter notebooks
- Dependency version changes in [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml)

You can inspect the current version directly from the repository:

```bash

# Check the current version tag of the repository

git describe --tags

```

## Environment Consistency with Pinned Dependencies

Reproducibility is critical for educational content. The [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file at the repository root pins **exact package versions** for core ML frameworks including TensorFlow, PyTorch, and Keras.

When a new **minor version** upgrades a dependency, the environment file is updated accordingly. This ensures learners executing notebooks six months apart encounter identical behavior.

## Lesson-Level Version Tracking

Individual Jupyter notebooks embed the library version they were authored against. For example, notebooks include checks like:

```python
import tensorflow as tf
print(tf.__version__)

```

This pattern helps learners verify their local environment matches the intended framework version for that specific lesson.

## Creating a New Release (Maintainers Only)

The following workflow shows how repository maintainers publish a new minor release after adding content:

```bash

# Create a new minor release after adding a lesson

git checkout main
git pull origin main

# update environment.yml, notebooks, etc.

git commit -am "Add lesson X and bump dependencies"
git tag -a v1.3.0 -m "Minor release: new lesson and updated deps"
git push origin v1.3.0

```

After pushing the tag, maintainers publish a GitHub Release containing the changelog and documentation links.

## Backwards Compatibility Requirements

**Minor and patch releases must remain compatible with older notebooks.** This rule is strictly enforced: if a dependency upgrade or structural change would break existing examples, the release must be tagged as a new **major version** instead.

This policy protects learners who began the curriculum under `v1.2.0` from having their partially completed notebooks fail unexpectedly when `v1.3.0` releases.

## Key Files Governing Versioning

| File | Purpose |
|---|---|
| [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) | Pins exact package versions for reproducible training environments |
| [`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) | Documents the contribution workflow and version bump process |
| [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) | Contains release information and current version notices |
| GitHub Releases | Hosts tagged versions, changelogs, and release artifacts |

## Summary

- AI For Beginners uses **semantic versioning** (`MAJOR.MINOR.PATCH`) where major bumps indicate breaking structural changes
- **Contributors do not modify version tags** — they submit PRs and maintainers handle versioning post-merge
- The [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file pins exact dependency versions to ensure **reproducible environments** across releases
- **Individual notebooks embed library versions** to help learners verify their setup matches lesson requirements
- **Backwards compatibility is mandatory** for minor and patch releases; breaking changes require major version bumps

## Frequently Asked Questions

### How do I know which version of AI For Beginners I am using?

Run `git describe --tags` in your local repository clone to see the current version tag. You can also check the GitHub Releases page to compare against the latest published release.

### Can I contribute a fix that bumps the version number?

No. According to [`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md), contributors should **never** modify version tags directly. Submit your changes via Pull Request, and maintainers will apply the appropriate version bump after reviewing and merging your contribution.

### What happens if a dependency update breaks existing notebooks?

Breaking changes to existing notebooks require a **major version bump** (e.g., `v1.x.x` to `v2.0.0`). Minor and patch releases must maintain backwards compatibility with all previously published lessons.

### Where can I find the changelog for a specific release?

Each tagged release includes a changelog in the [GitHub Releases](https://github.com/microsoft/AI-For-Beginners/releases) section, summarizing added lessons, updated notebooks, and dependency changes.