跳到正文
GitHub Blog· Jan Maarten·· 12 天前精选AI 评分44

GitHub 在仓库首页识别 ACCESSIBILITY.md 无障碍声明文件

Accessibility statements now have a home on GitHub

AI 导读

GitHub 现在识别仓库根目录、.github/ 或 docs/ 目录下的 ACCESSIBILITY.md,并在仓库概览页显示,也可从组织的 .github/ 仓库继承。

变化判断

GitHub 在仓库首页识别 ACCESSIBILITY.md,维护者可在 Insights 的 Community Standards 里生成起始文档,无障碍信息从散落的 issue 和审计报告收进一个固定位置。

正文 · AI 翻译

无障碍相关的工作往往散落在问题追踪器、贡献指南、审计报告、团队知识和与用户的对话里。这些信息没有固定的存放位置,遇到障碍的人就得自己去翻找,而随着贡献者和项目归属的变动,维护者也会丢失上下文。

现在,仓库概览页面上会显示 ACCESSIBILITY.md 文件,让项目有一个长期固定的地方,说明其无障碍目标、对贡献者的期望、支持的环境、已知限制以及报告障碍的流程。

GitHub 让无障碍声明更容易被找到

GitHub’s Community Standards page under Insights, showing an Accessibility card under “Additional community file” with an Add button for creating a statement.

GitHub 现在能识别仓库根目录、.github/ 目录或 docs/ 目录下的 ACCESSIBILITY.md 文件。仓库也可以继承其组织 .github/ 仓库中的声明。对于公开仓库,维护者可以在 Insights > Community Standards 中,使用一份简洁的入门文档来添加或提议声明。

GitHub 的社区健康文件帮助人们了解项目如何运作:

  • 贡献指南说明如何提出更改
  • 行为准则确立参与规范
  • 安全策略说明如何报告漏洞

识别 ACCESSIBILITY.md 让无障碍信息在这些指引之外有了专门的存放位置。

新仓库默认还会包含一个 accessibility 问题标签。声明会说明如何报告障碍以及后续会怎样,而这个标签帮助维护者整理和跟踪由此产生的工作。

无障碍声明让项目实践变得可见

例如,GitHub CLI 的无障碍声明记录了设置、已知障碍和变通方法。它解释了为什么表格输出对屏幕阅读器来说可能难以理解,并提供了一个命令,改为每行打印一个拉取请求编号和标题。它还要求修改提示词或输出的贡献者在启用相关无障碍设置的情况下展示结果。使用 CLI 的开发者得到了具体的变通方法;为它做贡献的开发者则对自己的更改有了明确的预期。

GitHub Annotation Toolkit 的无障碍声明记录了其 Figma 库的一项限制:注释使用画布位置、连接线和匹配编号来直观传达关系。单独访问各个画布对象,并不一定能说明这些关系是什么。

声明为协作者提供了一个具体的替代方案:提供结构化的文本描述,标明每个被注释的元素、其预期的语义和行为,以及任何相关的顺序。对于准备或接收设计交接的开发者来说,这说明了视觉注释需要附带哪些信息。

该文件还说明了如何报告无障碍障碍,并明确表示该库尚未经过仅键盘或屏幕阅读器测试。读者既能得到实用指引,也能清楚知道项目验证过什么、没验证过什么。把这些信息展示在仓库概览中,更容易与项目的其他文档一起被找到。

GitHub’s file editor displaying the ACCESSIBILITY.md starter template, with instructions for documenting accessibility priorities, contributor expectations, and how to report barriers.

记录项目能够维护的内容

ACCESSIBILITY.md 文件没有固定格式。小型库、命令行工具、文档站点和大型 Web 应用有着不同的用户、风险和維護能力。从项目能够保持准确的真实信息开始。

  • 优先级和目标:解释无障碍为什么对项目重要,以及哪些用户体验会受到关注。
  • 对贡献者的期望:说明变更需要满足哪些无障碍检查、提供哪些证据或经过哪些评审流程,并给出面向人类贡献者和编程智能体的操作指引。
  • 报告无障碍障碍:提供一条直接、无障碍的报告渠道。不要要求报告者披露残障情况,也不要强制提供截图或录屏。
  • 响应流程:说明维护者如何确认、分类、跟踪无障碍问题并就此沟通。如果项目使用严重程度分级,让维护者在分类阶段自行分配或确认级别。
  • 支持的环境:列出项目支持或已测试的平台、浏览器、输入方式和辅助技术。
  • 已知限制:从受影响体验的角度描述障碍,给出可用的变通方案,并链接到已跟踪的修复工作。
  • 归属与维护:指明由哪个团队、角色或维护者负责让这份声明及相关实践保持最新。
  • 反馈与改进:说明用户和贡献者可以如何就这份声明或项目的无障碍实践提出修改建议。

请注意,项目可以把某个版本的《Web 内容无障碍指南》及其级别定为目标。目标并不等于经过验证的符合性。符合性声明需要经过评估,并应说明评估范围、日期、方法和评估者。

最有用的 ACCESSIBILITY.md 文件包含什么

最有用的无障碍声明,服务的是那些在问题已经发生之后才找上门来的人。通俗的语言、描述清楚的链接和明确的报告途径,比法律条文或标准术语堆砌更重要。

有用的报告指引会邀请报告者提供相关背景,例如受影响的任务、页面、观察到的行为、浏览器、操作系统和辅助技术。它把截图和录屏设为可选,也避免要求别人证明自己存在残障。

声明还应设定维护者能够持续兑现的预期,可以包括确认收到、状态更新、可用变通方案、预计时间线,以及让报告者验证修复结果的机会。

从示例入手,再按需调整

Open Source Accessibility Toolkit 提供了一个详细的公开示例。

GitHub 的社区标准工作流提供了一个更简短的起步模板,其中的提示语可以由项目替换为自己的信息。目标不是在发布文件之前先写出一份完美的政策。先写准确的信息,点明缺口,再随着项目无障碍实践的成熟不断更新声明。

添加无障碍声明能让无障碍工作更容易被用户、贡献者和维护者发现。让这一做法在开源项目中成为常态,有助于把无障碍融入社区规划、构建、报告和改进工作的方式之中。

为你的仓库添加无障碍声明 >

文章 Accessibility statements now have a home on GitHub 最早发布于 The GitHub Blog。

来源:GitHub Blog · github.blog