Explicit, strict and automatic project version management based on semantic versioning.
Getting started
End users
An end user of the project is a developer who develops a project that needs versioning such as API or libraries.
Semantic versioning
There is the semantic versioning. To make a long story short, it is versioning specification with major, minor and patch numbers telling us what the current version of a project is and how to react on its new versions' updates. Example of the project version following semantic versioning is 1.3.12 where the first digit is major number, the second digit is minor number, and the third digit is patch number.
These are the rules of increasing chose numbers:
-
Increase major version when you make incompatible API changes.
Before changes: 1.3.12 After changes: 2.0.0
-
Increase minor version when you add functionality in a backwards compatible manner.
Before changes: 1.3.12 After changes: 1.4.0
-
Increase match version when you make backwards compatible bug fixes.
Before changes: 1.3.12 After changes: 1.3.13
You have probably seen semantic versioning in your programming language's packages such as JavaScript's axios (e.g. version 0.24.0) or Python requests (e.g. version 2.27.1).
Project version
project version is just a set of principles and automations for developers to maintain their projects. project version requires having a file named .project-version in the root directory containing a project version. With this file, developers declare single source of project version's truth.
If needed, project version must be reused only from the file in. On how to reuse it, check motivation chapter chapter below.
Motivation
There are the following principles and practices project version brings to you:
-
There may be situations when you deployed the new version of an application but do not have deployment logs, or you deployed the new version of a application but logs tell nothing, or do not have
Gitinformation. In all the cases it may be useful to enter your application's runtime and check file.project-versionto know the exact version which is related to the codebase.$ cat .project-version 1.3.12
-
Instead of using
Gitcommit SHA or its short version forDockerimages, you can use a project version.$ docker build --tag facebook/react:v$(cat .project-version) -f Dockerfile .
-
Instead of using
Gitcommit SHA or its short version forGitHubrelease version number, you can use a project version.on: push: branches: - master jobs: release: runs-on: [ubuntu-latest] outputs: project_version: ${{ steps.get_project_version.outputs.project_version }} steps: - uses: actions/[email protected] - name: Create Release uses: actions/[email protected] with: tag_name: $(cat .project-version) release_name: Release v$(cat .project-version)
-
Instead of supporting package version (
Python package,GemorJAR) in a dedicated file, you can automatically use a project version.Python packagewith itssetup.pyfor building packages is illustrated below:with open('.project-version', 'r') as project_version_file: project_version = project_version_file.read().strip() setup( version=project_version, name='project-version', ... )
-
In case you manage an infrastructure as a code (e.g.
Kubernetes), you may face challenges of supporting multiple major version of your project (e.g.HTTP API). Without automation, you should create new major version configurations manually.Let us consider the example where you have API's first version deployment configurations:
$ ls deployment/ ├── deployment │ ├── v1 │ │ └── deployment.yaml │ │ └── ingress.yaml │ │ └── service.yaml $ cat /deployment/v1/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: namespace: api-v1
When it is time to create API's second version, you can simply copy previous version configurations and substitute
v1tov2.$ echo .project-version 2.0.0 $ export PROJECT_PREVIOUS_MAJOR_VERSION=$(($cat .project-version)-1); echo $PROJECT_MAJOR_VERSION 1 $ export PROJECT_MAJOR_VERSION=$(cut -d '.' -f 1 <<< "$(cat .project-version)"); echo $PROJECT_PREVIOUS_MAJOR_VERSION 2 $ cp -r deployment/v$PROJECT_PREVIOUS_MAJOR_VERSION deployment/v$PROJECT_MAJOR_VERSION $ find deployment/ -type f -exec sed -i \ 's/namespace: v$PROJECT_PREVIOUS_MAJOR_VERSION/namespace: v$PROJECT_MAJOR_VERSION/g' {} +
After, you automatically get deployment configurations for the new version:
$ ls deployment/ ├── deployment │ ├── v1 │ │ └── deployment.yaml │ │ └── ingress.yaml │ │ └── service.yaml │ ├── v2 │ │ └── deployment.yaml │ │ └── ingress.yaml │ │ └── service.yaml $ cat /deployment/v2/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: namespace: api-v2
Yes, all this approaches requires for a project version always be up-to-date and never corrupted. Luckly, those cases are covered with a set of automation scripts (command line interface) written in Python that helps to manage a project version. Discover them by checking usage chapter below.
Installation
Install using pip3:
$ pip3 install project-version
Usage
This chapter describes a set of automation scripts (command line interface) that help to manage a project version.
Version
Get the version of the package — project-version --version:
$ project-version --version
project-version, version 0.1.0
Help
Get the detailed description of all supported commands by the package — project-version --help:
$ project-version --help
Usage: project-version [OPTIONS] COMMAND [ARGS]...
Project version command-line interface.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
check Check whether specified project version is increased properly.
Check
Check whether specified project version is increased properly — project-version check.
Parameters:
| Argument | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | String | Yes | One of: GitHub. |
A provider of hosting for software development and version control name. |
| organization | String | Yes | - | The provider's organization name. |
| repository | String | Yes | - | The provider's repository name. |
| base-branch | String | Yes | - | A branch to compare a project version with. Usually, a default branch. |
| head-branch | String | Yes | - | A branch to get its project version for comparison. Usually, a feature branch. |
| access-token | String | Yes | - | The provider's API access token. |
Example of usage:
$ project-version check \
--provider=GitHub \
--organization=facebook \
--repository=react \
--base-branch=master \
--head-branch=map-children-components \
--access-token=ghp_0TI5LBBLNyKlT5Lv8eR6EIOB0hkopMqz5LWjNyKlZ1
Examples
Example of checking a project version on a pull request workflow:
---
name: Pull request workflow
on:
pull_request_target:
branches:
- master
jobs:
check-project-version:
runs-on: [ubuntu-latest]
steps:
- uses: actions/[email protected]
- name: Install project version
run: pip3 install project-version
- name: Check a project version
run: |
project-version check \
--provider=GitHub \
--organization=facebook \
--repository=react \
--base-branch=master \
--head-branch=map-children-components \
--access-token=${{ secrets.GIT_HUB_ACCESS_TOKEN }}
Example of bumping a project version on a pull request workflow:
---
name: Pull request workflow
on:
pull_request_target:
branches:
- master
jobs:
check-project-version:
runs-on: [ubuntu-latest]
steps:
- uses: actions/[email protected]
- name: Install project version
run: pip3 install project-version
- name: Bump project version if it is non-human pull request
if: ${{ github.actor == 'dependabot[bot]' || github.actor == 'facebook-bot' }}
run: |
project-version bump \
--provider=GitHub \
--organization=facebook \
--repository=react \
--base-branch=master \
--head-branch=map-children-components \
--access-token=${{ secrets.GIT_HUB_ACCESS_TOKEN }}
Example of making a release based on a project version:
---
name: Master workflow
on:
push:
branches:
- master
jobs:
release:
runs-on: [ubuntu-latest]
outputs:
project_version: ${{ steps.get_project_version.outputs.project_version }}
steps:
- uses: actions/[email protected]
- name: Install project version
run: pip3 install project-version
- name: Get a version of the project
id: get_project_version
run: echo "::set-output name=project_version::$(cat .project-version)"
- name: Release
run: |
project-version release \
--provider=GitHub \
--organization=facebook \
--repository=react \
--branch=master \
--version=${{ steps.get_project_version.outputs.project_version }}
Contributing
Clone the project and install requirements:
$ git clone [email protected]:dmytrostriletskyi/accessify.git && cd accessify
$ make install-requirements
After changes, ensure the code quality remains the same:
$ make check-requirements-safety
$ make check-code-complexity
$ make check-code-quality
$ make check-yaml-standards
If you are new for the contribution, please read:
- About pull requests — https://help.github.com/en/articles/about-pull-requests
- Create a pull request — https://help.github.com/en/articles/creating-a-pull-request-from-a-fork
- The beginners guide to contributing — https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/
15.6k Jan 2, 2023
809 Dec 28, 2022
1.9k Dec 26, 2022
1 Sep 1, 2022
2 Oct 25, 2021
1 Jan 10, 2022
2 Jan 17, 2022
1 Dec 23, 2021
0 Feb 14, 2022
6 Jan 07, 2023
3 Oct 02, 2021
23.2k Dec 29, 2022
71 Oct 28, 2022
1 Nov 10, 2021
38 Nov 24, 2022
24.5k Jan 09, 2023
2 Dec 02, 2021
1 Dec 19, 2021
3 Apr 03, 2022
1.5k Jan 07, 2023
3 May 03, 2022
946 Dec 30, 2022
243 Dec 20, 2022
1 Nov 08, 2021
2 Nov 25, 2021
3 Jan 14, 2022
29 Dec 19, 2022
1.5k Jan 06, 2023