Skip to content

Commit

Permalink
Merge branch 'mainline' into mjuarez/docs-update
Browse files Browse the repository at this point in the history
  • Loading branch information
@otakup0pe
otakup0pe authored Mar 15, 2021
2 parents 1c7818a + b34ef6c commit 2a9ccee
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 19 deletions.
4 changes: 4 additions & 0 deletions .dir-locals.el
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
(("README.md"
(nil .
((fill-column . 80)))
(markdown-mode . ((eval . (turn-on-auto-fill))))))
81 changes: 62 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,26 @@ avakas

# Overview

This script provides a simple interface around viewing and manipulating project version metadata. It may be used to either bump, set, or view the version information for the project in a given directory. It is written with [semantic versioning](http://semver.org/) in mind.

It currently does it's best to determine whether the given directory contains a NodeJS, Erlang, Chef Cookbook, or Ansible project before just settling on keeping the version in a file named `version`. If a NodeJS project is discovered then the `package.json` will be edited. If an Ansible project is discovered then no files will be modified but the tags will still be handled. The Erlang detection is limited to OTP apps, and `avakas` will attempt to edit a rebar style `foo.app.src`. If a Chef Cookbook is discovered then `avakas` will attempt to modify the `version` attribute in `metadata.rb`.
This script provides a simple interface around viewing and manipulating project
version metadata. It may be used to either bump, set, or view the version
information for the project in a given directory. It is written with [semantic
versioning](http://semver.org/) in mind.

It currently does it's best to determine whether the given directory contains a
NodeJS, Erlang, Chef Cookbook, or Ansible project before just settling on
keeping the version in a file named `version`. If a NodeJS project is discovered
then the `package.json` will be edited. If an Ansible project is discovered then
no files will be modified but the tags will still be handled. The Erlang
detection is limited to OTP apps, and `avakas` will attempt to edit a rebar
style `foo.app.src`. If a Chef Cookbook is discovered then `avakas` will attempt
to modify the `version` attribute in `metadata.rb`.

The avakas tool makes a few assumptions

* There is only one logical project in each directory.
* The directory is somewhere in a git repository. You can have multiple projects
per repository by using the `--tag-prefix` option.
* For the protection of the user the git workspace must not be dirty.

The avakas tool supports the following types of version files

Expand All @@ -27,23 +40,37 @@ The avakas tool supports the following types of version files

## show

This mode will return the current version for a given project. Some optional arguments include:
This mode will return the current version for a given project. The following
will show the current Public API version. This operation supports an additional
`--build` argument, which will cause it to extend the version set in source
control with build-time metadata. It also supports the `--pre-build` argument,
which does the same thing on top of the prerelease field, because all kinds of
package management systems do not actually support the build semantic version
component.

It is possible to override this default `pre-build` behavior. The
`--pre-build-date` option will include the current date (down to the second) as
a string. The `--pre-build-prefix=foo` option will include a string prefix. It
is possible to include both pre-build _and_ build information, but only if you
specify a prefix or include the date in prebuild.

```shell
avakas show $HOME/projects/hal9000
```

## set

This mode will set an explicit version. Note that the string must be a valid semantic version.
This mode will set an explicit version. Note that the string must be a valid
semantic version.

```shell
avakas set $HOME/projects/hal9000 2.0.0
```

## bump

This mode will automatically update the version based on the input provided. It has four modes of operation.
This mode will automatically update the version based on the input
provided. It has four modes of operation.

* `major` will update the major (left) version component.
* `minor` will update the minor (middle) version component.
Expand All @@ -53,7 +80,11 @@ This mode will automatically update the version based on the input provided. It

### Autobump

When the `auto` option is selected, the system will use hints in the git log since the last version bump to determine if the version should be changed. These hints can be specified at any point in the commit message. The hints are specified, prefixed by `bump:`. For example, the following commit message would result in a minor version bump if it is subsequently "autobumped".
When the `auto` option is selected, the system will use hints in the git log
since the last version bump to determine if the version should be changed. These
hints can be specified at any point in the commit message. The hints are
specified, prefixed by `bump:`. For example, the following commit message would
result in a minor version bump if it is subsequently "autobumped".

```shell
$ avakas show .
Expand Down Expand Up @@ -127,17 +158,28 @@ Will use a prefix for the prerelease. (Example: `1.0.0-alpha.1`)

# Docker

You can use `avakas` as a Docker container as well. It supports either static SSH keys or the SSH Agent. It seems like the SSH agent only works on Linux though. The Docker entrypoint should setup your SSH environment on the `set` and `bump` `avakas` actions.
You can use `avakas` as a Docker container as well. It supports either static
SSH keys or the SSH Agent. It seems like the SSH agent only works on Linux
though. The Docker entrypoint should setup your SSH environment on the `set` and
`bump` `avakas` actions.

You can map a folder to `/etc/avakas` for static SSH or Git environment configuration. If the file `avakasrc` is present in `/etc/avakas` it will be sourced prior to running `avakas`. A common use case here is to export the `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` environment variables.
You can map a folder to `/etc/avakas` for static SSH or Git environment
configuration. If the file `avakasrc` is present in `/etc/avakas` it will be
sourced prior to running `avakas`. A common use case here is to export the
`GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` environment variables.

In all cases, you will want to map a source project into a folder and point `avakas` at it. The following example (running on Linux with SSH Agent forwarding) would bump the patch portion of the version in the current directory.
In all cases, you will want to map a source project into a folder and point
`avakas` at it. The following example (running on Linux with SSH Agent
forwarding) would bump the patch portion of the version in the current
directory.

```
$ docker run -t -v $(pwd):/app -v $SSH_AUTH_SOCK:/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent otakup0pe/avakas bump /app patch
```

The next example (running on OSX) would set the version explicitly in the current directory. Note how we need to setup a working folder to map `/etc/avakas` against.
The next example (running on OSX) would set the version explicitly in the
current directory. Note how we need to setup a working folder to map
`/etc/avakas` against.

```
$ mkdir -p /tmp/ssh-avakas-working
Expand All @@ -150,14 +192,14 @@ $ docker run -v $(pwd):/app -v /tmp/ssh-avakas-working:/etc/avakas otakup0pe/av
## Local Testing

`make test_in_containers` will run all integration tests against all supported
minor versions of Python. It does not currently run any style or lint tests,
and the coverage report it generates points to an absolute path on the
container (`/src/`) and is therefore not terribly useful, but it does run all
of the integration tests (the other tests and output are planned to be added).
minor versions of Python. It does not currently run any style or lint tests, and
the coverage report it generates points to an absolute path on the container
(`/src/`) and is therefore not terribly useful, but it does run all of the
integration tests (the other tests and output are planned to be added).

`make test` will work to run tests against whatever version of Python is
`python3` on your host. It also runs style and lint checks, and generates a
coverage report from the integration tests.
`make test` will work to run tests against whatever version of Python
is `python3` on your host. It also runs style and lint checks, and
generates a coverage report from the integration tests.

# License

Expand All @@ -166,4 +208,5 @@ coverage report from the integration tests.

# Author

The avakas tool was created by [Jonathan Freedman](http://jonathanfreedman.bio/).
The avakas tool was created by [Jonathan Freedman](http://jonathanfreedman.bio/)
and has seen several collaborators along the way.

0 comments on commit 2a9ccee

Please sign in to comment.