├── images ├── Wechatgroup.jpeg ├── contribution-journey.png └── readme-architecture.jpg ├── coc.md ├── 孵化报告模版.md ├── openatom_coc.md ├── coc_guide.md ├── readme_guide.md ├── openatom_checklist.md ├── contributing_guide.md ├── README.md ├── quick_start_guide.md ├── CONTRIBUTING.md └── LICENSE /images/Wechatgroup.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CommunityLeadershipDevelopment/doc_guide/HEAD/images/Wechatgroup.jpeg -------------------------------------------------------------------------------- /images/contribution-journey.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CommunityLeadershipDevelopment/doc_guide/HEAD/images/contribution-journey.png -------------------------------------------------------------------------------- /images/readme-architecture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CommunityLeadershipDevelopment/doc_guide/HEAD/images/readme-architecture.jpg -------------------------------------------------------------------------------- /coc.md: -------------------------------------------------------------------------------- 1 | # 行为准则(Code of Conduct) 2 | 3 | ## 适用范围 4 | 5 | 此行为准则适用于本项目的沟通和协作活动过程。 6 | 7 | ## 一、行为准则 8 | ### 1、尊重 9 | * 这里是一个尊重他人、非常包容的社区。尊重他人和他人的意见，即使你不同意他们的观点。若不同意对方观点，请反驳论题本身，不要反驳提出问题的人。 10 | 11 | ### 2、合法 12 | * 所有人员在参与任何与项目开源社区相关的活动中，皆需遵守任何可适用的法律、法规与规章。 13 | 14 | ### 3、开放 15 | * 我们欢迎任何认同基金会使命、价值观与愿景的人员参与项目开源社区相关的活动。 16 | 17 | ### 4、耐心友好 18 | * 我们共同努力解决冲突和矛盾，并尽力以符合公序良俗的方式行事。我们可能会不时遇到一些问题和矛盾，但我们不会让其变成人身攻击。让人感到不舒服或受到威胁的社区并不是一个富有成效的社区，在与社区其他人员以及社区外的人员交流时，我们应该尊重且耐心友好。 19 | 20 | ### 5、合作 21 | * 我们的成果可能被其他人使用，反过来我们也可能依赖他人的成果。当我们为了项目的利益做事时，我们愿意向其他人解释该项目是如何工作的，这样他们就可以在现有项目的基础上进行工作或优化。 22 | 23 | ### 6、多样性 24 | * 我们鼓励每个人的参与，尊重不同的主张、观点和经历。我们致力于成为一个每个人都乐于加入的社区。虽然我们可能无法让所有人都满意，但我们会一直努力善待每一个人。 25 | 26 | ### 7、谨言慎行 27 | * 请您谨慎选择言论。我们是一个专业社区，请勿侮辱或压制其他参与人员。任何骚扰、歧视和其他排他性的行为与言论是被禁止的。这包括但不限于： 28 | - 歧视性的笑话和语言 29 | - 个人侮辱，特别是那些涉及种族主义或性别歧视 30 | - 不受欢迎的性关注 31 | - 反复骚扰他人 32 | 33 | 如需举报侮辱、骚扰或其他不可接受的行为，您可以发送邮箱至jerrytan@apache.org，联系谭中意进行处理。 34 | 35 | -------------------------------------------------------------------------------- /孵化报告模版.md: -------------------------------------------------------------------------------- 1 | Project-2021-12-12-incubating-report.md 2 | 3 | 4 | ## Project Name 5 | Project Description. 6 | 7 | ### Incubating started Time 8 | XXX has been incubating since XXXX-XX-XX. 9 | 10 | 11 | ### Three most important unfinished tasks to address before graduating: 12 | * task 1 13 | * task 2 14 | * task 3 15 | 16 | ### Are there any issues that TOC need to be aware of? 17 | * issue 1 18 | * issue 2 19 | * issue 3 20 | 21 | ### How has the community developed since the last report? 22 | blah，blah 23 | 24 | ### How has the project developed since the last report? 25 | blah，blah 26 | 27 | 28 | ### Date of last release: 29 | 2021-XX-XX 30 | 31 | ### When were the last committers members elected? 32 | XXXX-XX-XX 33 | 34 | ### Have your mentors been helpful and responsive? 35 | blah，blah. 36 | 37 | 38 | ### Signed-off-by: 39 | * Mentor 1 Comments: 40 | * Mentor 2 Comments: 41 | * Mentor 3 Comments： 42 | 43 | 44 | ## TOC notes: 45 | blah，blah. 46 | -------------------------------------------------------------------------------- /openatom_coc.md: -------------------------------------------------------------------------------- 1 | # 行为准则(Code of Conduct) 2 | 3 | ## 适用范围 4 | 5 | 此行为准则适用于开放原子开源基金会技术监督委员会（Technical Oversight Committee，以下简称“TOC”）的日常活动，活动包括但不限于：TOC成员和导师使用官方电子邮件列表与社交平台、作为指定代表参与在线或线下活动。 6 | 7 | 并作为基金会内各开源项目内的默认行为准则使用。如果某项目有特定需求，可在此基础上更新为项目自身的COC，但不得违背本COC的基本要求。 8 | 9 | ## 行为准则 10 | ### 1、尊重 11 | 这里是一个尊重他人、非常包容的社区。尊重他人和他人的意见，即使你不同意他们的观点。若不同意对方观点，请反驳论题本身，不要反驳提出问题的人。 12 | 13 | ### 2、合法 14 | 所有人员在参与任何与项目开源社区相关的活动中，皆需遵守任何可适用的法律、法规与规章。 15 | 16 | ### 3、开放 17 | 我们欢迎任何认同基金会使命、价值观与愿景的人员参与项目开源社区相关的活动。 18 | 19 | ### 4、耐心友好 20 | 我们共同努力解决冲突和矛盾，并尽力以符合公序良俗的方式行事。我们可能会不时遇到一些问题和矛盾，但我们不会让其变成人身攻击。让人感到不舒服或受到威胁的社区并不是一个富有成效的社区，在与社区其他人员以及社区外的人员交流时，我们应该尊重且耐心友好。 21 | 22 | ### 5、合作 23 | 我们的成果可能被其他人使用，反过来我们也可能依赖他人的成果。当我们为了项目的利益做事时，我们愿意向其他人解释该项目是如何工作的，这样他们就可以在现有项目的基础上进行工作或优化。 24 | 25 | ### 6、多样性 26 | 我们鼓励每个人的参与，尊重不同的主张、观点和经历。我们致力于成为一个每个人都乐于加入的社区。虽然我们可能无法让所有人都满意，但我们会一直努力善待每一个人。 27 | 28 | ### 7、谨言慎行 29 | 请您谨慎选择言论。我们是一个专业社区，请勿侮辱或压制其他参与人员。任何骚扰、歧视和其他排他性的行为与言论是被禁止的。这包括但不限于： 30 | - 歧视性的笑话和语言 31 | - 个人侮辱，特别是那些涉及种族主义或性别歧视 32 | - 不受欢迎的性关注 33 | - 反复骚扰他人 34 | 35 | ## 联系方式和处理 36 | 如果遇到侮辱、骚扰或其他不可接受的行为，您可以发送邮箱至toc-main@openatom.io，联系开放原子开源基金会技术监督委员会处理。 37 | 38 | -------------------------------------------------------------------------------- /coc_guide.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct(行为规范) 2 | 3 | ## 什么是COC 4 | A code of conduct is a set of rules outlining the norms, rules, and responsibilities or proper practices of an individual party or an organization. --From wikipedia 5 | 6 | 行为规范，是社会群体或个人在参与社会活动中所遵循的规则、准则的总称，是社会认可和人们普遍接受的具有一般约束力的行为标准。--来自百度百科 7 | 8 | ## COC的作用 9 | 在开源社区的各项活动中，为了保证各种交流和合作的顺利进行，非常有必要定义一些规则，用于约束社区参与坊的行为，避免出现因为难以接受的行为而导致的不愉快。 10 | 11 | 对于一个开源社区来说非常重要，所以是项目必须的文档之一。 12 | 13 | ## COC的组成部分 14 | 1. 适用范围 15 | 要求：需要讲清楚该COC的适用范围 16 | * 在何处生效（仅适用于问题和请求，还是还包括类似事件的社区活动？） 17 | * 适用人员/群体（社区成员和维护者，是否还有赞助者呢？） 18 | 19 | 20 | 2. 行为规范 21 | 要求：形式可以多样，需要列举一些不可接受的行为包括违反法律，人身攻击相关等；也可以加上一些价值观的说明 22 | 23 | 3. 举报途径或者违反处罚办法 24 | 要求：给出明确的举报方式，一般留一个邮件地址；或者给出处罚方法包括删除言论，甚至永久除名等 25 | 26 | 27 | ## COC的参考sample 28 | 1. [开放原子基金会下项目的默认COC](openatom_coc.md) 29 | 2. [Apache开源软件基金会的COC](https://www.apache.org/foundation/policies/conduct) 30 | 3. [CNCF基金会的COC](https://github.com/cncf/foundation/blob/master/code-of-conduct-languages/zh.md) 31 | 32 | ## COC的Checklist 33 | - [ ] 项目主Repo的根目录下是否有COC文件 34 | - [ ] 项目Readme文件中是否有到COC文件的说明和链接 35 | - [ ] COC是否包含了如下部分 36 | - [ ] 适用范围 37 | - [ ] 不可接受的行为列表 38 | - [ ] 举报途径或者处罚方法 39 | - [ ] COC中的内容是否通俗易懂 40 | -------------------------------------------------------------------------------- /readme_guide.md: -------------------------------------------------------------------------------- 1 | # README 规范与建议 2 | 3 | 开源项目的 README 是项目的第一张名片，对于开源项目的用户快速了解与使用我们的开源项目至关重要。我们可以通过图、文、Gif 动画、视频等表现形式来丰富 README 的内容。 4 | 5 | ## 项目品牌 6 | 7 | 在 README 顶部，可以放置该项开源目的Slogan和项目的Logo。 8 | 9 | ## 项目介绍 10 | 11 | 为项目撰写一段言简意赅的介绍文案，让读者在**3 分钟** 内了解你的项目能做什么，应用于什么场景，能帮助用户解决什么问题。我们通常还可以添加一个功能列表，以及并添加一个链接到访问者可能不熟悉的参考资料。也可以在这里添加一个功能列表或一个背景小节。如果你的项目有替代方案，这也是列出区别因素的好地方。 12 | 13 | ## 安装说明 14 | 15 | 常见的软件安装方式例如 Yarn、NuGet 或 Homebrew 通常可以通过几条命令快速完成安装。然而，考虑到阅读 README 的人可能是个小白用户，希望得到更多的指导。列出具体步骤有助于消除歧义，可以帮助用户快速下载和安装我们的项目。如果它需要特定的环境下运行，如特定的编程语言版本或操作系统，以及在指定公有云或者基于 Kubernetes 安装，也需要提供超链接外链到相关安装文档。 16 | 17 | 我们通常可以使用折叠的方式来隐藏较为复杂的内容，用户可以选择性地展开查看更详细的内容。 18 | 19 | ## 快速入门 20 | 21 | 尽可能提供几个快速入门的使用示例，并展示预期输出，帮助用户在几分钟内快速上手你的项目，请参考 [快速上手指南](quick_start_guide.md) 了解更多。 22 | 23 | ## 支持 24 | 25 | 清晰地告诉用户可以到哪里去寻求帮助，包括但不限于 GitHub issue、社群（如 Slack、Gitter）、电子邮件地址等方式。 26 | 27 | ## 参与贡献 28 | 29 | 说明我们的项目是否对贡献者开放，以及接受社区贡献的 Pull Request 要求是什么，例如是否需要签署 CLA，是否需要参考和遵循哪些代码与文档规范。请参考 [贡献者指南](contributing.md) 了解更多。 30 | 31 | ## Code of Conduct 32 | 33 | 请参考 [Code of Conduct（本项目遵守的行为规范）](coc.md)。 34 | 35 | ## 许可证 36 | 37 | 请在 README 底部声明此开源项目所采用的开源许可证。 38 | 39 | 40 | ## Readme的Checklist 41 | - [ ] 项目主Repo的根目录下是否有Readme文件（文件名可以多样） 42 | - [ ] Readme文件是否包含了如下部分 43 | - [ ] 项目介绍 44 | - [ ] 到quickstart/contributing/coc/license的链接 45 | - [ ] 项目介绍是否通俗易懂 46 | 47 | -------------------------------------------------------------------------------- /openatom_checklist.md: -------------------------------------------------------------------------------- 1 | # 文档检查CheckList 2 | 3 | ## 适用范围 4 | 导师在检查开放原子基金会所属孵化项目的时候，可以参照该checklist来对repo的文档进行检查 5 | 6 | ## 基本文档检查 7 | - [ ] Readme 是否达标？ 8 | - [ ] Contributing 是否达标 9 | - [ ] quickstart 是否达标 10 | - [ ] COC 是否达标 11 | 12 | 13 | ## Readme的Checklist 14 | - [ ] 项目主Repo的根目录下是否有Readme文件（文件名可以多样） 15 | - [ ] Readme文件是否包含了如下部分 16 | - [ ] 项目介绍 17 | - [ ] 到quickstart/contributing/coc/license的链接 18 | - [ ] 项目介绍是否通俗易懂 19 | 20 | ## QuickStart的checklist 21 | - [ ] 项目的仓库下有「快速上手指南」文件。 22 | - [ ] 项目的 README 文件中有「快速上手指南」的链接。 23 | - [ ] 快速上手指南需包含以下模块和具体步骤： 24 | - [ ] 使用软件的先决条件（例如，软硬件要求） 25 | - [ ] 如何下载 26 | - [ ] 如何安装 27 | - [ ] 如何使用 28 | - [ ] 高质量的「快速上手指南」需[易使用](https://github.com/CommunityLeadershipDevelopment/doc_guide/blob/main/quick_start_guide.md#%E6%98%93%E4%BD%BF%E7%94%A8)、[易查找](https://github.com/CommunityLeadershipDevelopment/doc_guide/blob/main/quick_start_guide.md#%E6%98%93%E6%9F%A5%E6%89%BE)、[易理解](https://github.com/CommunityLeadershipDevelopment/doc_guide/blob/main/quick_start_guide.md#%E6%98%93%E7%90%86%E8%A7%A3)。 29 | 30 | ## Contributing的 Checklist 31 | - [ ] 项目主 repo 的根目录中是否有贡献者指南 32 | - [ ] 项目 readme 中是否有到贡献者指南的链接 33 | - [ ] 贡献者指南中包含如下内容 34 | - [ ] 欢迎的态度 35 | - [ ] 贡献的内容 36 | - [ ] 贡献的流程 37 | - [ ] 贡献者指南是否简介明了、清晰易懂 38 | 39 | ## COC的Checklist 40 | - [ ] 项目Readme文件中是否有到COC文件的说明和链接，链接到OpenAtom的COC或者基于该COC增补特定内容后项目本身的COC 41 | - [ ] COC是否包含了如下部分 42 | - [ ] 适用范围 43 | - [ ] 不可接受的行为列表 44 | - [ ] 举报途径或者处罚方法 45 | - [ ] COC中的内容是否通俗易懂 46 | -------------------------------------------------------------------------------- /contributing_guide.md: -------------------------------------------------------------------------------- 1 | 2 | # 开源贡献简介 3 | - 开源意味着开放、协作、公开、透明，大家都可以检查、修改并分享内容。 4 | 5 | - 开源软件按照去中心化、协作的方式发展，依赖社区共同治理；所以开源软件更廉价、更灵活，生命力也更旺盛、持久。 6 | 7 | - 开源社区的理念是：社区高于代码，社区需要多元化。无论你写代码，撰写用户手册、技术博客，设计网站，还是策划社区活动，这些都是在为社区做贡献。 8 | 9 | - 开源社区鼓励大家公开协作，无论你擅长什么，只要你愿意，你都可以在开源的舞台上发光发热。你付出的越多，收获的就越多。 10 | 11 | # 为什么要贡献开源 12 | 从个人角度来说，开源就像自助餐中的啤酒一样，意味着免费 - 没有人会为您的拉取请求支付任何费用。但这并不意味着您不能因此受益。通过这种公开透明的协作方式为开源做贡献，你可以 13 | - 提高个人知名度和影响力 14 | - 提升履历价值 15 | - 成为精英管理中的骨干 16 | 17 | # 如何贡献 18 | Apache 软件基金会、CNCF、Linux Foundation 等有成千上万的开源项目，怎么找到合适的项目贡献呢？我们以 Apache 项目为例来介绍如何上手。 19 | 1. 了解 [Apache 软件基金会的社区理念](https://apache.org/foundation/how-it-works.html)，深入了解社区高于代码 20 | 2. [发现问题，并尝试解决](https://community.apache.org/gettingStarted/101.html) 21 | 3. 加入社区：订阅邮件列表、加入项目 Slack、微信交流群，关注项目 Twitter、LinkedIn 等动态。大胆在邮件列表中介绍自己，并积极参与问题讨论。 22 | 23 | ## 贡献内容 24 | 无论你从事什么职业，为哪个开源项目做贡献，你可以在以下方面充分发挥自己的特长： 25 | - 写代码 26 | - 测试 27 | - 写文档 28 | - 审校 PR 29 | - 解决用户问题 30 | - 设计网站 31 | - 举办社区活动 32 | - ...... 33 | 34 | ## 贡献流程 35 | 描述贡献的各个步骤，比如先 fork，再 clone... 等。 36 | 37 | 详细步骤，可以参考 [本项目贡献者指南](CONTRIBUTING.md)。 38 | 39 | # 示例 40 | 41 | - [ASF 贡献者指南](https://community.apache.org/newcomers/) 42 | - [Apache Pulsar 贡献者指南](https://github.com/apache/pulsar/blob/master/CONTRIBUTING.md) 43 | - [KubeSphere 贡献指南](https://github.com/kubesphere/community) 44 | 45 | # Checklist 46 | - [ ] 项目主 repo 的根目录中是否有贡献者指南 47 | - [ ] 项目 readme 中是否提及贡献者指南 48 | - [ ] 贡献者指南中包含如下内容： 49 | - [ ] 欢迎的态度 50 | - [ ] 贡献的内容 51 | - [ ] 贡献的流程 52 | - [ ] 贡献者指南是否简介明了、清晰易懂 53 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 开源技术项目文档指南 2 | 3 | ## 项目介绍 4 | 5 | 本项目是一个开源技术项目的文档指南，希望能对开源技术项目的文档部分进行**最基本**的一些规范定义，从而对项目的文档完善起到一些参考作用。 6 | 本指南定义开源技术项目中哪些文档是必须的，以及这些文档应该有哪些内容章节，并需要达到什么的质量要求，便于开发者了解、使用和贡献这个开源项目。 7 | 8 | ## 使用场景 9 | 10 | 1. 开源项目的负责人可以参考此文档，检查自己的开源技术项目是否已有这些文档，这些文档是否达到本指南的各个质量要求 11 | 2. 开源项目的文档负责人可以参考此文档，把这些文档作为自己项目的文档模版，按需增补自己项目的特定内容，从而快速达到文档完备的基本要求 12 | 3. 本指南作为开放原子基金会TOC的工作文档一部分，作为导师帮助孵化项目达到文档质量要求的参考和Checklist 13 | 4. 作为国内开源项目技术传播工程师社区（包括布道，文档等）的一个初始产出 14 | 15 | ## 贡献者 16 | 17 | |名字|GitHub ID|所属公司或组织| 18 | |---|---|--| 19 | |谭中意|[tanzhongyi003](https://github.com/tanzhongyi003)|开放原子基金会| 20 | |周鹏飞|[FeynmanZhou](https://github.com/FeynmanZhou)|KubeSphere 社区| 21 | |Yu |[Anonymitaet](https://github.com/Anonymitaet)|StreamNative / ASF 22 | |Jennifer Huang |[Jennifer88huang](https://github.com/Jennifer88huang) | StreamNative / ASF| 23 | 24 | ## 文档列表 25 | 26 | 1. [Readme-相关](readme_guide.md) （鹏飞负责） 27 | 28 | 2. [快速上手指南-相关](quick_start_guide.md)（Yu 负责） 29 | 30 | 3. [Contributing-相关](contributing_guide.md) （Jennifer负责） 31 | 32 | 4. [COC（行为规范)-相关](coc_guide.md)（谭中意负责） 33 | 34 | ## 本项目文档的规范 35 | 36 | ### 每个文档分为三个部分 37 | 1. 第一部分阐述本文档的目的和作用，以及应该有哪些章节和每个章节应该达到的质量要求 38 | 2. 第二部分给出一个live的例子，即用在真实的知名项目中，质量还不错的例子 39 | 3. 第三部分是一个Checklist，针对第一部分的要求给出的多个Check Items，可以供工程师或者导师进行文档的检查 40 | 41 | ## 快速上手指南 42 | 43 | [这是「快速上手指南」的写作规范](quick_start_guide.md)，仅供参考 44 | 45 | ## 如何贡献 46 | [本项目欢迎贡献](CONTRIBUTING.md) 47 | 48 | ## Code of Conduct 49 | [本项目遵守如下的行为规范](coc.md) 50 | 51 | ## 欢迎加入开源项目技术传播社区 52 | 二维码如下，欢迎大家扫码加入，和我们一起讨论开源项目技术传播的事情，包括技术文档协作，技术线上和线下布道等等。 53 | 54 | 55 | 56 | 57 | -------------------------------------------------------------------------------- /quick_start_guide.md: -------------------------------------------------------------------------------- 1 | # 快速上手指南 2 | 3 | ## 什么是「快速上手指南」？ 4 | 5 | 「快速上手指南」帮助用户快速了解项目，并快速上手使用。 6 | 7 | ## 为什么需要「快速上手指南」？ 8 | 9 | 「快速上手指南」帮助用户在 **10 分钟内**上手项目，避免用户在一开始使用项目时受挫而产生负面情绪，提高用户对项目的兴趣。 10 | 11 | ## 怎样撰写「快速上手指南」？ 12 | 13 | 以下为通用说明，仅供参考。 14 | 15 | ### 撰写前 16 | 17 | 在开发技术文档之前，需要了解你的受众，包括但不限于以下方面： 18 | 19 | - 受众需求 20 | - 教育背景 21 | - 知识水平 22 | 23 | ### 撰写时 24 | 25 | 一般而言，「高质量」的快速上手指南具备以下特点： 26 | 27 | #### 易使用 28 | 29 | - **以「任务」为导向** 30 | - 不是描述项目功能或工作原理❌，而是描述「如何使用」✅。 31 | - 使用多级标题描述任务主题。 32 | - 将复杂任务拆成多个子任务。 33 | - 描述任务可以使用有序列表。 34 | - 提供清晰和具体的步骤以及**预期结果**。 35 | - 如果需要介绍「概念性」内容辅助用户完成任务，建议仅少量添加，可以使用链接。 36 | 37 | - **「准确性」** 38 | - 根据实际操作过程撰写，需准确描述。 39 | 40 | - **「完整性」** 41 | - 跳出开发人员视角，而是以用户的视角，提供完成任务所需的信息。既没有信息缺失，也没有信息超载。 42 | 43 | #### 易理解 44 | 45 | - **「清晰」** 46 | - 短小精悍，通过简洁易懂的描述，帮助用户快速上手项目。 47 | 48 | - **「具体」** 49 | - 可以添加示例。例如，代码块。 50 | 51 | - **「语法与风格」** 52 | - 使用正确的语法，避免拼写或标点符号错误等。 53 | - 尽量使用第二人称、主动语态和一般现在时。 54 | - 全文风格保持一致，注意术语的一致性。 55 | - 避免引起歧义（性别、种族）的描述。 56 | 57 | #### 易查找 58 | 59 | - **「文档结构」** 60 | - 信息架构可以基于任务划分，每个主题下的子任务层级尽量少，2 级比较合适。 61 | - 重点信息可以凸出显示。 62 | 63 | - **「可查找性」** 64 | - 在导航栏或目录中可以看到该指南，并能点击多级标题跳转至正文内容。 65 | - 可以加入有用的链接，但不宜太多。 66 | 67 | - **「视觉效果」** 68 | - 字不如表，表不如图。尽量用图表描述。 69 | - 可以增加视觉元素，用于信息强调或提醒。例如，在“提示”前增加“灯泡”图标💡。 70 | 71 | #### 撰写后 72 | 73 | - 和软件不断迭代一样，需要时常检查是否需要更新内容。 74 | - 多获取用户意见，不断修正。 75 | 76 | ## 示例 77 | 78 | - [Terraform - 快速上手指南](https://learn.hashicorp.com/tutorials/terraform/infrastructure-as-code?in=terraform/aws-get-started) 79 | - [Spring - 快速上手指南](https://spring.io/guides#getting-started-guides) 80 | - [Docker - 快速上手指南](https://docs.docker.com/get-started/) 81 | - [Databricks - 快速上手指南](https://docs.databricks.com/sql/get-started/admin-quickstart.html) 82 | - [Apache Pulsar - 快速上手指南](https://pulsar.apache.org/docs/en/next/standalone/) 83 | - [KubeSphere - 快速上手指南](https://kubesphere.com.cn/en/docs/quick-start/) 84 | 85 | ## 任务清单 86 | 87 | - [ ] 项目的仓库下有「快速上手指南」文件。 88 | 89 | - [ ] 项目的 README 文件中有「快速上手指南」的链接。 90 | 91 | - [ ] 快速上手指南需包含以下模块和具体步骤： 92 | - [ ] 使用软件的先决条件（例如，软硬件要求） 93 | - [ ] 如何下载 94 | - [ ] 如何安装 95 | - [ ] 如何使用 96 | 97 | - [ ] 高质量的「快速上手指南」需[易使用](#易使用)、[易查找](#易查找)、[易理解](#易理解)。 98 | 99 | 100 | 101 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # 贡献指南 2 | 3 | 如果你在使用本仓库时，发现任何问题或者有修改建议，欢迎提出来并修改，成为我们的贡献者。 4 | 5 | ## Markdown 6 | 本仓库下所有文件均为 [Markdown](https://www.markdownguide.org/) 文件。要想了解 Markdown 快速上手，可以查看[快速入门](https://www.markdownguide.org/getting-started)。 7 | 8 | ## 贡献流程 9 | 10 | ### 步骤一: Fork 11 | 12 | 1. 访问 https://github.com/CommunityLeadershipDevelopment/doc_guide 13 | 2. 点击右上角的 `Fork`。 14 | 15 | ### 步骤二: Clone 16 | 17 | 点击 **Code > Clone**。 18 | 19 | ```sh 20 | $ cd $working_dir 21 | $ git clone https://github.com/$user/doc_guide 22 | ``` 23 | 24 | 把你克隆的仓库加成 upstream。 25 | 26 | ```sh 27 | $ cd $working_dir/doc_guide 28 | $ git remote add upstream https://github.com/CommunityLeadershipDevelopment/doc_guide.git 29 | ``` 30 | 31 | 使用 `git remote -v` 命令查看远端仓库： 32 | 33 | ``` 34 | origin https://github.com/$user/doc_guide.git (fetch) 35 | origin https://github.com/$user/doc_guide.git (push) 36 | upstream https://github.com/CommunityLeadershipDevelopment/doc_guide (fetch) 37 | upstream https://github.com/CommunityLeadershipDevelopment/doc_guide (push) 38 | ``` 39 | 40 | ### 步骤三: 同步分支 41 | 42 | 确保你的分支和远端内容一致。 43 | 44 | ```sh 45 | $ cd $working_dir/doc_guide 46 | $ git checkout master 47 | $ git fetch upstream 48 | $ git rebase upstream/master 49 | $ git push origin master 50 | ``` 51 | 52 | ### 步骤四: 创建分支 53 | 54 | 基于 master 创建分支。 55 | 56 | ```sh 57 | $ git checkout -b myfeature 58 | ``` 59 | 60 | ### 步骤五: 修改内容 61 | 62 | 在新创建的分支中修改内容。 63 | 64 | ### 步骤六: 提交（Commit） 65 | 66 | 提交修改。 67 | 68 | ```sh 69 | $ git add 70 | $ git commit -m "$add a comment" 71 | ``` 72 | 73 | 提交修改后，你可能需要来回修改、提交几轮，可以参考使用以下命令。 74 | 75 | ```sh 76 | $ git add (used to add one file) 77 | git add -A (add all changes, including new/delete/modified files) 78 | git add -a -m "$add a comment" (add and commit modified and deleted files) 79 | git add -u (add modified and deleted files, not include new files) 80 | git add . (add new and modified files, not including deleted files) 81 | ``` 82 | 83 | ### 步骤七：把变更推到远端仓库（Push） 84 | 85 | 完成修改后，需要把修改内容推到你 fork 的远端仓库。 86 | 87 | ```sh 88 | $ git push origin myfeature 89 | ``` 90 | 91 | ### 步骤八: 创建 PR（pull request） 92 | 93 | 1. 访问你 fork 的仓库 https://github.com/$user/doc_guide 。 94 | 2. 点击 `Compare & pull request` 。 95 | 96 | ### 步骤九: 审校（review） 97 | 提交 PR 后，可以找人帮忙审校。审校确认无误，审校人会审批通过 （approve）并将你的修改合并到仓库（merge）。 98 | 99 | 恭喜你成为我们的贡献者！ 100 | 101 | > **建议** 102 | > - PR 内容修改少，会更容易审校、合并。 103 | > - 如果你要修改的内容很多，涉及多个文件，可以分开提 PR。 104 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution-ShareAlike 4.0 International Public License 2 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 3 | 4 | Section 1 – Definitions. 5 | 6 | Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 7 | Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 8 | BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License. 9 | Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 10 | Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 11 | Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 12 | License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. 13 | Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 14 | Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 15 | Licensor means the individual(s) or entity(ies) granting rights under this Public License. 16 | Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 17 | Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 18 | You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. 19 | Section 2 – Scope. 20 | 21 | License grant. 22 | Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 23 | reproduce and Share the Licensed Material, in whole or in part; and 24 | produce, reproduce, and Share Adapted Material. 25 | Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 26 | Term. The term of this Public License is specified in Section 6(a). 27 | Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 28 | Downstream recipients. 29 | Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 30 | Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. 31 | No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 32 | No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 33 | Other rights. 34 | 35 | Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 36 | Patent and trademark rights are not licensed under this Public License. 37 | To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 38 | Section 3 – License Conditions. 39 | 40 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 41 | 42 | Attribution. 43 | 44 | If You Share the Licensed Material (including in modified form), You must: 45 | 46 | retain the following if it is supplied by the Licensor with the Licensed Material: 47 | identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 48 | a copyright notice; 49 | a notice that refers to this Public License; 50 | a notice that refers to the disclaimer of warranties; 51 | a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 52 | indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 53 | indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 54 | You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 55 | If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 56 | ShareAlike. 57 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. 58 | 59 | The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. 60 | You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. 61 | You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. 62 | Section 4 – Sui Generis Database Rights. 63 | 64 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 65 | 66 | for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 67 | if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and 68 | You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 69 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 70 | Section 5 – Disclaimer of Warranties and Limitation of Liability. 71 | 72 | Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. 73 | To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. 74 | The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 75 | Section 6 – Term and Termination. 76 | 77 | This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 78 | Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 79 | 80 | automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 81 | upon express reinstatement by the Licensor. 82 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 83 | For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 84 | Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 85 | Section 7 – Other Terms and Conditions. 86 | 87 | The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 88 | Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. 89 | Section 8 – Interpretation. 90 | 91 | For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 92 | To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 93 | No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 94 | Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 95 | --------------------------------------------------------------------------------