Skip to content

Commit bacc8f7

Browse files
DonatSzaborichm
authored andcommitted
docs: add AGENTS.md with shared developer conventions from .github
Propagate the centrally managed AGENTS.md template so role developers and AI agents get coding conventions (argument_specs, OSTree package install, shell module, tests) in-repo. Signed-off-by: Donat Szabo <dszabo@redhat.com>
1 parent 56eb75a commit bacc8f7

8 files changed

Lines changed: 302 additions & 255 deletions

‎.coderabbit.yaml‎

Lines changed: 2 additions & 249 deletions
Original file line numberDiff line numberDiff line change
@@ -32,254 +32,7 @@ reviews:
3232
unit_tests:
3333
enabled: false
3434

35-
# Enforce PR title and description requirements
36-
pre_merge_checks:
37-
title:
38-
mode: "warning"
39-
requirements: |
40-
PR title MUST follow Conventional Commits format:
41-
- Format: <required type><optional (scope)><optional !>: <required description>
42-
- Valid types: Refer to https://github.com/linux-system-roles/auto-maintenance/blob/main/pr_title_lint.py#L23
43-
- Examples:
44-
- "feat: Add backup functionality"
45-
- "fix: Correct OSTree package installation"
46-
- "fix!: Remove deprecated variable (breaking change)"
47-
- "chore(formatting): Fix indentation in my_module.py"
48-
- "refactor(python)!: Use new python library thispy which has breaking api changes"
35+
# Coding conventions, PR title/description requirements, AI attribution, and path-specific instructions live in AGENTS.md at the repo root.
36+
# CodeRabbit auto-discovers AGENTS.md and applies it as review criteria: https://docs.coderabbit.ai/knowledge-base/code-guidelines
4937

50-
custom_checks:
51-
- mode: "warning"
52-
name: "Description Format"
53-
instructions: |
54-
PR description MUST follow the template structure from .github/pull_request_template.md:
55-
- Must contain "Enhancement:" or "Feature:" section describing what changed
56-
- Must contain "Reason:" section explaining why the change was needed
57-
- Must contain "Result:" section describing the outcome or impact
58-
- Can contain optional "Issue Tracker Tickets (Jira or BZ if any):" section
59-
- Must contain "Signed-off-by:" section with your name and email address - use git commit -s
60-
- Can contain optional "Assisted-by:" section with name of the AI coding assistant and models used
6138

62-
Example:
63-
```
64-
Feature: Introduce the network_secure_logging variable
65-
66-
Reason: Currently, all sensitive tasks use hard-coded no_log: true, which makes debugging difficult.
67-
68-
Result: Users can now set network_secure_logging: false for debugging while maintaining secure defaults.
69-
70-
Issue Tracker Tickets (Jira or BZ if any): RHEL-12345
71-
72-
Signed-off-by: John Doe john.doe@example.com
73-
74-
Assisted-by: Fish 4.3 using model Swim 6.2
75-
```
76-
77-
For PRs that are bug fixes, you can use the following template:
78-
- Must contain "Cause:" section explaining the root cause of the bug
79-
- Must contain "Consequences:" section explaining the impact of the bug and how it appears to users
80-
- Must contain "Fix:" section explaining the fix for the bug and how it fixes the bug
81-
- Must contain "Result:" section describing the outcome or impact of the fix
82-
- Can contain optional "Issue Tracker Tickets (Jira or BZ if any):" section
83-
- Must contain "Signed-off-by:" section with your name and email address - use git commit -s
84-
- Can contain optional "Assisted-by:" section with name of the AI coding assistant and models used
85-
86-
Example:
87-
```
88-
Cause: The variable rolename_user_name was being checked for a `none` value but was not being checked for string length greater than 0 if a string.
89-
90-
Consequences: The role allowed empty user names to be configured which caused the daemon to report "User not found".
91-
92-
Fix: The variable rolename_user_name is now checked for string length if not `none`, and will report an error in that case if the length is 0.
93-
94-
Result: The role will not allow the user to provide an empty user name and will report an error if the rolename_user_name length is 0.
95-
96-
Signed-off-by: John Doe john.doe@example.com
97-
98-
Assisted-by: Fish 4.3 using model Swim 6.2
99-
```
100-
101-
- mode: "warning"
102-
name: "AI Agent Attribution"
103-
instructions: |
104-
If the added code was substantially generated by AI, the generated code should contain a
105-
comment in-line or at the top of the file after the SPDX line (if any). The attribution
106-
comment should look like this:
107-
```
108-
# Assisted by <name of agent> using model(s) <name and version of model>[, <name and version of another model>]
109-
```
110-
The git commit message/PR body should also contain an attribution line like the following:
111-
```
112-
Assisted-by: <name of agent> using model(s) <name and version of model>[, <name and version of another model>]
113-
```
114-
115-
path_instructions:
116-
# ========================================
117-
# Ansible Tasks - Core role logic
118-
# ========================================
119-
- path: "tasks/**/*.yml"
120-
instructions: |
121-
**no_log patterns:**
122-
- For sensitive data (credentials, secrets, passwords, keys):
123-
```yaml
124-
- name: Task with sensitive data
125-
ansible.builtin.command: sensitive command
126-
no_log: "{{ network_secure_logging }}"
127-
```
128-
Ensure `network_secure_logging: true` is defined in defaults/main.yml
129-
130-
- For facts modules (package_facts, service_facts):
131-
```yaml
132-
- name: Gather package facts
133-
ansible.builtin.package_facts:
134-
no_log: "{{ ansible_verbosity < 3 }}"
135-
```
136-
This hides verbose facts output unless running with -vvv or higher verbosity
137-
138-
- NEVER use hardcoded `no_log: true` - always parametrize
139-
140-
**Package installation (OSTree compatibility):**
141-
- ALWAYS use `ansible.builtin.package` module (NEVER yum, dnf, or apt)
142-
- For Red Hat family systems: MUST include `use:` parameter for OSTree compatibility
143-
- For other systems (apt, etc.): OSTree `use:` parameter NOT needed
144-
145-
**Red Hat family pattern (rpm/dnf/yum based):**
146-
```yaml
147-
- name: Install packages
148-
ansible.builtin.package:
149-
name: "{{ __network_packages }}"
150-
state: present
151-
use: "{{ (__network_is_ostree | d(false)) | ternary('ansible.posix.rhel_rpm_ostree', omit) }}"
152-
```
153-
154-
**Non-Red Hat systems (apt based) - no OSTree handling needed:**
155-
```yaml
156-
- name: Install packages
157-
ansible.builtin.package:
158-
name: "{{ __network_packages }}"
159-
state: present
160-
when: ansible_facts["pkg_mgr"] == 'apt'
161-
```
162-
163-
**Pattern explanation:**
164-
- `__network_is_ostree` detects OSTree/rpm-ostree systems (RHEL/CentOS/Fedora variants)
165-
- This variable should already exist in vars/main.yml - do NOT suggest adding it
166-
- `| d(false)` provides safe default if variable undefined
167-
- `ternary()` selects `ansible.posix.rhel_rpm_ostree` for OSTree, `omit` otherwise
168-
- `omit` removes the parameter entirely on non-OSTree Red Hat systems
169-
170-
**Third-party collections:**
171-
- Avoid using third-party collections (community.general, community.crypto, etc.)
172-
- Use ansible.builtin modules or command module instead
173-
174-
**Referencing other system roles:**
175-
- Use FQCN: `fedora.linux_system_roles.network`
176-
177-
**Idempotency:**
178-
- Tasks must be idempotent - safe to run multiple times without unintended changes
179-
- Use proper state parameters (present/absent, started/stopped, etc.)
180-
- Command/shell tasks should use creates/removes or changed_when to avoid false changes
181-
- Example:
182-
```yaml
183-
- name: Initialize database
184-
ansible.builtin.command: /usr/bin/initialize-db
185-
args:
186-
creates: /var/lib/db/initialized.flag
187-
```
188-
189-
**Check mode support:**
190-
- Critical tasks should support check mode (--check flag)
191-
- Use check_mode: false only when absolutely necessary (e.g., fact gathering)
192-
- Test that role works with --check --diff
193-
194-
**Test coverage requirement:**
195-
- When adding new tasks to tasks/main.yml or creating new task files, verify that corresponding test coverage exists in tests/
196-
- New functionality MUST include test files (tests/tests_*.yml) that exercise the new code paths
197-
- Tests should verify both success scenarios and failure/edge cases
198-
- If this PR adds new tasks but does not include new or updated tests, flag it and request test coverage
199-
200-
# ========================================
201-
# Handlers
202-
# ========================================
203-
- path: "handlers/**/*.yml"
204-
instructions: |
205-
- Handlers with sensitive data must use `no_log: "{{ network_secure_logging }}"`
206-
207-
# ========================================
208-
# Test Playbooks
209-
# ========================================
210-
- path: "tests/tests_*.yml"
211-
instructions: |
212-
**CRITICAL: Role invocation pattern:**
213-
- NEVER use `ansible.builtin.include_role` directly
214-
- NEVER use `ansible.builtin.import_role` directly
215-
- NEVER use `roles:` keyword
216-
- ALMOST ALWAYS use the centrally managed wrapper:
217-
```yaml
218-
- name: Run role
219-
ansible.builtin.include_tasks: tasks/run_role_with_clear_facts.yml
220-
vars:
221-
network_<parameter>: <value>
222-
```
223-
The only exception to this rule is in tests_invalid_inputs.yml where we need to use the include_role directly to test the invalid inputs.
224-
225-
**Test quality requirements:**
226-
- Tests should verify both success and failure scenarios
227-
- Use assert module to verify expected state after role execution
228-
- Include cleanup tasks to ensure tests are rerunnable
229-
- Tests should be run in a block with an always section that runs the test cleanup to ensure that the cleanup is always run.
230-
- The cleanup tasks should be tagged with `tests::cleanup` so that the cleanup can be skipped for debug purposes.
231-
- Tests should be idempotent - running twice should not cause failures
232-
- Example verification:
233-
```yaml
234-
- name: Verify service is running
235-
ansible.builtin.assert:
236-
that:
237-
- ansible_facts.services['mssql-server.service'].state == 'running'
238-
fail_msg: "SQL Server service is not running"
239-
```
240-
241-
# ========================================
242-
# Templates
243-
# ========================================
244-
- path: "templates/**/*.j2"
245-
instructions: |
246-
**Required headers (in this order):**
247-
1. ansible_managed header: `{{ ansible_managed | comment }}`
248-
2. Role fingerprint: `{{ "system_role:network" | comment(prefix="", postfix="") }}`
249-
250-
# ========================================
251-
# Variable Definitions - defaults/
252-
# ========================================
253-
- path: "defaults/**/*.yml"
254-
instructions: |
255-
- All variables MUST be prefixed with `network_`
256-
- All variables MUST be stored in the file defaults/main.yml, Ansible
257-
doesn't include variables from other files.
258-
- These are user-facing API variables
259-
- For every new variable introduced in this file, verify that it is
260-
documented in README.md with a description and a usage example.
261-
If it is missing from README.md, flag it and request that it be added.
262-
263-
# ========================================
264-
# Variable Definitions - vars/
265-
# ========================================
266-
- path: "vars/**/*.yml"
267-
instructions: |
268-
- Internal variables MUST be prefixed with `__network_`
269-
- User-facing variables belong in defaults/main.yml, not here
270-
271-
# ========================================
272-
# Python Code
273-
# ========================================
274-
- path: "**/*.py"
275-
instructions: |
276-
- Must follow PEP 8 and be formatted with Python Black
277-
- Run `tox -e black,flake8` before committing
278-
279-
# ========================================
280-
# Documentation
281-
# ========================================
282-
- path: "README.md"
283-
instructions: |
284-
- Document all new user-facing variables
285-
- Include usage examples for new functionality

‎.github/workflows/actions.lock‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ dependencies:
110110
repo_id: 259445878
111111
'linux-system-roles/.github@main':
112112
ref: 'main'
113-
commit: 'sha1-c685ee6b59776f177edf523bf4eab71c8ee195eb'
113+
commit: 'sha1-f72e2d97b815ff843a106fb57949215d23bbf7df'
114114
owner_id: 28014670
115115
repo_id: 320092621
116116
'sclorg/testing-farm-as-github-action@v4.3.1':

‎.github/workflows/ansible-lint.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ jobs:
6868
- name: Install tox, tox-lsr
6969
run: |
7070
set -euxo pipefail
71-
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@241b655430b2fa3c2406b6d2a1190c9febb34b5b"
71+
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@8a78b9aa198295bb149510610453d33a1afe6366"
7272
7373
- name: Set up Python
7474
uses: actions/setup-python@v7.1.0

‎.github/workflows/ansible-managed-var-comment.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ jobs:
5757
- name: Install tox, tox-lsr
5858
run: |
5959
set -euxo pipefail
60-
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@241b655430b2fa3c2406b6d2a1190c9febb34b5b"
60+
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@8a78b9aa198295bb149510610453d33a1afe6366"
6161
6262
- name: Run ansible-plugin-scan
6363
run: |

‎.github/workflows/ansible-test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ jobs:
7171
- name: Install tox, tox-lsr
7272
run: |
7373
set -euxo pipefail
74-
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@241b655430b2fa3c2406b6d2a1190c9febb34b5b"
74+
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@8a78b9aa198295bb149510610453d33a1afe6366"
7575
7676
- name: Set up Python
7777
uses: actions/setup-python@v7.1.0

‎.github/workflows/python-unit-test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ jobs:
9494
tox=tox
9595
virtualenv=virtualenv
9696
fi
97-
pip install "$tox" "$virtualenv" "git+https://github.com/linux-system-roles/tox-lsr@241b655430b2fa3c2406b6d2a1190c9febb34b5b"
97+
pip install "$tox" "$virtualenv" "git+https://github.com/linux-system-roles/tox-lsr@8a78b9aa198295bb149510610453d33a1afe6366"
9898
# If you have additional OS dependency packages e.g. libcairo2-dev
9999
# then put them in .github/config/ubuntu-requirements.txt, one
100100
# package per line.

‎.github/workflows/qemu-kvm-integration-tests.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ jobs:
141141
python3 -m pip install --upgrade pip
142142
sudo apt update
143143
sudo apt install -y --no-install-recommends git ansible-core genisoimage qemu-system-x86 qemu-utils
144-
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@241b655430b2fa3c2406b6d2a1190c9febb34b5b"
144+
pip3 install "git+https://github.com/linux-system-roles/tox-lsr@8a78b9aa198295bb149510610453d33a1afe6366"
145145
146146
- name: Check for podman version 5 or higher
147147
id: check_podman_version

0 commit comments

Comments
 (0)