Skip to content

Latest commit

 

History

History
58 lines (29 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

58 lines (29 loc) · 4.15 KB
Raw

Contributing to veda-backend

Collaboration

This project generally follows the git-flow branching model.

Branching

  • All features, fixes, and improvements are committed in branches based on the develop protected branch.

  • As soon as manual smoke testing has been executed in the development environment, a new pull request is used to broadcast and get wider approval from maintainers for the new work before merging develop into the protected main branch.

Pull request conventions

  • Pull requests should explain what is changed, why, and how the change can be tested.

  • Pull request titles must adhere to the conventional commits specification. This is enforced using action-semantic-pull-request.

  • Successful automated pull request linting, testing, and deployment checks are required.

  • Deleting the feature branch after merging is recommended but not enforced.

Conventional commits and semantic versioning

Conventional Commits v1.0.0 Specification compliant commit messages and pull request titles allow us to systematically generate the next Semantic Versioning 2.0.0 MAJOR.MINOR.PATCH version. Conventional commits are strongly recommended for all changes, but are only required for pull request titles (and for the single commit in a pull request that only includes one commit). We use python-semantic-release to infer version steps from conventional commit messages.

Conventional commits and MAJOR.MINOR.PATCH semantic version

This project currently implements python-semantic-release defaults in pyproject.toml where custom versioning strategy configuration can be added. Local installation of python-semantic-release is optional.

  • Major version increments are required when breaking changes are introduced. Breaking changes are indicated with a ! in a conventional commit message such as feat(database)!: (example).

  • Minor version increments are applied on feature changes, these commit messages are prefixed with feat: or feat(scope):.

  • Patch version increments are applied for fixes and performance tuning by using the fix: and perf: commit prefixes with or without a defined (scope).

  • Chores, documentation, and other changes that do not cause version changes including "chore", "ci", "docs", "style", "refactor", and "test" are configured in pyproject.toml.

Automated releases

Release branch groups are configured in pyproject.toml. Merges in to the develop branch generate pre release candidates. When the develop branch is merged into main, new releases are generated by dropping the rc.<increment> from the release candidate version. Release changes are generated from conventional commit messages.

Note: Release versions are managed with git tags only to avoid managing an admin token for the release action.

Tips and tools

Commitizen git prompter

A command line tool with prompts for formatted conventional commit messages.

Fix missed conventional commit messages

Empty commit messages are an easy way to add to the conventional commit history used for semantic versioning. git commit --allow-empty -m 'feat(api)!: introduced breaking path change in xyz endpoint'

Squased merges (if you must)

If it is necessary to squash commit history on merging, make sure that the merge message is an appropriate conventional commit message to ensure that automated release versioning will be applied properly. The project is configured to default the squash commit message to the pull request title.