layla/auto-semver
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #31 from RightBrain-Networks/documentation/confluence

Browse Source 
Built documentation from confluence & wiki
This commit is contained in:
Derek DeJonghe 2019-12-19 17:21:12 -05:00 committed by GitHub
commit 9335f7559b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 126 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
README.md
View File

@ -1,25 +1,132 @@
# Semantic Versioning
# Automatic Semantic Versioning
This code repository extends/wraps the bumpversion library to automatically determine which type of increment (Major, Minor, Patch) to perform based on git branch names.
The tool uses the git log to determine if the last commit was a merge into a main line branch, and if it was, detect the name of the branch being merged in. If the name of the branch begins with one of the key words provided to the configuration file, a new version is produced.
# Usage
***It is important to note that the tool performs actions on a local Git repository. After completion, it will be necessary to do a `git push --tags` if a commit and tag are created***
# FULL_PATH_TO_LOCAL_REPO gives container access to repo to be versioned
# FULL_PATH_TO_SSH_FOLDER gives container access to ssh keys to be able to push repo
docker build -t semver .
docker run -v FULL_PATH_TO_LOCAL_REPO:/application_repo -v FULL_PATH_TO_SSH_FOLDER:/root/.ssh semver
## Setup
# after this finishes must go to FULL_PATH_TO_LOCAL_REPO and push yourself
git push origin develop
git push origin --tags
auto-semver is a pip installable package to install, make sure pip is installed and simply run:
# Exit Codes
Exit codes mean things
`pip install path/to/auto-semver-<version>tar.gz`
## 1
No merge found
## 2
Not a main branch
## 3
No git flow branch name found
## 128
Totally broken dont know why
## Configuration
There are two configuration files that must appear in the top directory of repository for which we want to update the version. These files are `VERSION` and `.bumpversion.cfg`.
Below is an example configuration of a `.bumpversion.cfg` file using commits:
```ini
[bumpversion]
current_version = develop
commit = False
tag = True
tag_name = {new_version}
message = Bump version: {current_version} -> {new_version}
[bumpversion:file:VERSION]
search = version=develop
replace = version={new_version}
[semver]
main_branches = master
major_branches = major
minor_branches = feature
patch_branches = hotfix, bugfix
```
### bumpversion
```ini
[bumpversion]
current_version = 1.5.2
commit = True
tag = True
tag_name = v{new_version}
message = Bump version: {current_version} -> {new_version}
```
The `current_version` represents the default version of the application contained in the repository. This must match what is in the VERSION file (example shown below). The `commit` and `tag` options determine whether to create a new Git commit and a new Git tag, respectively. The `tag_name` represents what the name of the Git tag will be, and by default is set to `{new_version}`, which will be substitued with the new version during runtime. This can be changed as desired - for example, `v{new_version}` could resolve to `v1.15.5`. The `message` option is what the message used if there is a git commit.
### File updates
```ini
[bumpversion:file:VERSION]
search = version={current_version}
replace = version={new_version}
[bumpversion:file:example_app/__init__.py]
search = version = '{current_version}'
replace = version = '{new_version}'
```
The `search` and `replace` options describe how the tool will update the version in the `VERSION` file. The format must match the format of the contents of the `VERSION` file. The `{current_version}` represents the old version of the application and the `{new_version}` represents the version after it is updated. These will be substituted with the actual values at runtime.
You can use this to update mutiple files are runtime.
### Branch Based Versioning
```ini
[semver]
main_branches = master
major_branches = major
minor_branches = feature
patch_branches = hotfix, bugfix
```
The last four options are exceptionally important - they tie in to how the branching was done in the Git repository. Each one is expected to be a comma-delimited list. The `main_branches` option represents the Git branches that feature branches will be merged into. Functionally, the tool will make commits on the currently checked out branch during runtime, which must match one of the specified branches.
In order for the tool to make a determination on how to increment the version, it looks at the most recent commit, checks to determine if it was a merge from another branch, then compares the branch name to the values listed for the options. If the merged in branch name was prefixed with one of the values for `major_branches`, the major version number is incremented and the other numbers are set to 0. If the merged in branch name was prefixed with one of the values for `minor_branche`', the minor version number is incremented and the patch number is set to 0. If the merged in branch name was prefixed with one of the values for `patch_branches`, the patch number will be incremented.
Below is an example configuration in the VERSION file:
```VERSION
version=1.15.5
```
The value for `version` represents the current version of the application, and should match the current_version in the `.bumpversion.cfg`.
## Usage
<a name="semver"></a>
#### semver
The `semver` command runs auto-semver in the current working directory.
The exit code of auto-semver determines the output.
**Exit codes**:
|Value|Meaning|
|---|---|
|0|Successfully ran auto-semver|
|1|No merge found|
|2|Not a main branch|
|3|No git flow branch name found|
|128|Unknown error occured|
#### Flags
`-n`
Does not push after versioning.
`-h`
Shows helps screen.
<a name="semver_get_version"></a>
### semver_get_version
The `semver_get_version` command returns the version number if the `semver` command exited `0`. If `semver` exited anything else, `semver_get_version` will return the branch name.
#### Flags
`-d`
Replaces `/` with `.` in branch names. For example, `feature/test` becomes `feature.test`
### Commitless Versioning
Because auto-semver keeps track of the version by looking at the latest git tag, instead of commiting versioned values to the repository, files can be updated upon release.