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

Merged
merged 3 commits into from
Jul 8, 2025

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.


Internal previews

📄 File 🔗 Preview link
docs/csharp/versioning.md docs/csharp/versioning

@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
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good start, but I have some comments.

@Copilot Copilot AI requested a review from BillWagner July 7, 2025 17:58
Copilot finished work on behalf of BillWagner July 7, 2025 17:58
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This LGTM now.

@BillWagner BillWagner marked this pull request as ready for review July 7, 2025 18:00
@BillWagner BillWagner requested a review from a team as a code owner July 7, 2025 18:00
@BillWagner BillWagner requested a review from IEvangelist July 7, 2025 18:00
@BillWagner BillWagner enabled auto-merge (squash) July 8, 2025 14:02
@BillWagner BillWagner merged commit 2924209 into main Jul 8, 2025
10 checks passed
@BillWagner BillWagner deleted the copilot/fix-23343 branch July 8, 2025 16:10
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
3 participants