Skip to content

Add concrete examples to semantic versioning documentation for beginners #47092

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jul 3, 2025

This PR enhances the semantic versioning section in the C# versioning guide to better serve beginner developers by adding concrete, practical examples.

Problem

The current semantic versioning documentation was too abstract for beginners. A grade 8 student learning C# reported confusion about:

  • What constitutes "incompatible API changes" (MAJOR version increments)
  • What "backwards-compatible manner" means (MINOR vs PATCH increments)
  • When to increment each version number type

Solution

Added a new subsection "Understanding version increments with examples" that provides:

MAJOR version examples (incompatible API changes):

  • Removing public methods or properties
  • Changing method signatures by adding required parameters
  • Changing method behavior in breaking ways

MINOR version examples (backwards-compatible functionality):

  • Adding new public methods or properties
  • Adding optional parameters to existing methods
  • Adding new method overloads

PATCH version examples (backwards-compatible bug fixes):

  • Fixing bugs in existing method implementations
  • Performance improvements that don't change the API

Each example includes clear "before and after" code samples showing the specific changes and version numbers, making it easy for beginners to understand the practical application of semantic versioning rules.

Key principle added

The key principle is: if existing code can use your new version without any changes, it's a MINOR or PATCH update. If existing code needs to be modified to work with your new version, it's a MAJOR update.

This simple rule helps developers quickly determine the appropriate version increment.

Fixes #23343.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@Copilot Copilot AI changed the title [WIP] Semantic Versioning Add concrete examples to semantic versioning documentation for beginners Jul 3, 2025
@Copilot Copilot AI requested a review from BillWagner July 3, 2025 16:16
Copilot finished work on behalf of BillWagner July 3, 2025 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Semantic Versioning
2 participants