how-to-release.md: Fix "git push" command

diff --git a/.ansible-lint b/.ansible-lint
index 2c2e459166ce0e13999d6f4dcdac2b5ded2faedf..f9f1cf7f8ed0e83ef6616daa7a8cc97f5f3ff9de 100644 (file)
--- a/.ansible-lint
+++ b/.ansible-lint
@@ -8,6 +8,7 @@ exclude_paths:
   - ansible_galaxy/ansible_collections/
   - ansible_galaxy/ansible_roles/
   - bin/
+  - group_vars/all/ansible_vault.yml
   - requirements.yml
 
 warn_list:

diff --git a/.gitignore b/.gitignore
index d76a6357661355084157d71094dc641373222006..380fa01cc20d995b2f15d996f56a99eb97698963 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,5 @@
 /bin/ap
 /bin/aps
 /dist/
+
+.ansible-vault-secret

diff --git a/.yamllint.yml b/.yamllint.yml
index d61e11d41fd0b6793b209278cea0a6733994472f..46718bb05aa0554e5f532c8edae2192d650c4c67 100644 (file)
--- a/.yamllint.yml
+++ b/.yamllint.yml
@@ -5,12 +5,21 @@
 extends: default
 
 rules:
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false
+  braces:
+    max-spaces-inside: 1
   line-length:
     max: 100
     level: warning
+  octal-values:
+    forbid-explicit-octal: true
+    forbid-implicit-octal: true
 
 ignore: |
   .trunk/
   .venv/
   ansible_galaxy/ansible_collections/
   ansible_galaxy/ansible_roles/
+  group_vars/all/ansible_vault.yml

diff --git a/Makefile b/Makefile
index df6618093b998cd7e1203fb19494d88e7a523d1e..5a33f4971702f822a014450d9341bc959f3ce87e 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,16 @@ default: all
 include Makefile.boilerplate
 
 check: check-ansible
+       if command -v mdl >/dev/null; then make check-mdl; fi
+       if command -v shellcheck >/dev/null; then make check-shellcheck; fi
+
+check-mdl:
+       mdl -g -r '~MD013,~MD029' -w .
+
+check-shellcheck:
+       shellcheck \
+        bin/ansible-boilerplate \
+        bin/a bin/ap bin/aps
 
 install:
 
@@ -29,7 +39,7 @@ dist: all $(VENV_BIN)/ansible-galaxy
 distcheck: dist
 #      Run tests on distribution archive ...
        mkdir -p "$(DIST_D)/check"
-       tar -C "$(DIST_D)/check" -xzf "$(DIST_D)"/*.tar.gz
+       tar -C "$(DIST_D)/check" -xzf $$(find "$(DIST_D)" -name '*.tar.gz' | sort -Vr | head -n1)
        test -e "$(VENV_D)" && ln -fs "$(VENV_D)" "$(DIST_D)/check/.venv"
        make -C "$(DIST_D)/check" check
 #      Clean up ...

diff --git a/README.md b/README.md
index 7f244915efb87392e2e8efdf370e687abc938f16..7fd69ebb9627038f8aff28b31325cfecbbe3d88c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -98,3 +98,17 @@ system provided by this project, you can just use the `make` command itself:
 ```bash
 make upgrade
 ```
+
+## Upgrade vs. Update
+
+Updating an existing project, either with `./bin/ansible-boilerplate update` or
+by calling `make update`, means to fulfill all Python dependencies in
+`requirements.txt` and all Ansible Galaxy dependencies in `requirements.yml` by
+trying to install the latest/newest compatible versions. Ansible Boilerplate
+scripts are updated (overwritten) with their current versions; configuration is
+left unchanged.
+
+The `./bin/ansible-boilerplate upgrade` or `make upgrade` command do the same
+and additionally install new, missing and updated Ansible Boilerplate
+configuration files. Existing configuration files are not overwritten, new
+versions are installed with the ".new" file extension.

diff --git a/bin/ansible-boilerplate b/bin/ansible-boilerplate
index 3d089a189c9f1c3a0eed7dabdcb9917c740ffdf7..45c5024734261315aacca548af0a43fdc6df4293 100755 (executable)
--- a/bin/ansible-boilerplate
+++ b/bin/ansible-boilerplate
@@ -18,8 +18,8 @@ Usage() {
                echo "$0 <command>"
                echo
                echo "  help       Show this help text and exit."
-               echo "  init       Initialize project and boilerplate code."
-               echo "  upgrade    Upgrade boilerplate code and dependencies. [Alias: update, up]"
+               echo "  init       Initialize project and boilerplate code. [Alias: upgrade]"
+               echo "  update     Update boilerplate code and dependencies. [Alias: up]"
                echo "    --force  Force overwriting an existing role or collection."
                echo
        } >&2
@@ -131,7 +131,7 @@ EOF
 # - Install Ansible when ansible-galaxy command is not found.
 # - Install "ansible-boilerplate" collection when not found.
 # - Update local "ansible-boilerplate" setup: copy script, create links, ...
-# - Upgrade template files.
+# - Upgrade template files (when "--init" is given).
 # - Install/upgrade Python dependencies (from requirements.txt file).
 # - Install/upgrade Ansible Galaxy dependencies (from requirements.yml file).
 #
@@ -143,10 +143,11 @@ Upgrade() {
        while [ $# -gt 0 ]; do
                case "$1" in
                        "--force")
-                               do_force="--force"
+                               do_force="--force --force-with-deps"
                                ;;
                        "--init")
                                is_init="--init"
+                               do_force="--force --force-with-deps"
                                ;;
                        *)
                                Usage
@@ -189,9 +190,9 @@ Upgrade() {
 
        if [ -r requirements.yml ]; then
                echo "Upgrading Ansible Galaxy dependencies ..."
-               # shellcheck disable=SC2248
+               # shellcheck disable=SC2086
                "${ANSIBLE_GALAXY}" collection install -U -r requirements.yml ${do_force}
-               # shellcheck disable=SC2248
+               # shellcheck disable=SC2086
                "${ANSIBLE_GALAXY}" role install -r requirements.yml ${do_force}
        fi
 
@@ -238,7 +239,12 @@ Upgrade_Dependent() {
                requirements.txt \
        ; do
                # shellcheck disable=SC2086
-               Upgrade_Template "${file}" ${is_init}
+               Upgrade_Template "${file}" $1
+       done
+
+       # List differences in *.new template files, if any:
+       find . \( -name '*.new' -o -name '.*.new' \) | while read -r fname; do
+               diff -u "${fname%*.new}" "${fname}" || true; echo
        done
 }
 
@@ -261,7 +267,7 @@ Upgrade_Template() {
        # Do not override the target when it exists already!
        if [ -e "$1" ]; then
                # Target already exists. Is it different?
-               if [ "$2" = "--init" ] && ! cmp "$1" "${BASE_D}/$1"; then
+               if [ "$2" = "--init" ] && ! cmp -s "$1" "${BASE_D}/$1"; then
                        # Files are not the same! Install new version in parallel:
                        install -b -m 0644 -p -v "${BASE_D}/$1" "$1.new"
                fi
@@ -275,10 +281,10 @@ cmd="$1"
 [ $# -gt 0 ] && shift
 
 case "${cmd}" in
-       "init")
+       "init"|"upgrade")
                Init "$@"
                ;;
-       "upgrade"|"update"|"up")
+       "update"|"up")
                Upgrade "$@"
                ;;
        "help"|"--help")

diff --git a/docs/ansible-vault.md b/docs/ansible-vault.md
new file mode 100644 (file)
index 0000000..c8803f5
--- /dev/null
+++ b/docs/ansible-vault.md
@@ -0,0 +1,14 @@
+# Ansible Boilerplate Collection and Ansible vault
+
+This Boilerplate Collection is meant to cope well with Ansible vault.
+
+The following files are treated specially for ansible-vault(1) usage:
+
+- `.ansible-vault-secret`: You can use this as a "local vault password file".
+  It should _not_ be added to the Git repository and is listed in the
+  `.gitignore` template file by default.
+
+- `group_vars/all/ansible_vault.yml`: Use this file to store encrypted Ansible
+  variables which are handled by ansible-vault(1). It is automatically added to
+  some commands invoked by the Ansible Boilerplate scripts, wrappers, and
+  Makefile's.

diff --git a/docs/how-to-release.md b/docs/how-to-release.md
new file mode 100644 (file)
index 0000000..a850482
--- /dev/null
+++ b/docs/how-to-release.md
@@ -0,0 +1,59 @@
+# Creating a new Ansible Boilerplate Collection Release
+
+## Prerequisites
+
+1. Make sure your source tree is clean.
+2. Make sure everything is committed and pushed out.
+3. Run `make check`!
+
+## Steps to Create the new Release
+
+1. Set new version number (major.minor.fix):
+
+   ```sh
+   major=1; minor=2; fix=3
+   galaxy_api_key=…
+   ```
+
+2. Update `galaxy.yml`, bump the version number accordingly:
+
+   ```sh
+   sed -i'.bak' \
+     -e "s/^version: .*$/version: ${major}.${minor}.${fix}/g" galaxy.yml
+   rm -fv galaxy.yml.bak
+   ```
+
+3. Create the release commit and signed tag:
+
+   ```sh
+   git add galaxy.yml
+   git diff --cached --patch-with-stat
+   git commit --message "Release ${major}.${minor}.${fix}"
+   git tag -m "Release ${major}.${minor}.${fix}" -s \
+     "rel-${major}-${minor}-${fix}"
+   ```
+
+4. Create the distribution archive:
+
+   ```sh
+   make distcheck
+   ```
+
+   The resulting `.tar.gz` file is in the `./dist/` sub-directory.
+
+5. Push the commit and tag out:
+
+   ```sh
+   git push --all
+   ```
+
+6. Publish the new release on the Ansible Galaxy repository:
+
+   ```sh
+   .venv/bin/ansible-galaxy collection publish \
+     --api-key "${galaxy_api_key}" \
+     "dist/alexbarton-boilerplate-${major}.${minor}.${fix}.tar.gz"
+   ```
+
+7. Check the result online:
+   <https://galaxy.ansible.com/ui/repo/published/alexbarton/boilerplate/>

diff --git a/galaxy.yml b/galaxy.yml
index 6daee98ec42020b2d4df4869493e3926100b4ac0..38907b92fa97f064b2a524ad82d0b38afc5c1c18 100644 (file)
--- a/galaxy.yml
+++ b/galaxy.yml
@@ -1,7 +1,7 @@
 ---
 namespace: alexbarton
 name: boilerplate
-version: 1.0.1
+version: 1.1.2
 
 authors:
   - Alexander Barton <alex@barton.de>

diff --git a/requirements.txt b/requirements.txt
index c04d152094495372735c5efd7caba033294dcb0c..95a41f86d4db7bac7030e78e4fe11e4e1a20640a 100644 (file)
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,4 @@
 # Python dependencies
 
-ansible>=8.2
-ansible-lint>=6.17
+ansible>=9.6
+ansible-lint>=24.5