Prepare galaxy releasing

.docsmith/readme.md.j2

@@ -1,20 +1,23 @@
 {# Compact README variable reference for ansible-docsmith. Shared by all roles.
-   Renders ONE table; nested sub-options (e.g. logstash_pipelines fields) appear as
-   indented rows. No per-variable detail sections, no table of contents.
+   Renders ONE two-column table. Type, required, default and choices are stacked
+   under the variable name so that only two columns compete for the page width and
+   the description never needs horizontal scrolling. Nested sub-options (e.g.
+   logstash_pipelines fields) appear as indented rows.
    Use with: --template-readme .docsmith/readme.md.j2 #}
 {% macro row(name, spec, depth) -%}
 {% set pad = '    ' * depth %}
 {% set mark = '↳ ' if depth > 0 else '' %}
-| {{ pad }}{{ mark }}`{{ name | ansible_escape }}` | `{{ spec.type }}`{% if spec.elements %} of `{{ spec.elements }}`{% endif %} | {% if spec.options %}…{% else %}{{ spec.default | format_default | replace('|', '\\|') }}{% endif %} | {% if spec.choices %}{{ spec.choices | map('string') | map('code_escape') | join(', ') }}{% else %}—{% endif %} | {{ spec.description | format_table_description(name, 0) }} |
+{% set default = spec.default | format_default | replace('|', '\\|') -%}
+| {{ pad }}{{ mark }}`{{ name | ansible_escape }}`<br>**Type**: `{{ spec.type }}`{% if spec.elements %} of `{{ spec.elements }}`{% endif %}{% if spec.required %}<br>**Required**: Yes{% endif %}{% if not spec.options and default != 'N/A' %}<br>**Default**: {{ default }}{% endif %}{% if spec.choices %}<br>**Choices**: {{ spec.choices | map('string') | map('code_escape') | join(', ') }}{% endif %} | {{ spec.description | format_table_description(name, 0) }} |
 {% for sn, ss in (spec.options or {}).items() %}
 {{ row(sn, ss, depth + 1) }}
 {%- endfor %}
 {%- endmacro %}
 ## Role variables<a id="variables"></a>
 
 {% if has_options %}
-| Variable | Type | Default | Choices | Description |
-|----------|------|---------|---------|-------------|
+| Variable | Description |
+|----------|-------------|
 {% for name, spec in options.items() %}
 {{ row(name, spec, 0) }}
 {%- endfor %}

.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+---
+# Publishes a tagged version of this collection to Ansible Galaxy and attaches the
+# built archive to the matching GitHub release.
+#
+# Triggered manually and never automatically, so that a tag can be inspected before an
+# immutable version reaches Galaxy. Both the tag and the release have to exist before
+# the workflow is started: the build happens from the checked out tag, galaxy.yml at
+# that tag determines the published version, and the archive is uploaded to the release
+# carrying the same name as the tag.
+#
+# Requires the repository or organization secret GALAXY_API_KEY, holding an API token of
+# an account that owns the "netways" namespace on Ansible Galaxy.
+
+name: publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing tag to build and publish, for example 0.1.0'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the tag
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install ansible-core
+        run: pip install ansible-core
+
+      - name: Show the version that will be published
+        run: grep '^version:' galaxy.yml
+
+      - name: Build the collection
+        run: ansible-galaxy collection build -vvv
+
+      - name: Publish to Ansible Galaxy
+        env:
+          GALAXY_API_KEY: ${{ secrets.GALAXY_API_KEY }}
+        run: ansible-galaxy collection publish --token "$GALAXY_API_KEY" ./netways-elasticstack-*.tar.gz
+
+      - name: Attach the archive to the release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ inputs.tag }}" ./netways-elasticstack-*.tar.gz --clobber

.github/workflows/test_changelog.yml

@@ -0,0 +1,80 @@
+---
+# Every pull request has to bring a changelog fragment, so that the changelog can be
+# generated at release time instead of being reconstructed from the commit history.
+#
+# A change that is not worth mentioning to users still needs a fragment, but its entry
+# goes into the "trivial" section, which antsibull-changelog does not render. See
+# CONTRIBUTING.md.
+
+name: Test Changelog
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  fragment:
+    # Dependabot only bumps action and dependency versions, which needs no fragment.
+    if: >-
+      github.event.pull_request.draft == false
+      && github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the codebase
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install antsibull-changelog
+        run: pip install "antsibull-changelog==0.35.1"
+
+      - name: A changelog fragment is present
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          if [ -z "$BASE_REF" ]; then
+            echo "Not a pull request, nothing to compare against."
+            exit 0
+          fi
+          git fetch --no-tags origin "$BASE_REF"
+          added=$(git diff --name-only --diff-filter=A \
+            "origin/$BASE_REF...HEAD" -- changelogs/fragments/ \
+            | grep -v '^changelogs/fragments/\.keep$' || true)
+          if [ -z "$added" ]; then
+            echo "::error::This pull request adds no new changelog fragment."
+            echo "Add a NEW file under changelogs/fragments/ describing the change."
+            echo "Do not put the entry into an existing fragment, so that every entry"
+            echo "stays traceable to the pull request that added it."
+            echo "If the change is not relevant for users, put the entry in the"
+            echo "'trivial' section. See CONTRIBUTING.md."
+            exit 1
+          fi
+          echo "New fragments in this pull request:"
+          echo "$added"
+
+          touched=$(git diff --name-only --diff-filter=MRD \
+            "origin/$BASE_REF...HEAD" -- changelogs/fragments/ \
+            | grep -v '^changelogs/fragments/\.keep$' || true)
+          if [ -n "$touched" ]; then
+            echo "::error::This pull request changes fragments it did not add:"
+            echo "$touched"
+            echo "Fragments belong to the pull request that created them. Add your own"
+            echo "instead of editing, renaming or deleting someone else's."
+            exit 1
+          fi
+
+      - name: Fragments are valid
+        run: antsibull-changelog lint

.gitignore

@@ -4,3 +4,9 @@ __pycache__*
 .vscode
 .venv
 .fuse_hidden*
+
+# ansible-lint working directory, also removed by "make cleanup"
+.ansible
+
+# antsibull-changelog
+changelogs/.plugin-cache.yaml

.mailmap

@@ -1,3 +1,14 @@
+# Maps the different name and email combinations people committed with onto one
+# canonical identity, so that git shortlog and git blame show one entry per person
+# instead of one per address. Git applies this file automatically.
+#
+# Add a line when somebody shows up twice, for example after a change of employer or
+# after a commit made through the GitHub web interface. Check the result with:
+#   git check-mailmap "Name <address>"
+#
+# Syntax: Proper Name <proper@mail> <commit@mail>
+# See https://git-scm.com/docs/gitmailmap
+
 Afeef Ghannam <afeef.ghannam@netways.de> <39904920+afeefghannam89@users.noreply.github.com>
 Alexander Stoll <alexander.stoll@netways.de> <45196568+Crited@users.noreply.github.com>
 Daniel Neuberger <daniel.neuberger@netways.de> <xtruthx@users.noreply.github.com>

CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing
+
+Every kind of contribution is welcome. This page describes what we need from a pull request so that reviewing it does not take longer than writing it.
+
+## Before you build something
+
+There is no written scope for this collection. It gets what is useful and what helps from an automation point of view, and that is easier to answer per case than in the abstract. Please open an issue for anything bigger than a bug fix and we will say yes or no before you invest the work.
+
+For now all pull requests go against `main`.
+
+## What a pull request needs
+
+* **One topic per pull request.** Touching several roles is fine when it is the same change in each of them, for example the same fix applied to beats, logstash, kibana and elasticsearch. A pull request that bundles unrelated changes gets sent back.
+* **A description that says precisely what changes and why.** This is required, not optional. A pull request whose purpose can only be reconstructed from the diff gets sent back.
+* **Evidence that it was tested**, against the new feature or fix and against what sits next to it. Please say which Elastic Stack release and which ansible-core version you tested with.
+* **New or changed variables** belong in the role's `meta/argument_specs.yml` and in its README table, otherwise the documentation drifts apart from the code. See "Documenting role variables" below.
+* **Comments on anything that is not obvious.** Six months later nobody remembers what a clever condition was for, and then it gets analysed again from scratch.
+* **A changelog fragment.** See below.
+* If a change **claims something about how Elastic behaves**, please link the Elastic documentation for it.
+
+
+## Changelog fragments
+
+The changelog is not generated from commit messages. It is assembled from small files that each pull request brings along, so that the description is written by the person who knows what changed rather than reconstructed months later at release time.
+
+Add one **new** file per pull request under `changelogs/fragments/`. Name it after the issue or the change, for example `546_rolling_upgrade.yml`. Do not put your entry into an existing fragment and do not rename or delete one, so that every entry stays traceable to the pull request that introduced it. The pipeline rejects both.
+
+```yaml
+# changelogs/fragments/546_rolling_upgrade.yml
+bugfixes:
+  - Raising ``elasticstack_version`` no longer upgrades all Elasticsearch nodes at once
+    (https://github.com/NETWAYS/ansible-collection-elasticstack/issues/546).
+```
+
+Available sections, one or more per file:
+
+| Section | Use it for |
+|---|---|
+| `major_changes` | Changes that affect how the collection is used as a whole |
+| `minor_changes` | New variables, new options, improved behaviour |
+| `breaking_changes` | Anything users have to adapt to, for example a renamed variable |
+| `deprecated_features` | Something that still works but will be removed |
+| `removed_features` | Something previously deprecated that is now gone |
+| `security_fixes` | Fixes with a security impact |
+| `bugfixes` | Wrong or broken behaviour that now works |
+| `known_issues` | Problems shipped with the release on purpose |
+| `trivial` | Not rendered into the changelog. See below |
+
+Fragments are consumed at release time: `antsibull-changelog release` folds them into the changelog and deletes them, so the directory is empty again after every release. That is why a new file is always the right answer, never an edit to an existing one.
+
+### Changes that do not belong in the changelog
+
+Some changes are not worth telling users about. They still need a fragment, but the entry goes into the `trivial` section, which is not rendered into the changelog:
+
+```yaml
+# changelogs/fragments/fix_comment_typo.yml
+trivial:
+  - Fixed a typo in a comment in the elasticsearch role.
+```
+
+Typical cases for `trivial`:
+
+* documentation wording, typos and formatting
+* CI and workflow changes
+* test and Molecule scenario changes
+* refactoring with no visible effect on behaviour
+* dependency bumps of test tooling
+
+If you are unsure whether something is trivial, ask in the pull request. It is easier to move an entry than to notice a missing one after the release.
+
+## Documenting role variables
+
+Role variables are documented from each role's `meta/argument_specs.yml`, which is the single source of truth. When your pull request changes a role's variables:
+
+1. Update that role's `meta/argument_specs.yml` with type, default and description.
+2. Regenerate the README variable table. Please do **not** edit it by hand. The table is produced by [ansible-docsmith](https://github.com/foundata/ansible-docsmith), install it with `pip install ansible-docsmith` if you do not have it:
+
+   ```bash
+   ansible-docsmith generate roles/<role> --no-defaults --template-readme .docsmith/readme.md.j2
+   ```
+
+3. Commit the regenerated `README.md` together with your change.
+
+The `Test Documentation` workflow checks that each README matches its `argument_specs.yml` and fails the pull request if they drift apart.
+
+## Documenting modules
+
+Modules document themselves through the `DOCUMENTATION`, `EXAMPLES` and `RETURN` blocks in their own file. That is the only place, so there is nothing to keep in sync. Check your changes with `ansible-doc netways.elasticstack.<module>`.
+
+Shared code under `plugins/module_utils/` has no such block, because `ansible-doc` does not read it. Those functions are described in [plugins/module_utils/README.md](plugins/module_utils/README.md), please keep it current when you change them.
+
+## Testing
+
+Besides testing your change against a real setup, the repository has Molecule scenarios that exercise the whole stack, and it checks for ansible-lint and yamllint errors. To run the linters locally there is a `makefile`:
+
+```bash
+make
+```
+
+## Releasing
+
+Maintainers only. See [RELEASE.md](RELEASE.md).

NOTICE.md

@@ -1,7 +1,7 @@
-# Notice and Acknowledgements #
+# Notice and Acknowledgements
 
-## Sponsoring ##
+## Sponsoring
 
 Here's a list of sponsors who contributed by having the collection improved via outsourcing to NETWAYS.
 
-* CID GmbH : Thank you so much for sponsoring. Especially the feature to have different types of Elasticsearch nodes in the cluster and the ingetration of rolling upgrades.
+* CID GmbH : Thank you so much for sponsoring. Especially the feature to have different types of Elasticsearch nodes in the cluster and the integration of rolling upgrades.