ican is a simple version bumper/build pipeline orchestrator
Project description
:wave: ican
because anything you ask of it, the response is always ican
:man_office_worker: Motivation
There are plenty of version bumpers and build tools. But ican is the only one that is designed for the smallest teams, even the 1 man team.
The one man team has different procedures than most. Often times the one man team forgets to bump version numbers. Few even bother to keep a code repository besides their own "Dropbox."
ican brings big team development practices to small teams. ican's build number is one feature. As long as you use ican to automate your docker image builds, deployments, etc. each time your build number is incremented. That way you always have a different semantic version number, even if you don't purposely bump one of the primary 3 parts.
You can even easily use ican to start tagging docker images, as well as git commits. Soon your small team will be officially "tagging" and "releasing" software like you have a Fortune 500 CI/CD manager.
:floppy_disk: Install
Install the ican package via pypi
pip install ican
:toolbox: Sample Config
Config is done via the .ican file in your project's root diarectory.
Sample .ican config file
[version]
current = 0.1.6+build.40
[options]
log_file = ican.log
[aliases]
deploy = bump build
[file: version]
file = ./src/__init__.py
style = semantic
variable = __version__
[pipeline: new.release]
step1 = ./clean_my_project.sh
step2 = git commit -a
step3 = git tag -a {{tag}} --sign
step4 = git push origin master {{tag}}
Explanation
- This config defines the current version as
0.1.6
with build # 40. - All operations will be logged to the
ican.log
file. - ican will update a variable named
__version__
in./src/__init__.py
any time the bump command is run. - ican will use the
semantic
style of the version when updating this file. - The new.release pipeline will run on bump [patch, minor, or major].
- All pipeline steps are typically shell-based commands.
:exclamation: Important
Take note, all sections must be unique. So if you define more than one <file: [LABEL]> section, make sure each one has a unique label.
The same is true for pipeline
sections. Each pipeline section must have a unique label.
:thumbsdown: :exploding_head:
[file: py_code]
file = ./src/__init__.py
...
[file: py_code]
file = ./src/__main__.py
:thumbsup: :sunglasses:
[file: src_init]
file = ./src/__init__.py
...
[file: main]
file = ./src/__main__.py
:triangular_ruler: Config
Section | Key | Value |
---|---|---|
version | current | This is the value that ican stores the current version number in. |
version | previous | This is the previous version ican uses in case of rollback. |
options | log_file | All operations are logged to disk in this file. To turn logging off, do not define the log_file. |
aliases | [ALIAS] | Built-in command + args that [ALIAS] will trigger. Example bump patch |
file: [LABEL] | file | The filename of a file ican will update with new versions. You can use a standard unix glob (*.py) if desired. |
file: [LABEL] | style | The version format to use. Choices are [semantic, public, pep440, git] |
file: [LABEL] | variable | The variable name pointing to the version string that ican will update when versions are bumped. |
file: [LABEL] | regex | User-supplied python formattted regex string defining how to replace the file's version. |
pipeline: [LABEL] | [STEP] | A pipeline step is a cli command such as git commit -a . STEP values MUST to be unique. |
:mag: User-supplied regex
When searching for a variable, ican will search for the variable's name, followed by an =
symbol, followed by a value in either single or double quotes. There can be spaces or no spaces on either side of the =
symbol. This covers most use cases.
If your use case is more complicated, you can omit the variable
line in your config file and instead include a regex
value instead. This should be a pyton formatted regex string with a named group to identify the version
ican will replace.
[file1]
file = ./src/__init__.py
style = semantic
regex = __version__\s*=\s*(?P<quote>[\'\"])(?P<version>.+)(?P=quote)
:computer: Pipelines
Labels
Pipeline labels have 2 purposes:
- At the CLI using
ican run LABEL
. This way we know which pipeline to run. - Each
ican bump
looks for a specific pipeline to run automatically.- new.release - runs with
bump [major, minor, patch]
- new.prerelease - runs with
bump [prerelease]
- rebuild.release - runs with
bump[build]
IF the version IS NOT a prerelease - rebuild.prerelease - runs with
bump[build]
IF the version IS a prerelease
- new.release - runs with
Pipeline Context
The pipeline context is available in 2 locations
- In the pipeline itself, you can use Jinja-style templating. Example:
git push origin master {{tag}}
- Before pipelines run, ican injects the ENV with all pipeline context variables.
Pipeline Context Variables
Variable | Description |
---|---|
semantic | the current version in semantic format |
public | the current version in public format |
pep440 | the current version canonical with pep440 |
git | the current version using git metadata |
previous | the previous semantic version |
tag | the git tag, v{public_version} |
age | REBUILD if bump build, NEW all other bumps |
env | DEVELOPMENT or PRODUCTION based on the version |
stage | AGE . (RELEASE or PRERELEASE) ex NEW.RELEASE |
root | the root directory of your project |
:muscle: Use
You can use ican via the CLI in a typical fashion, using the format below
ican [command] [arguments] [options]
:dog2: Commands
Command | Arguments | Options | Description |
---|---|---|---|
bump | PART required |
Increments the PART of the semantic version. [major, minor, patch, prerelease] |
|
bump | --pre PRE |
If using prerelease, PRE allows you to set [alpha, beta, rc, dev] | |
show | STYLE required |
Shows the current version with the format STYLE. [semantic, public, pep440, git] |
|
run | PIPELINE required |
Run the specified PIPELINE | |
rollback | none | Rollback to the previously persisted version. | |
init | none | Initialize your project with default config in the current directory. |
:roll_eyes: Options
The output and parsing of ican
can be controlled with the following options.
Name | Description |
---|---|
--verbose |
To aid in your debugging, verbose prints all messages. |
--dry-run |
Useful if used WITH --verbose, will not modify any files. |
--version |
This will displpay the current version of ican. |
:eyes: Examples
$ ican init
...
$ ican show current
0.2.7-beta.3+build.99
# Bump with no arguments defaults to bump the build number.
$ ican bump
0.2.7-beta.3+build.100
# Now its release time. Lets bump the minor
$ ican bump minor
0.3.0+build.101
# Oh no, major problem, rollback
$ ican rollback
0.3.0+build.100
# Use an aliaw
$ ican deploy
+BEGIN pipeline.NEW.RELEASE
git commit successful
+END pipeline.NEW.RELEASE
1.0.0+build.101
# now run our docker pipeline
$ ican run docker
+BEGIN pipeline.DOCKER
docker container build...
+END pipeline.DOCKER
1.0.0+build.101
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.