From b34ef6ceceb3f2b79f3664920c63aa146421e3f7 Mon Sep 17 00:00:00 2001 From: Jonathan Freedman Date: Sun, 14 Mar 2021 18:08:04 -0700 Subject: [PATCH] some doc subtleties --- .dir-locals.el | 4 +++ README.md | 82 +++++++++++++++++++++++++++++++++++++------------- 2 files changed, 65 insertions(+), 21 deletions(-) create mode 100644 .dir-locals.el 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 5ba0b8d..1e7565e 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,25 @@ 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. +* 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 @@ -26,9 +37,19 @@ The avakas tool supports the following types of version files ## show -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. +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. +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 @@ -37,14 +58,17 @@ 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. @@ -54,7 +78,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". ``` $ avakas show . @@ -84,17 +112,28 @@ This prefix will be added to the version string when creating a git tag. # 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 @@ -107,14 +146,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 @@ -122,4 +161,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.