From f3dcb065e5d63ae9b621f3356a026d2baba019fc Mon Sep 17 00:00:00 2001 From: voidvore Date: Sun, 26 Jul 2026 03:59:03 +0300 Subject: [PATCH 1/4] chore: Setup AI agent infrastructure - Add .agents/AGENTS.md: AI contributor guide with project overview and crate map - Add .agents/CONTRIBUTING_AGENTS.md: research-backed governance guide for editing AGENTS.md - Update .gitignore: track AGENTS.md and CONTRIBUTING_AGENTS.md, ignore rest of .agents/ and .opencode --- .agents/AGENTS.md | 27 +++++ .agents/CONTRIBUTING_AGENTS.md | 174 +++++++++++++++++++++++++++++++++ .gitignore | 6 ++ 3 files changed, 207 insertions(+) create mode 100644 .agents/AGENTS.md create mode 100644 .agents/CONTRIBUTING_AGENTS.md diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md new file mode 100644 index 00000000..49eb6e3d --- /dev/null +++ b/.agents/AGENTS.md @@ -0,0 +1,27 @@ +# ASUSCTL – AI contributor guide + +ASUSCTL is a Linux utility for controlling ASUS laptop hardware features. + +## Overview + +| Area | Location | Description | +|------|----------|-------------| +| asus-shutdown | `asus-shutdown/` | +| asusctl (CLI) | `asusctl/` | +| asusd (system D-Bus daemon) | `asusd/` | +| asusd-user (user D-Bus daemon) | `asusd-user/` | +| config-traits | `config-traits/` | +| dmi-id | `dmi-id/` | +| rog-platform | `rog-platform/` | +| rog-dbus | `rog-dbus/` | +| rog-anime | `rog-anime/` | +| rog-aura | `rog-aura/` | +| rog-profiles | `rog-profiles/` | +| rog-control-center | `rog-control-center/` | +| rog-slash | `rog-slash/` | +| rog-scsi | `rog-scsi/` | +| simulators | `simulators/` | +| data (service files, udev rules) | `data/` | +| extra (icons, web assets) | `extra/` | +| distro-packaging | `distro-packaging/` | +| CI/CD (GitHub Actions) | `.github/` | \ No newline at end of file diff --git a/.agents/CONTRIBUTING_AGENTS.md b/.agents/CONTRIBUTING_AGENTS.md new file mode 100644 index 00000000..294e0300 --- /dev/null +++ b/.agents/CONTRIBUTING_AGENTS.md @@ -0,0 +1,174 @@ +# CONTRIBUTING to AGENTS.md β€” Human Governance Guide + +> [!CAUTION] +> **Warning:** This document is NOT for AI agents. It is a governance guide for human contributors who edit `AGENTS.md`. AI must never read or process this file. + +--- + +## πŸ“‹ Table of Contents + +1. [Why This File Exists](#why-this-file-exists) +2. [Research Findings](#research-findings) + - [1. Instruction File Structure & Impact (Instructions-as-Code)](#1-instruction-file-structure--impact-instructions-as-code) + - [2. Rule Polarity & Context Priming (Guardrails vs. Guidance)](#2-rule-polarity--context-priming-guardrails-vs-guidance) + - [3. Repository Context Overhead & Minimalist Design (AGENTS.md Evaluation)](#3-repository-context-overhead--minimalist-design-agentsmd-evaluation) + - [4. Closed-Loop Review Feedback & Behavioral Rule Accumulation (Self-Improving Agents)](#4-closed-loop-review-feedback--behavioral-rule-accumulation-self-improving-agents) +3. [Contributor Conclusions](#contributor-conclusions) + - [Sub-Agent Usage](#sub-agent-usage) + - [Performance and Flow Configuration](#performance-and-flow-configuration) + - [Documentation File Method](#documentation-file-method) +4. [Note to Maintainers: AI Feedback Loop](#note-to-maintainers-ai-feedback-loop) + +--- + +## 🎯 Why This File Exists + +`AGENTS.md` is an **LLM system prompt**, not human documentation. It lives inside the model's context window on every turn, so every wasted token degrades performance and burns budget. This guide explains what belongs in `AGENTS.md`, what does not, and why. + +Use `AGENTS.md` to document solutions for recurring issues encountered during LLM workflows: + +* 🎯 **Document Explicit Rules:** If the model repeatedly gets stuck or requires manual correction on the same mistake, specify its exact required behavior. +* 🌐 **Global Scope Only:** Ensure rules apply globally across the entire project rather than targeting isolated, one-off scenarios. + +--- + +## πŸ”¬ Research Findings + +> [!IMPORTANT] +> Before making changes to the [AGENTS.md](/.agents/AGENTS.md) file, you must thoroughly read or analyze the papers listed below with the assistance of AI to fully understand them. To contribute, feel free to add any new research you find useful to this list. + +### 1. Instruction File Structure & Impact (Instructions-as-Code) + +Adding instruction files (`AGENTS.md`, `.cursorrules`, `copilot-instructions.md`) only improves agent performance when structured as modular code with fine-grained rules. + +> πŸ“„ **Source:** [arXiv:2606.13449](https://arxiv.org/html/2606.13449v1): Empirical study of 15,549 AI-generated PRs across 148 open-source GitHub projects (AIDev dataset). + +#### Key Findings & Metrics +* **Success Split:** 27.70% of projects (41) saw $\ge 20\%$ higher PR merge rates, 26.35% (39) saw $\ge 20\%$ *decrease*, and 45.95% (68) had no significant change. +* **Structure Matters:** Successful instruction files were longer (median of **976 words** vs. **569 words** in failing projects) and heavily sectioned with H3 headers (median **9 `###` headers** vs. **1 `###` header** in failing projects). +* **Code Quality & Friction:** Well-structured instruction files reduced code churn by **-18.5%** and review comments to **0.6x**, whereas poor files increased code churn by **+34.2%** and review comments to **1.8x**. + +> [!TIP] +> **Rule:** Write instruction files as modular, fine-grained **`###` subsections** (*Instructions-as-Code*) rather than loose, informal text. + +--- + +### 2. Rule Polarity & Context Priming (Guardrails vs. Guidance) + +Prohibitive guardrails ("DO NOT") consistently improve agent task completion, whereas prescriptive style guidance ("DO") is often neutral or individually harmful. + +> πŸ“„ **Source:** [arXiv:2604.11088](https://arxiv.org/html/2604.11088v2): Controlled study analyzing 679 rule files (25,532 rules) across 5,000+ Claude Code agent runs on SWE-bench Verified. + +#### Key Findings & Metrics +* **Guardrails Beat Guidance:** Prohibitive negative constraints (e.g., *"do not refactor unrelated code"*) consistently boosted task completion rates by **+13.8 percentage points (+13.8pp)**, whereas positive directives (e.g., *"follow code style"*, *"run tests before committing"*) were neutral or harmful (-1.2pp to +0.4pp). +* **Context Priming Mechanism:** Performance gains were largely content-independent; randomized, shuffled, or off-domain rule sets matched expert-curated rule sets (yielding the same **+13.8pp** gain), demonstrating that rule files function primarily as a context priming signal that activates structured problem-solving pathways. +* **Ensemble Resilience:** Accumulating 0 to 50 rules maintained stable pass rates without degrading performance. +* **Aviation Checklist Analogy:** Like flight checklists, rule files work best when preventing specific human/LLM error modes rather than teaching baseline procedural knowledge. + +> [!TIP] +> **Rule:** Prioritize explicit negative constraints and prohibitive guardrails over positive style advice to prevent agent missteps and activate structured reasoning. + +--- + +### 3. Repository Context Overhead & Minimalist Design (AGENTS.md Evaluation) + +Comprehensive repository context files often degrade agent task performance and inflate inference costs unless restricted to minimal, essential constraints. + +> πŸ“„ **Source:** [arXiv:2602.11988](https://arxiv.org/html/2602.11988v1): Empirical study evaluating LLM-generated and human-written context files across 438 coding tasks in SWE-bench Lite and AGENTbench. + +#### Key Findings & Metrics +* **Task Success Degradation:** Providing repository-level context files generally reduced overall task completion rates compared to providing no context at all; LLM-generated context files decreased success rates by **-3%**, while human-written files yielded only a marginal **+4%** gain. +* **Inference Cost Surge:** Including repository context files increased total inference costs by **>20%** across all evaluated agent frameworks and LLMs. +* **Increased Exploration Friction:** Agents actively obeyed context guidelinesβ€”increasing tool usage by **1.6x to 2.5x** and executing more testsβ€”yet high-level repository overviews failed to help agents locate relevant files faster, causing agents to exhaust step/token budgets. +* **Ablation Results:** Stronger LLMs did not generate more effective context files, and prompt engineering variations failed to eliminate performance drops. + +> [!TIP] +> **Rule:** Omit verbose codebase overviews and comprehensive guidelines from repository context files; restrict instructions strictly to minimal, non-negotiable execution constraints. + +--- + +### 4. Closed-Loop Review Feedback & Behavioral Rule Accumulation (Self-Improving Agents) + +Converting accepted human PR review comments into persistent, version-controlled behavioral rules eliminates repetitive error classes across sessions without model fine-tuning. + +> πŸ“„ **Source:** [arXiv:2607.13091](https://arxiv.org/html/2607.13091v1): Deployment study of a closed-loop framework across 35+ microservices, evaluating 11 logged work sessions and 36 PR reviews. + +#### Key Findings & Metrics +* **Zero Error Recurrence:** Codifying human PR review feedback into explicit behavioral rules achieved a **0% recurrence rate** (0 repeated errors across 74 post-rule session exposures) across all codified error classes. +* **Review Effort Elevation:** Human review effort shifted away from low-level mechanical correctness and code formatting (**14%** of total review comments) toward high-level architecture, design, and performance (**66%** of total review comments). +* **Logarithmic Rule Saturation:** Rule set accumulation followed a logarithmic curve, stabilizing at **18 behavioral rules**, **15+ language-specific standards**, and a **15-item self-review checklist** (~6,250 tokens, consuming **<5%** of a 128K context window). +* **Cross-Domain & Tool Transfer:** **60%** of documented knowledge transfers crossed repository, task, or interface boundaries (e.g., migrating rules seamlessly from IDE to Terminal agents) without requiring model weight updates or RLHF. + +> [!TIP] +> **Rule:** Systematically transform accepted human code review comments into version-controlled instruction rules and pre-submission self-review checklists to permanently block recurring error classes. + +--- + +## πŸ’‘ Contributor Conclusions + +> [!NOTE] +> **Note:** If you find any section to be incorrect or inaccurate, please add your corrections along with supporting evidence and references. + +### Sub-Agent Usage and Setup Guidelines + +A **sub-agent** is an isolated worker process spawned by a primary (orchestrator) agent to execute a specific, self-contained task. By running within its own fresh context window and passing only the latest chat message rather than the entire conversation history, a sub-agent prevents context window saturation, lowers inference costs, and maintains high execution accuracy across complex workflows. + +#### When to Use vs. When Not to Use Sub-Agents + +##### βœ… When to Use: +* **Context Window Saturation:** Used when the context window becomes bloated to prevent the LLM from losing focus due to excessive context. +* **Cost Optimization:** To keep costs low, assign a frontier model to the main agent (orchestrator) while utilizing cheaper models for certain sub-agents (excluding planning agents). +* **Context Isolation:** Applied to offload the main agent's context window, prevent context poisoning, and achieve more accurate results. *(Note: The sub-agent should inherit minimal context from the main agent. Only include critical execution constraints and rules that would break the code if violated.)* +* **Parallel Tasks:** When parallel execution is required (tasks must be mutually independent to avoid conflicts; the main agent should ideally determine this suitability). +* **Separation of Roles and Responsibilities:** When a single model is instructed in `AGENTS.md` to simultaneously write code, run tests, and act as a security auditor, it bloats the context window and significantly increases the likelihood of errors. + +##### ❌ When Not to Use: +* For sequential, interdependent tasks. +* For simple / single-session tasks. + +#### Sub-Agent Setup Guidelines + +* **Fresh Context Isolation:** When spawning a sub-agent, avoid passing the entire conversation history from the parent agent. Forward only the data directly relevant to the sub-agent's assigned task. + +--- + +### Performance and Flow Configuration + +Avoid exhausting system limits by cluttering the framework with complex sub-agent and skill files for negligible (~1%) performance gains. + +#### Key Principles for Improving Accuracy + +* **Establish Boundaries:** Explicitly instruct the model on what **not** to do. +* **Provide Concrete Commands:** Demonstrate **how** to execute tasks using concrete code snippets and exact commands rather than abstract descriptions. + > *(e.g., Instead of adding "run tests before committing" to the documentation, include the exact test command that must be executed.)* + +LLMs already understand general task workflows. Unless specifying project-specific details that the model cannot infer, avoid overloading it with excessive instructions; otherwise, performance degradation is inevitable. + +> Instead of forcing information onto the LLM, help it find the information. + +--- + +### Documentation File Method + +The use of documentation files such as `architecture.md` or `doc/001_feature.md` was considered, but abandoned due to development budget constraints. + +* These documents must be rewritten with every modified line of code. Failing to update them when code is written or edited creates confusion for humans while causing context poisoning in LLMs, leading the model to hallucinate. + +#### Contributor's Solution + +We can solve this issue by creating a sub-agent named `codebase-explorer` and instructing it on how to search the codebase. This sub-agent can explain the relevant code details to the main agent (orchestrator) based on the requested information. This approach resolves the problem while preventing the main agent's context window from unnecessarily filling up. **@voidvore** + +--- + +## πŸ”„ Note to Maintainers: AI Feedback Loop + +> [!IMPORTANT] +> **Attention Maintainers:** When an LLM-generated error is identified during a PR review, evaluate the following: +> *"Is this a one-off issue specific to this task, or a general error class that the AI might repeat in the future?"* +> +> * **If it is a one-off issue:** Simply request the code fix via a PR comment. +> * **If it is a general error class (Closed Loop):** In addition to the code fix, ask the PR author (or update it yourself) to update the [AGENTS.md](/.agents/AGENTS.md) file within the same PR. +> +> **Sections to Update in AGENTS.md:** +> 1. **Code Standards / Behavioral Rules:** Add the constraint and rationale as a clear rule. +> 2. **Anti-Patterns:** Provide an example of the forbidden code pattern and, if necessary, its correct alternative. \ No newline at end of file diff --git a/.gitignore b/.gitignore index c51ce806..48bf7541 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,12 @@ desktop-extensions/gnome*/*.zip CLAUDE.md AGENTS.md /reference +.opencode + +# .agents is a universal standard for AI tools (Claude, Cursor, opencode, antigravity). +.agents/* +!.agents/AGENTS.md +!.agents/CONTRIBUTING_AGENTS.md *.log From dbd4ff19df5afd186ca274e9cef9ac4bf137f7b6 Mon Sep 17 00:00:00 2001 From: voidvore Date: Wed, 29 Jul 2026 00:11:13 +0300 Subject: [PATCH 2/4] chore(agents): move AGENTS.md to repo root and polish docs - Relocate .agents/AGENTS.md to the repo root (AGENTS.md standard) - Populate the overview table descriptions and add a "What not to do" rule - Fix CONTRIBUTING_AGENTS.md TOC anchors (MD051) and point AGENTS.md links to /AGENTS.md - Drop the obsolete .agents/AGENTS.md negation from .gitignore --- .agents/AGENTS.md | 27 --------------------------- .agents/CONTRIBUTING_AGENTS.md | 14 +++++++------- .gitignore | 1 - AGENTS.md | 31 +++++++++++++++++++++++++++++++ 4 files changed, 38 insertions(+), 35 deletions(-) delete mode 100644 .agents/AGENTS.md create mode 100644 AGENTS.md diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md deleted file mode 100644 index 49eb6e3d..00000000 --- a/.agents/AGENTS.md +++ /dev/null @@ -1,27 +0,0 @@ -# ASUSCTL – AI contributor guide - -ASUSCTL is a Linux utility for controlling ASUS laptop hardware features. - -## Overview - -| Area | Location | Description | -|------|----------|-------------| -| asus-shutdown | `asus-shutdown/` | -| asusctl (CLI) | `asusctl/` | -| asusd (system D-Bus daemon) | `asusd/` | -| asusd-user (user D-Bus daemon) | `asusd-user/` | -| config-traits | `config-traits/` | -| dmi-id | `dmi-id/` | -| rog-platform | `rog-platform/` | -| rog-dbus | `rog-dbus/` | -| rog-anime | `rog-anime/` | -| rog-aura | `rog-aura/` | -| rog-profiles | `rog-profiles/` | -| rog-control-center | `rog-control-center/` | -| rog-slash | `rog-slash/` | -| rog-scsi | `rog-scsi/` | -| simulators | `simulators/` | -| data (service files, udev rules) | `data/` | -| extra (icons, web assets) | `extra/` | -| distro-packaging | `distro-packaging/` | -| CI/CD (GitHub Actions) | `.github/` | \ No newline at end of file diff --git a/.agents/CONTRIBUTING_AGENTS.md b/.agents/CONTRIBUTING_AGENTS.md index 294e0300..561e55be 100644 --- a/.agents/CONTRIBUTING_AGENTS.md +++ b/.agents/CONTRIBUTING_AGENTS.md @@ -7,17 +7,17 @@ ## πŸ“‹ Table of Contents -1. [Why This File Exists](#why-this-file-exists) -2. [Research Findings](#research-findings) +1. [Why This File Exists](#-why-this-file-exists) +2. [Research Findings](#-research-findings) - [1. Instruction File Structure & Impact (Instructions-as-Code)](#1-instruction-file-structure--impact-instructions-as-code) - [2. Rule Polarity & Context Priming (Guardrails vs. Guidance)](#2-rule-polarity--context-priming-guardrails-vs-guidance) - [3. Repository Context Overhead & Minimalist Design (AGENTS.md Evaluation)](#3-repository-context-overhead--minimalist-design-agentsmd-evaluation) - [4. Closed-Loop Review Feedback & Behavioral Rule Accumulation (Self-Improving Agents)](#4-closed-loop-review-feedback--behavioral-rule-accumulation-self-improving-agents) -3. [Contributor Conclusions](#contributor-conclusions) - - [Sub-Agent Usage](#sub-agent-usage) +3. [Contributor Conclusions](#-contributor-conclusions) + - [Sub-Agent Usage and Setup Guidelines](#sub-agent-usage-and-setup-guidelines) - [Performance and Flow Configuration](#performance-and-flow-configuration) - [Documentation File Method](#documentation-file-method) -4. [Note to Maintainers: AI Feedback Loop](#note-to-maintainers-ai-feedback-loop) +4. [Note to Maintainers: AI Feedback Loop](#-note-to-maintainers-ai-feedback-loop) --- @@ -35,7 +35,7 @@ Use `AGENTS.md` to document solutions for recurring issues encountered during LL ## πŸ”¬ Research Findings > [!IMPORTANT] -> Before making changes to the [AGENTS.md](/.agents/AGENTS.md) file, you must thoroughly read or analyze the papers listed below with the assistance of AI to fully understand them. To contribute, feel free to add any new research you find useful to this list. +> Before making changes to the [AGENTS.md](/AGENTS.md) file, you must thoroughly read or analyze the papers listed below with the assistance of AI to fully understand them. To contribute, feel free to add any new research you find useful to this list. ### 1. Instruction File Structure & Impact (Instructions-as-Code) @@ -167,7 +167,7 @@ We can solve this issue by creating a sub-agent named `codebase-explorer` and in > *"Is this a one-off issue specific to this task, or a general error class that the AI might repeat in the future?"* > > * **If it is a one-off issue:** Simply request the code fix via a PR comment. -> * **If it is a general error class (Closed Loop):** In addition to the code fix, ask the PR author (or update it yourself) to update the [AGENTS.md](/.agents/AGENTS.md) file within the same PR. +> * **If it is a general error class (Closed Loop):** In addition to the code fix, ask the PR author (or update it yourself) to update the [AGENTS.md](/AGENTS.md) file within the same PR. > > **Sections to Update in AGENTS.md:** > 1. **Code Standards / Behavioral Rules:** Add the constraint and rationale as a clear rule. diff --git a/.gitignore b/.gitignore index 48bf7541..e74f0c22 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,6 @@ AGENTS.md # .agents is a universal standard for AI tools (Claude, Cursor, opencode, antigravity). .agents/* -!.agents/AGENTS.md !.agents/CONTRIBUTING_AGENTS.md *.log diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..ca7b4802 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# ASUSCTL – AI contributor guide + +ASUSCTL is a Linux utility for controlling ASUS laptop hardware features. + +## Overview + +| Area | Location | Description | +|------|----------|-------------| +| asus-shutdown | `asus-shutdown/` | Shutdown-time applier for deferred ASUS GPU firmware writes | +| asusctl (CLI) | `asusctl/` | Command-line tool for controlling laptop features via asusd | +| asusd (system D-Bus daemon) | `asusd/` | System daemon bridging kernel sysfs/udev to D-Bus interfaces | +| asusd-user (user D-Bus daemon) | `asusd-user/` | User-session daemon for per-user AniMe and RGB control | +| config-traits | `config-traits/` | Shared config load/save traits with versioned migration | +| dmi-id | `dmi-id/` | Hardware detection via SMBIOS/DMI data | +| rog-platform | `rog-platform/` | Sysfs/platform wrapper for ASUS firmware attributes and sensors | +| rog-dbus | `rog-dbus/` | D-Bus proxies and interface definitions for asusd | +| rog-anime | `rog-anime/` | Types and image conversion for the AniMe Matrix display | +| rog-aura | `rog-aura/` | Types for ASUS keyboard RGB (Aura) effects | +| rog-profiles | `rog-profiles/` | Fan-curve and platform-profile management | +| rog-control-center | `rog-control-center/` | Slint-based GUI for all laptop features | +| rog-slash | `rog-slash/` | Types for the ASUS Slash auxiliary display | +| rog-scsi | `rog-scsi/` | SCSI LED controller communication (Arion protocol) | +| simulators | `simulators/` | Hardware simulators for development without real devices | +| data (service files, udev rules) | `data/` | systemd units, udev rules, D-Bus policy, icons | +| extra (icons, web assets) | `extra/` | Application icons and web assets | +| distro-packaging | `distro-packaging/` | Packaging recipes for Arch, RPM, and install scripts | +| CI/CD (GitHub Actions) | `.github/` | CI/CD workflow definitions | + +### What not to do + +- Don't use `--no-verify` or `-n` with `git commit` or `git push`. All commits and pushes must run the git hooks (pre-commit/pre-push) normally. \ No newline at end of file From 7428ca5d4cb3537095949160fed4a0cdd05fe26b Mon Sep 17 00:00:00 2001 From: voidvore Date: Sun, 2 Aug 2026 04:29:08 +0300 Subject: [PATCH 3/4] chore(agents): add release-notes skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds .agents/skills/release-notes/SKILL.md β€” a release lifecycle skill for asusctl. Contents: it summarizes commits, PR descriptions, and touched files into flat CHANGELOG.md entries with PR links (#NN) and contributor thanks (@handle), bumps the [workspace.package] version in Cargo.toml, and runs the release commit/tag/push. Breaking-change analysis and gh release create execution are excluded; the gh command is printed for the maintainer instead. --- .agents/skills/release-notes/SKILL.md | 91 +++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 .agents/skills/release-notes/SKILL.md diff --git a/.agents/skills/release-notes/SKILL.md b/.agents/skills/release-notes/SKILL.md new file mode 100644 index 00000000..773df7eb --- /dev/null +++ b/.agents/skills/release-notes/SKILL.md @@ -0,0 +1,91 @@ +--- +name: release-notes +description: > + Release lifecycle and changelog drafting skill for asusctl. Summarizes + commit messages, PR descriptions, and touched files into flat + CHANGELOG.md entries with PR links (#NN) and contributor thanks (@handle). + Bumps workspace package versioning in Cargo.toml, updates CHANGELOG, and + creates release commits/tags. Excludes breaking change analysis and gh + release create execution. Trigger when drafting release notes, preparing + a new version release, or updating CHANGELOG. +--- + +# asusctl release-notes + +Executes the release workflow: draft notes β†’ decide version β†’ bump Cargo.toml + prepend CHANGELOG β†’ commit & tag β†’ push. + +## DO NOTs & Critical Constraints + +- **NEVER** run `gh release create`. Always print the exact command for the maintainer at the very end. +- **NEVER** request the `commits` field in `gh pr list` (causes a GitHub GraphQL 500k node limit crash). +- **NEVER** run per-PR loops or attempt commit-to-PR SHA/subject matching (rebase-merge rewrites SHAs; `gh` truncates message headlines). +- **NEVER** thank the maintainer cutting the release. Only PR authors(if they authored a PR themselves, they can tag themselves) (`Thanks @handle`) and co-authors listed in PR bodies (`Credits to @handle`). +- **NEVER** credit bots (`dependabot`, `@app/*`). +- **NEVER** copy raw commit subjects verbatim β€” rewrite internal mechanisms into user-visible outcomes. +- **NEVER** proceed if `HEAD..origin/main` is not empty β€” STOP immediately and ask the maintainer to sync (`git pull` / `git rebase`). + +## Step 1 β€” Boundary & Sync Check + +```bash +git fetch origin main +LAST_TAG=$(git tag --sort=-creatordate | head -1) && echo $LAST_TAG +git --no-pager log HEAD..origin/main --oneline +``` +*If `HEAD..origin/main` output is non-empty, STOP and ask the maintainer to sync first.* + +## Step 2 β€” Fetch In-Range PRs (Single Call) + +```bash +TAG_DATE=$(git log -1 --format=%aI "$LAST_TAG") && echo "$TAG_DATE" +gh pr list --repo OpenGamingCollective/asusctl \ + --state merged \ + --search "merged:>$TAG_DATE" \ + --json number,title,author,body,files,baseRefName +``` +*Filter: Keep only PRs where `baseRefName == "main"`.* + +Optional direct commit inventory check: +```bash +git --no-pager log --no-merges "${LAST_TAG}..HEAD" --format='%h|%ae|%s' +``` + +## Step 3 β€” Draft CHANGELOG Entry + +- **Format:** `- : Thanks @handle (#NN)`. +- **Co-authors:** Scan PR `body` for `Credits to @handle` or `thanks @handle` lines. +- **Rollup:** Consolidate pure CI, packaging, test, or refactor changes into 1 summary line (e.g. `Packaging, CI/CD and Issue tracking optimizations: Thanks @a and @b (#228)`). +- **Noise:** Ignore `Release: X.Y.Z` and `chore: update CHANGELOG` commits. +- **Upgrade Notes:** Always Ask the maintainer if existing users need manual action (e.g. post-upgrade autostart file cleanup). If yes, append `### Notes` explaining: **Who is affected / What happens / Action required**. + +## Step 4 β€” Version Selection + +Present a suggestion box(use tool if exists): +1. Next Major (X+1.Y.Z) +2. Next Minor (X.Y+1.Z) +3. Next Patch (X.Y.Z+1) +4. Type your own + +Guidance: New features / device support β†’ Minor; fixes / chores only β†’ Patch. + +## Step 5 β€” Apply Release (Maintainer Approved) + +1. Set `version = "X.Y.Z"` in `Cargo.toml` (`[workspace.package] version`). +2. Prepend `## X.Y.Z` (and optional `### Notes`) to `CHANGELOG.md`. +3. Commit, tag, and push: +```bash +git add Cargo.toml CHANGELOG.md +git commit -m "Release: X.Y.Z" +git tag X.Y.Z +git push origin main && git push origin X.Y.Z +``` + +## Step 6 β€” Instruct Maintainer for GitHub Release + +Print this exact command for the maintainer to execute manually: + +```bash +gh release create X.Y.Z \ + --repo OpenGamingCollective/asusctl \ + --verify-tag \ + --title X.Y.Z +``` \ No newline at end of file From f4af2601a7ffda0a34d2ab3e2b890c4bae30a325 Mon Sep 17 00:00:00 2001 From: voidvore Date: Mon, 3 Aug 2026 21:27:17 +0300 Subject: [PATCH 4/4] docs(contributing): rewrite to match actual project workflow - Removed stale Docker template leftovers (layer, exposed ports, container params) - Replaced fake two-developer sign-off rule with real single-maintainer + squash-merge flow - Dropped non-existent examples/ version-bump rule; versions are maintainer-managed at release - Added verification suite (cargo check/test/clippy/cranky/fmt) - Added Conventional Commits and --no-verify ban - Added supported-distributions policy (Arch-based; Ubuntu out of scope) - Added latest-version retest requirement for bug reports - Added hardware context requirement (model, DMI, kernel, distro, version) - Compressed Code of Conduct to Contributor Covenant 1.4 essentials --- CONTRIBUTING.md | 110 ++++++++++++++++-------------------------------- 1 file changed, 36 insertions(+), 74 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a1cc0cf..f96b6b70 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,92 +1,54 @@ -# Contributing +# Contributing to asusctl -When contributing to this repository, please first discuss the change you wish to make via issue, -email, or any other method with the owners of this repository before making a change. +Thank you for contributing to asusctl. This guide outlines project bounds, issue reporting rules, and the pull request workflow. -Please note we have a code of conduct, please follow it in all your interactions with the project. +## Project scope and support bounds -## Pull Request Process - -1. Ensure any install or build dependencies are removed before the end of the layer when doing a - build. -2. Update the README.md with details of changes to the interface, this includes new environment - variables, exposed ports, useful file locations and container parameters. -3. Increase the version numbers in any examples files and the README.md to the new version that this - Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. +### Scope +The goal of this project is making ASUS hardware usable under Linux. -## Code of Conduct +### Supported distributions +Arch Linux and Arch-based distributions are officially supported. Issues specific to unsupported distributions like Ubuntu may be closed without investigation due to maintainer time constraints. -### Our Pledge +## Reporting issues -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. +### Test on the latest version +Always test against the latest release or current `main` branch before submitting a bug report. Issues opened against older versions will be asked to retest. -### Our Standards +### Include hardware context +Include your laptop model, DMI board name, kernel version, distribution name, and exact asusctl version in your report. -Examples of behavior that contributes to creating a positive environment -include: +## Pull request workflow -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +### Before starting +For significant changes, open an issue or discuss your proposed design in the Discord server first. This prevents duplicate effort and ensures compatibility with daemon components. -Examples of unacceptable behavior by participants include: +### Commit standards +- Follow Conventional Commits format for commit titles (for example, `fix(rog-platform): resolve sysfs node parsing` or `refactor(asusctl): modularize cli handlers`). +- Do not use `--no-verify` or `-n` to bypass git hooks. All commits and pushes must run repository hooks normally. -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting +### Verification suite +Run these checks before submitting your pull request: +- `cargo check --all-targets` +- `cargo test --all` +- `cargo clippy --workspace --all-targets --all-features -- -D warnings` +- `cargo cranky` +- `cargo fmt --all -- --check` -### Our Responsibilities +### Submitting a PR +- Fill out the pull request template completely, including tested hardware details and verification steps. +- Do not bump workspace or package versions in `Cargo.toml`. Version updates are managed by maintainers during releases. +- Link related issues using standard keywords such as `Fixes #123` or `Supersedes #456`. -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +## Code of conduct -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +### Our pledge +We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity. -### Scope +### Standards +Positive behaviors include using inclusive language, respecting differing viewpoints, accepting constructive criticism, and focusing on community well-being. -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. +Unacceptable behaviors include sexualized language or imagery, trolling, derogatory comments, personal attacks, public or private harassment, and publishing private information without explicit consent. ### Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at luke@ljones.dev. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -### Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +Maintainers enforce these standards and may remove comments, reject code, or ban contributors who violate them. Report violations to project maintainers or contact `luke@ljones.dev`. All complaints are reviewed confidentially. \ No newline at end of file