贡献指南

目的与范围

本文档概述了为免费编程书籍仓库贡献的指南和流程。这些指南旨在确保所有资源列表的一致性、质量和易于维护。它们适用于所有贡献，无论是添加新资源、更新现有资源还是协助翻译。

有关创建和提交拉取请求的具体过程，请参阅拉取请求流程。有关自动化质量控制系统的详细信息，请参阅质量控制系统。

来源：.github/PULL_REQUEST_TEMPLATE.md1-24 docs/CONTRIBUTING-hi.md12-16

贡献工作流程

贡献过程遵循标准的 GitHub 工作流，并包含此仓库特有的额外质量控制步骤。

贡献流程图

来源：.github/workflows/fpb-lint.yml1-37 .github/workflows/comment-pr.yml1-56 docs/CONTRIBUTING-hi.md12-30

贡献要求

所有对仓库的贡献都必须满足特定标准，以确保质量和一致性

仅限免费内容：资源必须是完全免费的，不得有付费墙或要求提供有效电子邮件地址
适当的资源类型：贡献必须符合支持的资源类别之一
正确的格式：所有贡献都必须遵循格式指南
无重复：该资源不应已被列出（请使用搜索功能）
完整信息：包括作者、平台和适当的指示符

资源类别

该仓库分为六种主要类型的资源，每种都有特定的要求

来源：docs/CONTRIBUTING-hi.md18-25

格式指南

所有贡献都必须遵循特定的格式规则，以保持仓库内的一致性。

基本格式结构

* [Resource Title](http://example.com/resource) - Author Name (Format Indicator)

关键要素:

元素	描述	示例
资源标题	资源的原始标题	`Python 入门`
URL	资源的直接链接	`http://example.com/python-intro`
作者	资源的创建者	`Jane Smith`
格式指示符	括号中的资源格式	`(PDF)`, `(HTML)`
特殊说明	附加信息	`(:construction: 进行中)`

文件结构规则

列表以索引部分开始
主章节使用三级标题（###）
子章节使用四级标题（####）
所有列表必须按字母顺序排列
最后一个链接和新章节之间留2个空行
标题和第一个链接之间留1个空行
链接之间留0个空行
每个文件末尾留1个空行

来源：docs/CONTRIBUTING-hi.md57-69 docs/CONTRIBUTING-hi.md94-116

按字母顺序排列

仓库要求所有资源在其章节内按字母顺序排列

以相同字母开头的条目按第二个字母的顺序排列，依此类推
one two 位于 onetwo 之前（字符前的空格）

正确排序示例:

* [Advanced Python Programming](http://example.com/advanced)
* [Basic Programming Concepts](http://example.com/basic)
* [Python for Beginners](http://example.com/beginners)
* [Python Pro Tips](http://example.com/protips)

自动化代码检查将检查正确的字母排序并标记任何问题。

来源：docs/CONTRIBUTING-hi.md156-162

质量控制系统

该仓库采用自动化质量控制系统，以确保所有贡献都符合所需标准。

质量控制流程图

自动化代码检查工具（free-programming-books-lint）检查以下内容：

正确的字母排序
正确的 Markdown 格式
是否遵循间距规则
链接有效性

当发现问题时，代码检查工具会在拉取请求上评论，并附上具体的错误信息，以指导贡献者进行必要的修复。

来源：.github/workflows/fpb-lint.yml1-37 .github/workflows/comment-pr.yml1-56

元数据指南

标题

使用资源的原始标题，不要创建或编辑修改
对于具有历史意义的旧作品，在括号中添加年份
除非来源使用，否则不要使用全大写标题
标题中不要使用表情符号

URL

不要使用短链接
从 URL 中删除跟踪代码
转义国际化 URL
始终优先使用安全（https）URL（如果可用）
避免指向实际资源以外的 URL

创作者署名

酌情注明免费资源的创作者
对于翻译作品，注明原作者
使用逗号分隔多位作者
冗长的作者列表可以使用“等”缩短
不提供创作者链接

来源：docs/CONTRIBUTING-hi.md168-212

平台和访问说明

某些资源可能需要特殊的可访问性说明

课程平台：如果需要注册，请注明平台（例如，Coursera, EdX）
YouTube 内容：视频应至少一小时长，并结构化为课程形式
Leanpub：对于需要账户的资源，添加*(需要 Leanpub 账户或有效电子邮件)*

有时限的资源：仓库不收录

将在六个月内被移除的资源
报名期有限的课程
仅在有限时间内免费的资源

来源：docs/CONTRIBUTING-hi.md216-234

贡献翻译

该仓库提供了超过40种语言的文档。强烈鼓励贡献文档翻译或添加不同语言的资源。

当前文档翻译状态

贡献翻译时

检查 docs/README.md 中的现有翻译
遵循与原始文档相同的格式
在文件名中包含适当的语言代码（例如，CONTRIBUTING-es.md 表示西班牙语）

来源：docs/README.md1-147

行为准则

所有贡献者都应遵守项目的行为准则，这确保了一个尊重和包容的社区。通过贡献，您同意遵守此准则。

行为准则概述了

预期行为
不可接受的行为
违规后果
事件报告流程

完整的行为准则可在仓库中以多种语言提供

来源：docs/CODE_OF_CONDUCT-mr.md1-30 docs/CODE_OF_CONDUCT-ml.md1-24

常见问题与解决方案

问题	解决方案
代码检查工具报告字母排序错误	检查您的资源是否放置在正确的字母顺序位置
代码检查工具报告格式问题	确保空格和换行符遵循指南
重复资源	使用搜索功能检查资源是否已存在
付费墙后的资源	提交前验证资源是否完全免费
不确定使用哪个类别	检查资源类型定义和示例

来源：.github/workflows/comment-pr.yml42-55 docs/CONTRIBUTING-hi.md156-162

新手贡献者帮助

如果您是开源或 GitHub 新手，本仓库欢迎您的贡献

您无需了解 Git 即可贡献——您可以提出问题并提供资源建议
查看操作指南提供多种语言版本
查阅拉取请求模板，确保您的提交包含所有必需信息

该仓库拥有一个不断壮大的贡献者社区，他们可以提供问题解答和指导。

来源：docs/HOWTO-ml.md1-32 .github/PULL_REQUEST_TEMPLATE.md1-24