AI For Beginners Versioning Guidelines: How Releases Are Managed

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, 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

You can inspect the current version directly from the repository:

# 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 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:

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:

# 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	Pins exact package versions for reproducible training environments
CONTRIBUTING.md	Documents the contribution workflow and version bump process
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 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, 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 section, summarizing added lessons, updated notebooks, and dependency changes.

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