Lazy loaded image
技术分享
Git and Code Versioning Standards for Spring Boot Microservices
字数 960阅读时长≈ 3 分钟
2025-5-13
2025-5-13
type
status
date
slug
summary
tags
category
icon
password
## Git and Code Versioning Standards for Spring Boot Microservices
  • *Introduction**
This document outlines the recommended standards for Git version control and code versioning practices for Spring Boot microservice development. Adhering to these standards will help ensure consistency, facilitate collaboration, improve code quality, and streamline the CI/CD pipeline.
  • *1. Repository Strategy**
  • *Polyrepo Model**: Each microservice should reside in its own dedicated Git repository. This promotes modularity, independent lifecycles, and clearer ownership, aligning with microservice architecture principles.
  • *README**: Every repository must include a comprehensive `README.md` file. This file should detail:
* The purpose and functionality of the microservice.
* Instructions for building, configuring, and running the service locally.
* Key dependencies and environment variables.
* An overview of the API endpoints (or a link to Swagger/OpenAPI documentation).
* Contact information for the development team or primary maintainers.
  • *2. Branching Strategy**
A consistent branching strategy is crucial. We recommend a model that balances agility with stability, inspired by common industry practices:
  • *`main` branch (or `master`)**:
* This branch contains the latest stable, production-ready code.
* Direct commits to `main` are strictly prohibited.
* Merges into `main` should only occur from `release` branches after successful testing and validation, or from `hotfix` branches.
  • *`develop` branch**:
* This branch serves as the primary integration branch for ongoing development and features.
* Feature branches are created from `develop` and merged back into `develop` upon completion and review.
* This branch should always represent a state that is ready for testing and potential release.
  • *Feature branches (`feature/<feature-name>` or `feature/<JIRA-ID>-<description>`)**:
* Created from the `develop` branch for developing new features, enhancements, or non-critical bug fixes.
* Example: `feature/USER-AUTH-MODULE`, `feature/PROJ-123-implement-search-functionality`.
* These branches should be short-lived and focused on a single piece of functionality.
* Once development is complete, tested, and reviewed, the feature branch is merged into `develop` (typically via a Pull Request).
  • *Release branches (`release/vX.Y.Z`)**:
* Created from the `develop` branch when preparing for a new production release.
* Example: `release/v1.2.0`.
* This branch is used for final regression testing, minor bug fixes specific to the release, and final updates to documentation or configuration.
* No new features should be added to a release branch.
* Once the release is validated, this branch is merged into `main` (and tagged) and also back into `develop` to ensure any fixes are incorporated there.
  • *Hotfix branches (`hotfix/<JIRA-ID>-<description>` or `hotfix/vX.Y.Z-patch`)**:
* Created from the `main` branch to address urgent, critical bugs discovered in the production environment.
* Example: `hotfix/PROJ-456-critical-security-patch`.
* After the fix is implemented and thoroughly tested, it is merged directly into `main` (and tagged) and also into `develop` (and any active release branches) to ensure the fix is propagated.
  • *3. Committing and Merging Practices**
  • *Commit Messages**:
* Commit messages should be clear, concise, and descriptive, following a consistent style. The [Conventional Commits](https://www.conventionalcommits.org/) specification is highly recommended.
* Example: `feat: Add user profile editing feature`, `fix: Correct calculation error in payment module`, `docs: Update API documentation for endpoint X`.
* Include issue tracker IDs (e.g., JIRA ticket numbers) in commit messages where applicable.
  • *Atomic Commits**: Each commit should represent a single logical change. Avoid bundling unrelated changes into one commit.
  • *Pull Requests (PRs)**:
* All code changes intended for integration into `develop` or `main` branches (from feature, release, or hotfix branches) must be submitted via a Pull Request.
* PRs should have a clear title and a detailed description of the changes, the problem solved, and any relevant context.
  • *Code Reviews**:
* PRs must be reviewed by at least one other designated team member (e.g., senior developer, tech lead) before merging.
* Reviewers should check for correctness, adherence to coding standards, performance implications, security vulnerabilities, and adequacy of tests.
  • *Automated Checks**: Integrate automated checks into the PR process, including:
* Static code analysis (e.g., SonarQube, Checkstyle).
* Unit and integration tests execution.
* Security vulnerability scanning.
A PR should only be mergeable if all automated checks pass.
  • *4. Versioning Strategy**
  • *Semantic Versioning (SemVer)**: All microservice releases should strictly follow Semantic Versioning (`MAJOR.MINOR.PATCH`).
* `MAJOR` version increment for incompatible API changes.
* `MINOR` version increment for adding functionality in a backward-compatible manner.
* `PATCH` version increment for backward-compatible bug fixes.
  • *Git Tags**:
* Every release merged into the `main` branch must be tagged with its unique SemVer version (e.g., `v1.0.0`, `v1.0.1`).
* Tags provide stable reference points for released versions.
  • *API Versioning**:
* For APIs exposed by microservices, a clear versioning strategy is essential, especially when introducing breaking changes. Common approaches include versioning in the URL path (e.g., `/api/v1/resource`, `/api/v2/resource`) or using custom HTTP headers.
* API changes should be clearly documented, and a deprecation policy for older API versions should be established if necessary.
  • *5. Automation (CI/CD)**
  • *Continuous Integration (CI)**: Implement a robust CI pipeline that automatically builds, tests (unit, integration, and potentially end-to-end tests), and scans code for vulnerabilities upon every commit to any branch, especially before merging PRs.
  • *Continuous Delivery/Deployment (CD)**:
* Automate the deployment process. Merges to the `develop` branch could trigger deployment to a staging or UAT environment.
* Merges to the `main` branch (representing a release) should trigger deployment to the production environment, potentially with a manual approval step if required by organizational policy.
  • *Rollback Strategy**: Ensure that the CD pipeline includes a reliable rollback mechanism to quickly revert to a previous stable version in case of deployment failures or critical issues post-deployment.
  • *6. Documentation**
  • *Changelogs**: Maintain a `CHANGELOG.md` file at the root of each microservice repository. This file should be updated with every release, detailing new features, bug fixes, performance improvements, and any breaking changes. This can often be automated or semi-automated based on commit messages if a consistent format is used.
  • *API Documentation**: Ensure that API documentation (e.g., using OpenAPI/Swagger specifications) is comprehensive, accurate, and kept in sync with the code. This documentation should be easily accessible to consumers of the microservice.
  • *Code Comments**: Encourage developers to write clear and meaningful comments in the code, especially for complex logic or non-obvious decisions. However, well-structured code and good naming conventions should be the primary means of conveying intent.
By adhering to these standards, development teams can improve collaboration, maintain high code quality, reduce the risk of errors, and ensure more stable and predictable releases of Spring Boot microservices.
上一篇
AI 辅助开发指南
下一篇
Get name prompt