v2.1.0

Release Notes: v2.1.0

Release Date: 2026-06-29
发布日期： 2026-06-29

This release introduces a comprehensive assembler style linter for RISC-V assembly code validation, a new self-upgrade feature (-update flag) with custom update server configurations, and improved CI/CD linting capability by returning a non-zero exit code when formatting differences are detected.

---

English Version

1. Assembler Style Linter (NEW)

• Comprehensive Linter Subsystem: Added a complete code style linter that validates assembly code against best practices and style guidelines. Includes 30+ configurable rules organized into three categories: RISC-V specific (L1xx), Generic GAS (L2xx), and Structure/Formatting (L3xx). (commit a8c7289)
• RISC-V Specific Rules: Enforces ABI register naming, bans compressed instructions, validates relocation operator spacing, ensures GP load relaxation, and checks CSR naming conventions. (commits a8c7289)
• Generic GAS Rules: Enforces alignment directive usage, bans redundant directives, validates operator precedence, and checks symbol declaration patterns. (commits a8c7289)
• Inline Control Comments: Added support for per-line and per-file inline comment directives to selectively disable lint rules using // asmfmt-disable-next-line L101 or /* asmfmt-disable-line L101 */ syntax. Supports both C++ and assembly comment styles. (commits c632eb2, 91def2b)
• Copyright & SPDX Validation: Added copyright_require_spdx and copyright_format options to validate copyright headers and SPDX license identifiers. (commit 8b6ff02)
• Declarative Macros Support: Added declarative_macros config option to handle custom macros as directives for rule validation. (commit 229e2b1)

2. Bug Fixes

• Unreachable Code Detection: Fixed false positives for empty lines in rule L313, preventing blank lines from triggering unreachable code warnings. (commit feda76a)
• Instruction Termination Reporting: Fixed reporting of un-terminated sequences to point to the exact instruction line rather than the end of the function. (commit ff17d26)
• GAS Directive Indentation: Fixed .extern directive indentation when GAS directive config is enabled. (commit 0de823a)

3. In-Place Self-Upgrade Feature

• Self-Upgrade CLI Flag: Added the -update <target> CLI option to upgrade the asmfmt binary in-place to the latest version, a beta build, or a specific Release Tag (e.g. v2.1.0). (commit 60f8fb6)
• Custom Environment Overrides: Added support for overriding the upgrade repository via ASMFMT_UPGRADE_REPO (defaults to Mi-AIoT/asmfmt) and the GitHub API base URL via ASMFMT_UPDATE_URL (defaults to https://api.github.com), facilitating local tests and custom mirror usages. (commits 60f8fb6, b05cd38)

4. CI Verification Enhancements

• Non-Zero Exit Code on Diff: Updated the -d (diff) and -l (list files) flags to return a non-zero exit code (1) when any formatting differences are detected. This simplifies integration check steps in CI environments without requiring log parsing wrappers. (commit 15ec8fd)
• Exit Code Test Coverage: Added integration tests to verify successful/failed exit code behavior for -d, -l, -w and standard output modes under formatting differences. (commit 15ec8fd)

5. CI/CD & Build Improvements

• Exclude Non-v Tags from Snapshot Versioning: Deletes non-v-prefixed local tags (such as beta) before running GoReleaser in snapshot builds, ensuring that automated master branch beta releases retrieve the latest v-prefixed semantic version (e.g., v2.0.0-next instead of beta-next). (commit bc0c12d)
• Automated Release Notes for Beta Builds: Configured the beta release pipeline to automatically generate release notes using GitHub Releases API to show changes since the last tag. (commit 06f528e)
• Dynamic Custom Release Notes: Added capability to dynamically fetch release notes by checking for custom files at build time. (commit 98fbf48)

6. Bilingual Documentation

• Lint Rules Manual: Created comprehensive documentation for all 30+ style linter rules in both English (docs/lint_rules.md) and Chinese (docs/lint_rules_zh.md). (commits e4135d5, bcf6ab3, cb8d1e6, 042b1f6, 2cb48ff)
• Manual & README Updates: Documented the -update flag, exit code behavior changes, and environment variables bilingually in English and Chinese manuals (docs/user_manual.md, docs/user_manual_zh.md) and project READMEs. (commits 29f83c5, b05cd38)
• Development Guidelines: Updated AGENTS.md guidelines to specify that both English and Chinese versions of documentation must be updated concurrently whenever changes are made. (commits 29f83c5, 29f83c5)

---

中文版说明 (Chinese Version)

本版本为 asmfmt 引入了全新的汇编代码风格检查器、自更新功能（-update 选项），并支持自定义更新服务器配置。同时，本版本通过在检测到文件格式不一致时返回非零退出码，极大地增强了工具在 CI/CD 静态校验环境中的集成易用性。

1. 汇编代码风格检查器（新增）

• 完整 Linter 子系统: 新增完整的代码风格检查器，用于验证汇编代码是否符合最佳实践和风格指南。包含 30+ 条可配置规则，分为三大类：RISC-V 专用规则 (L1xx)、通用 GAS 规则 (L2xx) 和结构/格式规则 (L3xx)。(commit a8c7289)
• RISC-V 专用规则: 检查 ABI 寄存器命名、禁止压缩指令、验证重定位操作符间距、确保 GP 寄存器加载时的松弛选项、检查 CSR 命名约定等。(commits a8c7289)
• 通用 GAS 规则: 检查对齐指令用法、禁止冗余指令、验证运算符优先级、检查符号声明模式等。(commits a8c7289)
• 内联控制注释: 支持使用内联注释指令逐行或逐文件选择性禁用规则，如 // asmfmt-disable-next-line L101 或 /* asmfmt-disable-line L101 */ 语法。支持 C++ 和汇编注释风格。(commits c632eb2, 91def2b)
• 版权与 SPDX 验证: 新增 copyright_require_spdx 和 copyright_format 选项，用于验证版权头和 SPDX 许可证标识符。(commit 8b6ff02)
• 声明式宏支持: 新增 declarative_macros 配置选项，将自定义宏作为指令处理以进行规则验证。(commit 229e2b1)

2. Bug 修复

• 不可达代码检测: 修复了 L313 规则中空行导致的误报问题，防止空行触发不可达代码警告。(commit feda76a)
• 指令终止报告: 修复了未终止指令序列的报告位置，现在会指向准确的指令行而非函数末尾。(commit ff17d26)
• GAS 指令缩进: 修复了启用 GAS 指令配置时 .extern 指令的缩进问题。(commit 0de823a)

3. 就地自更新功能

• 命令行自更新标志: 新增 -update <target> 命令行选项，支持就地在线将 asmfmt 二进制文件升级到 latest（最新发布版）、beta（测试版）或指定的 Release Tag（如 v2.1.0）。(commit 60f8fb6)
• 环境变量自定义配置: 升级功能支持使用 ASMFMT_UPGRADE_REPO（默认为 Mi-AIoT/asmfmt）覆盖更新仓库源，以及使用 ASMFMT_UPDATE_URL（默认为 https://api.github.com）覆盖 GitHub API 地址，从而允许指向本地测试服务器或企业镜像源。(commits 60f8fb6, b05cd38)

4. CI 格式校验集成增强

• 格式差异返回非零退出码: 更新了 -d（输出 diff 补丁）和 -l（仅列出差异文件）参数的行为。当检测到任何文件的排版格式与 asmfmt 标准不一致时，工具将以状态码 1 退出。这允许 CI 静态检查流水线直接阻断不合规的提交，而无需再依赖额外的日志文本过滤脚本。(commit 15ec8fd)
• 退出状态码测试覆盖: 编写了完整的集成测试，全面验证了在存在格式差异时，-d、-l、-w 和标准输出模式下的正确/失败退出状态码表现。(commit 15ec8fd)

5. CI/CD 构建优化

• 排除非 v 开头标签干扰快照版本号: 在构建测试版快照时，CI 流水线会在本地自动清除如 beta 这样非 v 开头的标签，以确保 GoReleaser 能够基于最新版本的正式 v 标签（如 v2.0.0）生成快照版本号（例如 v2.0.0-next，而非 beta-next）。(commit bc0c12d)
• Beta 构建自动生成 Release Note: 优化了 Beta 发布流程，启用 GitHub 自动 Release Note 接口，自动检索并呈现自上一个版本以来的 Commits 和 PRs。(commit 06f528e)
• 动态自定义 Release Notes: 增加了在 CI 阶段动态检测并载入自定义发布日志的脚本逻辑。(commit 98fbf48)

6. 双语文档与规范

• Linter 规则手册: 为所有 30+ 条风格检查规则创建了完整的中英文文档（docs/lint_rules.md 和 docs/lint_rules_zh.md）。(commits e4135d5, bcf6ab3, cb8d1e6, 042b1f6, 2cb48ff)
• README 及用户手册更新: 同步更新了中英文的 README 及用户手册（docs/user_manual.md、docs/user_manual_zh.md），详尽阐述了自更新标志、退出码变更和相关环境变量的使用方法。(commits 29f83c5, b05cd38)
• 仓库开发指南完善: 完善了 AGENTS.md 中的开发流程规范，规定每次更新文档时，必须同时更新中文和英文版本。(commits 29f83c5, 29f83c5)

Beta / Nightly Build

This is an automated pre-release build of the master branch.

It is automatically built and updated on every successful commit to master.

Commit: f94c93d

---

Changes since v2.1.0:

• f94c93d: docs(release): add beta release timestamp fix to v2.2.0 release notes
• 5225c28: ci: fix beta release timestamp by deleting existing release before re-creation
• e80dfe0: docs(release): update v2.2.0 release notes with CI/CD improvements
• 97c4531: ci: include commit history and release notes in beta releases
• 12e9d02: ci: add tag validation and concurrency control to workflows
• f5af748: docs: add release process guidelines to AGENTS.md
• 835b32c: docs(release): add v2.2.0 release note template (in development)

---

English Version

CI/CD Workflow Improvements

• Release Tag Validation: Added validation to ensure release tags follow semantic version format (vX.Y.Z) and rejects non-version tags to prevent accidental releases. (commit 12e9d02)
• Beta Release Concurrency Control: Added concurrency control to beta deployment workflow to prevent race conditions when multiple master pushes occur simultaneously. (commit 12e9d02)
• Enhanced Beta Release Notes: Beta releases now automatically include:
  • Commit history since latest release tag in hash: message format
  • Latest development release notes from docs/ directory
    Provides full visibility into all changes in development. (commit 97c4531)
• Beta Release Timestamp Fix: Fixed beta release timestamp not updating by deleting existing release before creating a new one. This ensures GitHub displays the correct updated timestamp instead of the original creation time. (commit 5225c28)
• Release Process Documentation: Added comprehensive release process guidelines to AGENTS.md covering:
  • Release note location, naming conventions, and bilingual format
  • Development vs released status tracking
  • Bilingual documentation requirements
  • Post-release workflow procedures. (commit f5af748)

Documentation

• Release Process Guidelines: Documented standard release workflow, tag validation requirements, and documentation synchronization rules. (commit f5af748)

---

中文版说明 (Chinese Version)

CI/CD 工作流改进

• Release Tag 验证: 新增 tag 格式验证，确保 release tag 遵循语义化版本格式 (vX.Y.Z)，拒绝非版本标签以防止意外发布。(commit 12e9d02)
• Beta Release 并发控制: 新增 beta 部署工作流的并发控制，防止多个 master 推送同时发生时的竞态条件。(commit 12e9d02)
• 增强的 Beta Release Notes: Beta releases 现在自动包含：
  • 自最新 release tag 以来的 commit 历史，格式为 hash: message
  • docs/ 目录中的最新开发中 release notes
    提供开发中所有更改的完整可见性。(commit 97c4531)
• Beta Release 发布时间修复: 修复 beta release 发布时间不更新的问题。通过在创建新 release 前先删除现有的 beta release，确保 GitHub 显示正确的更新时间而非原始创建时间。(commit 5225c28)
• Release 流程文档: 在 AGENTS.md 中添加了全面的 release 流程指南，涵盖：
  • Release note 位置、命名约定和双语格式
  • 开发中 vs 已发布状态跟踪
  • 双语文档要求
  • 发布后工作流程序。(commit f5af748)

文档

• Release 流程指南: 记录了标准 release 工作流、tag 验证要求和文档同步规则。(commit f5af748)

Full Changelog: v2.1.0...beta

v2.0.0

Release Notes: v2.0.0

This release marks a major milestone for asmfmt. Moving beyond the upstream v1.3.2 codebase, v2.0.0 introduces comprehensive GNU Assembler (GAS) and RISC-V syntax support, a highly customizable TOML configuration engine, semantic equivalence verification, and pre-built release automation.

---

English Version

1. GNU Assembler (GAS) & RISC-V Support

• RISC-V GAS Formatter: Complete formatting coverage for RISC-V oriented assembly written in GAS syntax. (commit c78a973)
• Expanded GAS Directives: Full support for .section, .attribute, .option, .insn, CFI directives (e.g. .cfi_startproc, .cfi_endproc), data directives, and relocation helpers. (commit 8510ddd)
• Advanced Comment Parsing: Added support for GAS-specific comment markers: #, //, block comments (/* ... */), and ARM/GAS @ line comments. (commit 2e6b81a)
• Macro Preservation: Robust support for GAS macro blocks (.macro, .irp, .irpc, .rept, .if, .else), preventing formatting from corrupting or flattening lines inside macro bodies. (commit bdf6146)

2. Extensible TOML Configuration Support

• Project-Level .asmfmt.toml & Config Discovery: Read formatting options from a TOML configuration file. Supports automatic configuration resolution walking upward from the file's directory, falling back to ~/.asmfmt.toml and /etc/asmfmt.toml. (commit 169de5e)
• New Layout Options: Added new formatting configuration parameters including:
  • indent_style / indent_width: Customize tabs or spaces for indentation.
  • align_operands / align_comments: Toggle alignment for operands and comments.
  • align_continuations: Toggle alignment for trailing \ continuation lines in macros.
  • max_blank_lines: Control consecutive blank lines to preserve.
  • source_style: Force formatting parser style (auto, plan9, gas, riscv-gas).
  • indent_gas_directives: Indent zero-indent GAS directives to code level. (commit ce13a2f)

3. Layout & Indentation Fixes

• Refactored Comment Alignment: Comment alignment in GAS mode is now calculated only against lines containing comments. This prevents long comment-less lines (like macro definitions) from pushing comments on other lines far to the right. (commit 3f0b272)
• Preprocessor Block Alignment: Restored correct indentation levels inside C-preprocess #if / #else / #endif blocks. (commits ca543bf, 2df112b)
• Preserve Local Directives: Fixed issues where zero-indent GAS directives inside macros or blocks were incorrectly de-indented. (commit 3614359)

4. CLI & Developer Tooling

• -init Flag: Automatically generate a default .asmfmt.toml configuration template in the current directory. (commit eabca18)
• -version Flag & Usage Header: Display version number, git hash, and build time (with automatic fallback to Go VCS build info). (commits f054a9e, ac34d8b)
• -cpuprofile Clarification: Updated flag description to specify debugging/profiling intent. (commit 8d65678)
• Makefile Integration: Added a root Makefile for streamlined building, testing, linting, and formatting. (commit ffa452d)

5. Documentation & Automated CI

• Structured Manuals: Added comprehensive English and Chinese user manuals (docs/user_manual.md, docs/user_manual_zh.md) covering all configurations and editor setups. (commits cb8cbf0, 8609047)
• Semantic Verification: Integrated RISC-V assembler binutils (as & objdump) semantic equivalence testing in CI, guaranteeing that formatting changes do not alter compile-time binary output. (commit cbba8d0)
• Pre-built Beta Releases & CI Checkout Fix: Automated GitHub Actions to compile and release pre-built snapshots of the master branch to the beta tag, fixing deep tag checkouts. (commits 3419687, 2ec9140)

---

中文版说明 (Chinese Version)

本版本是 asmfmt 维护分支的一个里程碑版本。相比于上游官方 v1.3.2 版本，v2.0.0 引入了对 GNU 汇编（GAS）和 RISC-V 语法的全面支持、高可定制性的 TOML 配置引擎、语义等价性自动化校验以及预构建发布流程。

1. GNU 汇编 (GAS) 与 RISC-V 语法支持

• RISC-V GAS 格式化: 针对以 GAS 语法编写的 RISC-V 汇编代码提供了完整的格式化覆盖。(commit c78a973)
• 扩展 GAS Directive: 完整支持 .section、.attribute、.option、.insn、CFI 指令（如 .cfi_startproc、.cfi_endproc）、数据定义指令和重定位辅助指令。(commit 8510ddd)
• 高级注释解析: 增加了对 GAS 专属注释标记 #、//、块注释（/* ... */）以及在检测为 GAS 格式时 ARM/GAS 风格的 @ 行注释支持。(commit 2e6b81a)
• 宏代码块保护: 对 GAS 宏指令块（.macro、.irp、.irpc、.rept、.if、.else 等）提供了稳健的解析保护，防止格式化破坏或折叠宏体内的代码结构。(commit bdf6146)

2. 灵活的 TOML 配置支持

• 项目级 .asmfmt.toml 与配置自动查找: 支持从 TOML 配置文件中读取特定格式化规则。运行时自动从当前格式化文件目录向上逐级查找 .asmfmt.toml，并支持 fallback 到用户主目录 ~/.asmfmt.toml 和系统目录 /etc/asmfmt.toml。(commit 169de5e)
• 丰富的新增排版选项: 新增的一系列格式化控制选项包含：
  • indent_style / indent_width：自定义使用 tab 还是空格缩进及空格数量。
  • align_operands / align_comments：开关操作数和行尾注释对齐。
  • align_continuations：控制宏多行拼接符 \ 的右对齐。
  • max_blank_lines：最大连续保留空行数。
  • source_style：强制指定解析器语法风格（auto、plan9、gas、riscv-gas）。
  • indent_gas_directives：控制是否将原零缩进的 GAS directive 缩进对齐到代码层级。(commit ce13a2f)

3. 排版与缩进修复

• 优化注释对齐: 在 GAS 模式下，行尾注释的对齐位置只根据含有注释的行计算，防止未包含注释的长代码行（如宏定义）将其他行的行尾注释强行推至极右侧。(commit 3f0b272)
• 预处理块对齐: 修复了 C 语言预处理 #if / #else / #endif 内部代码行对齐失效的问题，能够正确维持并恢复缩进层级。(commits ca543bf, 2df112b)
• 保留局部指令缩进: 修复了宏或局部代码块内部零缩进 GAS 指令被错误取消缩进的排版缺陷。(commit 3614359)

4. 命令行与开发工具链

• -init 选项: 支持在当前目录下自动生成带完整选项注释的默认 .asmfmt.toml 模板配置文件。(commit eabca18)
• -version 选项与使用说明标头: 命令行输出版本号、Git Hash 和编译时间（支持 Go VCS 信息自动回退解析）。(commits f054a9e, ac34d8b)
• -cpuprofile 描述优化: 优化了帮助说明，明确说明该选项仅供开发调试和大规模格式化性能调优使用。(commit 8d65678)
• Makefile 集成: 新增根目录 Makefile，方便开发者进行本地构建、测试、格式化与静态检查。(commit ffa452d)

5. 完善的文档与 CI/CD 构建

• 中英文用户手册: 编写了详尽的中英文用户手册（docs/user_manual.md、docs/user_manual_zh.md），解耦并简化了 README，提供了配置详解及主流编辑器集成指南。(commits cb8cbf0, 8609047)
• 语义等价性校验: CI 流程中引入了基于 RISC-V 交叉编译工具链（as 和 objdump）的语义等价性自动化校验，保障格式化操作绝对不改变编译出的机器码。(commit cbba8d0)
• Beta 版本自动发布及构建源历史修复: 每次向 master 分支推送代码且 CI 跑通后，会自动将多平台预构建二进制产物发布并更新到 beta 预发布标签下，修复了浅拉取带来的版本号错误问题。(commits 3419687, 2ec9140)