Users/zhaodongwang/standardize versioning

CHANGELOG.md

@@ -2,52 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [0.1.0b1] - 2025-11-14
 
 ### Added
-**Initial beta release** of Microsoft Dataverse SDK for Python
-
-**Core Client & Authentication:**
-- Core `DataverseClient` with Azure Identity authentication support
-- Secure authentication using Azure Identity credentials (Service Principal, Managed Identity, Interactive Browser)
-- TLS 1.2+ encryption for all API communications
-- Proper credential handling without exposing secrets in logs
-
-**Data Operations:**
-- Complete CRUD operations (create, read, update, delete) for Dataverse records
+- Initial beta release of Microsoft Dataverse SDK for Python
+- Core `DataverseClient` with Azure Identity authentication support (Service Principal, Managed Identity, Interactive Browser) (#1)
+- Complete CRUD operations (create, read, update, delete) for Dataverse records (#1)
 - Advanced OData query support with filtering, sorting, and expansion
-- SQL query execution via `query_sql()` method with result pagination
-- Support for batch operations and transaction handling
-- File upload capabilities for file and image columns
-
-**Table Management:**
+- SQL query execution via `query_sql()` method with result pagination (#14)
+- Bulk operations including `CreateMultiple`, `UpdateMultiple`, and `BulkDelete` (#6, #8, #34)
+- File upload capabilities for file and image columns (#17)
 - Table metadata operations (create, inspect, delete custom tables)
+- Comprehensive error handling with specific exception types (`DataverseError`, `AuthenticationError`, etc.) (#22, #24)
+- HTTP retry logic with exponential backoff for resilient operations (#72)
 
-**Reliability & Error Handling:**
-- Comprehensive error handling with specific exception types (`DataverseError`, `AuthenticationError`, etc.)
-- HTTP retry logic with exponential backoff for resilient operations
-
-**Developer Experience:**
-- Example scripts demonstrating common integration patterns
-- Complete documentation with quickstart guides and API reference
-- Modern Python packaging using `pyproject.toml` configuration
-
-**Quality Assurance:**
-- Comprehensive test suite with unit and integration tests
-- GitHub Actions CI/CD pipeline for automated testing and validation
-- Azure DevOps PR validation pipeline
-
-### Changed
-- N/A
-
-### Deprecated
-- N/A
-
-### Removed
-- N/A
-
-### Fixed
-- N/A
-
-### Security
-- N/A
+[0.1.0b3]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b2...v0.1.0b3
+[0.1.0b2]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b1...v0.1.0b2
+[0.1.0b1]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/releases/tag/v0.1.0b1

CONTRIBUTING.md

@@ -10,4 +10,103 @@ provided by the bot. You will only need to do this once across all repos using o
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Development Guidelines
+
+### Versioning
+
+This project follows open-source industry standard [Semantic Versioning](https://semver.org/):
+
+**Version Format:** `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
+
+**When to bump:**
+- **MAJOR** (e.g., 1.0.0 → 2.0.0): Breaking changes that require users to update their code
+  - Removing public methods, classes, or modules
+  - Changing method signatures (parameters, return types)
+  - Changing default behavior that breaks existing code
+  - Dropping Python version support
+
+- **MINOR** (e.g., 1.0.0 → 1.1.0): New features that are backwards-compatible
+  - Adding new public methods or classes
+  - Adding optional parameters (with defaults)
+  - New features that don't break existing code
+  - Adding Python version support
+
+- **PATCH** (e.g., 1.0.0 → 1.0.1): Bug fixes that are backwards-compatible
+  - Fixing bugs without changing the API
+  - Documentation updates
+  - Security fixes (non-breaking)
+  - Internal refactoring
+
+### Changelog
+
+We maintain a [CHANGELOG.md](CHANGELOG.md) following the [Keep a Changelog](https://keepachangelog.com/) format.
+
+**For Contributors:** You don't need to update the changelog with your PRs. Maintainers will update it at release time.
+
+**For Maintainers (Release Process):**
+
+Before each release, review merged PRs and update the changelog with:
+
+**What to include:**
+- ✅ New features (→ **Added**)
+- ✅ Changes to existing functionality (→ **Changed**)
+- ✅ Soon-to-be removed features (→ **Deprecated**)
+- ✅ Removed features (→ **Removed**)
+- ✅ Bug fixes (→ **Fixed**)
+- ✅ Security fixes (→ **Security**)
+- ❌ Internal refactoring (unless it affects performance/behavior)
+- ❌ Test-only changes
+- ❌ CI/CD changes
+- ❌ Documentation-only updates
+
+**Process:**
+1. Review all PRs merged since last release
+2. Add user-facing changes to CHANGELOG.md under appropriate categories
+3. Include PR numbers for reference (e.g., `(#123)`)
+4. Focus on **why it matters to users**, not implementation details
+
+**Adding version links to CHANGELOG.md:**
+
+After creating tags, add version comparison links at the bottom of CHANGELOG.md:
+
+```markdown
+[0.1.0b3]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b2...v0.1.0b3
+[0.1.0b2]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b1...v0.1.0b2
+[0.1.0b1]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/releases/tag/v0.1.0b1
+```
+
+### Git Tags and Releases
+
+We use git tags to mark release points and GitHub Releases for announcements.
+
+**Creating Git Tags:**
+
+Git tags should be created for every release published to PyPI:
+
+```bash
+# Create annotated tag for version X.Y.Z
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+
+# Push tag to remote
+git push origin --tags
+```
+
+**GitHub Releases:**
+
+After publishing to PyPI, create a GitHub Release based on CHANGELOG.md
+
+**Release notes format:**
+
+```markdown
+Brief summary of the release
+
+### Added
+- Feature 1 (#123)
+- Feature 2 (#124)
+
+### Fixed
+- Bug fix 1 (#125)
+- Bug fix 2 (#126)
+```