@@ -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
0 commit comments