Built documentation from confluence & wiki
This commit is contained in:
parent
1726d247af
commit
a71b96c364
146
README.md
146
README.md
@ -1,25 +1,133 @@
|
||||
# Semantic Versioning
|
||||
# Automatic Semantic Versioning
|
||||
|
||||
The automated semantic version solution (auto-semver) does three things:
|
||||
|
||||
# Usage
|
||||
1. It increments the version of the chosen repository based on rules in the chosen configuration and updates the VERSION file with the new version.
|
||||
2. A new Git commit _can_ be made to the chosen repository
|
||||
3. A new Git tag with the version is created and linked to the versioned commit.
|
||||
|
||||
# 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
|
||||
```txt
|
||||
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
|
||||
```
|
||||
|
||||
# after this finishes must go to FULL_PATH_TO_LOCAL_REPO and push yourself
|
||||
git push origin develop
|
||||
git push origin --tags
|
||||
## Setup
|
||||
|
||||
# Exit Codes
|
||||
Exit codes mean things
|
||||
auto-semver is a pip installable package to install, make sure pip is installed and simply run:
|
||||
|
||||
## 1
|
||||
No merge found
|
||||
## 2
|
||||
Not a main branch
|
||||
## 3
|
||||
No git flow branch name found
|
||||
## 128
|
||||
Totally broken dont know why
|
||||
`pip install path/to/auto-semver-<version>tar.gz`
|
||||
|
||||
## 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 = 1.23.0
|
||||
commit = True
|
||||
tag = True
|
||||
tag_name = {new_version}
|
||||
message = Bump version: {current_version} -> {new_version}
|
||||
|
||||
[bumpversion:file:VERSION]
|
||||
search = version={current_version}
|
||||
replace = version={new_version}
|
||||
|
||||
[semver]
|
||||
main_branches = develop
|
||||
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.
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
```ini
|
||||
[semver]
|
||||
main_branches = develop
|
||||
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`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user