在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

tldr-pages/tldr

菜单

贡献 TLDR Pages

相关源文件

本指南介绍了如何通过创建新页面、更新现有页面或翻译内容来为 tldr-pages 项目做出贡献。它涵盖了从初始设置到成功提交拉取请求的整个工作流程。有关项目的治理和社区角色信息，请参阅项目治理和社区角色。

贡献流程概述

TLDR 页面以简单的 Markdown 格式编写，每个页面记录一个特定的命令。可以通过 GitHub 贡献，使用 Web 界面或命令行 Git 均可。

来源：CONTRIBUTING.md20-54 README.md98-119

页面结构和格式

TLDR 页面采用特定的格式，包含简洁的示例。每个页面包含标题、描述和最多 8 个命令示例。格式必须遵循项目的风格指南。

基本页面格式

每个页面必须

  • 以命令名作为标题（前面加上 #）
  • 有一个简洁的描述（行以 > 开头）
  • 包含一个指向官方文档的“更多信息”链接
  • 包含示例（每个示例都带有描述和命令）
  • 在 {{双花括号}} 中使用占位符表示用户提供的值

格式良好的页面示例

来源：contributing-guides/style-guide.md15-35 contributing-guides/style-guide.md246-255 CONTRIBUTING.md82-100

创建新页面

创建新页面时，请遵循以下步骤

  1. 检查页面是否已存在
  2. 确定正确的平台目录（common、linux、windows、osx 等）
  3. 使用命令名创建新的 Markdown 文件
  4. 按照风格指南格式化页面
  5. 在本地测试页面
  6. 提交拉取请求

来源：CONTRIBUTING.md55-67 contributing-guides/style-guide.md111-148

翻译页面

翻译是为 tldr-pages 做出贡献的宝贵方式。翻译时，您必须

  1. 确保英文页面首先存在
  2. 在正确的语言目录中创建页面（pages.{locale}）
  3. 保持与英文页面相同的结构
  4. 遵循特定语言的格式规则

特定语言的目录遵循 pages.{locale} 模式，其中 locale 是一个POSIX Locale Name，例如 fr 或 pt_BR。

来源：CONTRIBUTING.md172-197 contributing-guides/translation-templates/common-arguments.md contributing-guides/translation-templates/alias-pages.md

本地测试页面

在提交贡献之前，请使用 tldr-lint 工具在本地测试您的页面

  1. 安装 tldr-lint: npm install --global tldr-lint
  2. 在您的页面上运行 Linter: tldr-lint path/to/page.md
  3. 修复所有报告的问题

您也可以预览页面将如何显示

来源：CONTRIBUTING.md208-223 contributing-guides/style-guide.md70-86

提交贡献

您可以通过 GitHub 的 Web 界面或使用命令行 Git 进行贡献。

使用 GitHub 的 Web 界面

  1. 找到您想要编辑的文件，或者想要创建新文件的地方
  2. 点击编辑按钮（铅笔图标）或“添加文件”按钮
  3. 进行您的更改
  4. 在底部，提供一个描述性的提交消息
  5. 点击“提议更改”或“提议新文件”
  6. 点击“创建拉取请求”

使用命令行 Git

对于提交消息和 PR 标题，请使用格式：command: type of change

例如：tar: add example for creating tar.xz archives

来源：CONTRIBUTING.md205-242 contributing-guides/git-terminal.md1-45

评审流程

提交拉取请求后，会发生以下情况

  1. 自动 CI 测试运行，以检查格式和风格
  2. 协作者审查您的贡献
  3. 可能会要求您进行更改
  4. 获得批准后，维护者将合并您的 PR

来源：.github/workflows/ci.yml1-66 scripts/test.sh1-50 MAINTAINERS.md15-250

风格指南和最佳实践

在创建或编辑页面时，请牢记以下关键指南

  1. 页面保持约 5 个示例（最多 8 个）
  2. 注重清晰度而非简洁性
  3. 包含单字母选项的完整拼写
  4. 逐步引入选项，从简单到复杂
  5. 关注命令本身的细节，而非通用的 UNIX 概念
  6. 所有描述都使用祈使语气
  7. 使用正确的占位符：{{path/to/file}}，{{arg_value}}
  8. 优先使用长选项（--help 而非 -h）

来源：contributing-guides/style-guide.md246-266 contributing-guides/style-guide.md434-475 CONTRIBUTING.md35-49

特殊页面类型

子命令

对于带有子命令的命令（例如 git commit, git push），请为每个子命令创建单独的页面，使用连字符

git-commit.md
git-push.md

然后在主页面中添加对这些子命令的引用

来源：CONTRIBUTING.md130-171 contributing-guides/translation-templates/subcommand-mention.md1-49

别名页面

对于其他命令的别名命令，请创建一个别名页面

来源：contributing-guides/style-guide.md121-146 contributing-guides/translation-templates/alias-pages.md1-64

获取帮助

如果您在贡献过程中需要帮助

  1. 请查阅style guide以获取详细的格式指南
  2. 加入Matrix 聊天室提问
  3. 参考现有页面以获取示例和指导

来源：README.md119 CONTRIBUTING.md53-54

治理与认可

定期贡献者可能会被邀请成为存储库的协作者，并最终成为 tldr-pages 组织的成员，请遵循Community Roles 文档中的指南。

来源：MAINTAINERS.md9-14 COMMUNITY-ROLES.md28-63