diff --git a/.dir-locals.el b/.dir-locals.el new file mode 100644 index 0000000..5dd4947 --- /dev/null +++ b/.dir-locals.el @@ -0,0 +1,4 @@ +(("README.md" + (nil . + ((fill-column . 80))) + (markdown-mode . ((eval . (turn-on-auto-fill)))))) diff --git a/README.md b/README.md index 2ca45d4..491a265 100644 --- a/README.md +++ b/README.md @@ -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 @@ -27,7 +40,19 @@ 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 @@ -35,7 +60,8 @@ 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 @@ -43,7 +69,8 @@ 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. @@ -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 . @@ -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 @@ -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 @@ -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.