如何做一个开源项目（内训文字稿）

[moyui]

常见文件认识

说明文件

说明文件一般会放在项目的最顶级目录当中，包括不仅限于以下几种文件（文件内容）

参考文章

• AUTHORS：贡献者列表，记录项目的贡献者。

• DISCLAIMER：免责声明文件。

• CHANGELOG：CHANGELOG 文件用来记录项目的变更记录，通常包含 Added、Changed、Removed 和 Fixed。

• CODE_OF_CONDUCT：行为准则文件. 行为准则定义了如何在社区中进行交互和交流的最佳实践, 它也可以作为解决社区成员之间冲突的首选文件。

• CODEOWNERS：代码所有者，代码所有者文件是 Github 提供的特性，可以指定文件或目录的代码所有者，当文件或目录出现 PR 时，可以推送给代码所有者，提醒进行 PR 审查。

• CONTRIBUTING：指导参与者如何对项目做出贡献，CONTRIBUTING 中表述了项目需要什么类型的贡献，社区或者本项目的作业流程。

• LICENSE：开源许可证文件，开源项目通过编写开源许可文件，声明项目使用的开源协议。

• NOTICE：用来存放 License 定义的法律声明文件。

• README：项目介绍说明文件，通常 README 会表述项目的用处、发起原因、快速使用等。

以58开源的项目fair举例, 和facebook开源的react举例 包含以下几个部分

我们公司的lincense应该是免责声明和法律条款二合一

实际上的协议应该是osi组织规定的以下协议的一种

这里要注意package中的lincense，fair项目中 package 是MIT，然而协议是BSD-3-Clause 所以内外协议不一致的情况下可能存在相关问题

react中包含CODE_OF_CONDUCT和CONTRIBUTING相关的贡献指南

贡献准则参考 也可以参考 react的相关贡献准则

贡献编写参考 也可以参考 react的相关贡献准则

代码所有者，这部分应该是在github后台配置的

README部分：包含中英文两份 大致内容参考fair和react如下

基本介绍
    一些版本标志，npm版本标志，当前构建是否pass的标志等，联系方式标志，协议标志，文档标志
    项目介绍： 谁 是什么，要做什么，有什么特性
    
如何安装与启动demo

文档地址

examples

（更新文档）一般是通过releases中的相关文档，并且类似react，是会写一些blog的，来补充说明这一次更新了些什么东西

（roadmap）要做些什么事情

代码文件命名与相关目录

针对前端项目 fair不太具有相关的参考价值，我们换而参考同样是公司开源的前端项目taro-rn

├── .github                   # github流水线相关配置
├── .vscode                   # 编辑器相关配置
├── example                   # 运行样例
├── packages                  # 工程包
│   ├── * pkgA                # 工程包a
│   │   └── __tests__         # 测试用例
│   │   └── __mocks__         # mock代码
│   └── pkgB                  # 工程包b
├── scripts                   # 脚本集合，包括各个模块的构建发布, authors, eslint自定义规则等，比较杂
├── types                     # 类型系统 
├── .eslintrc.js              # eslint配置
├── .gitignore                # gitignore
├── package.json              # package
├── README.md                 # README
├── tsconfig.json             # ts配置
└── yarn.json                 # package

nvmrc 等，看用到什么需要什么
lock文件也是一并上传的

其余的都是“大写“的相关说明文件

文档根据taro和react来看，都不是和项目放在一起的，例如taro有单独的仓库taro-docs
至于要不要放在一起那就看情况

协同工作相关

commit - 文档系统机器人

关键字 - github action，dependabot

github action

dependabot

github action类似于ci-cd工具，在.github/workflow
文件夹下面写配置（类似shell脚本），在不同的场景（push，commit，pr）中可以分别触发

dependabot参考taro的相关方案，也是在这个环境下进行触发的

自动生成readme的方案需要再看看，暂时没有找到（dependabot能提供发布日志）

github提供多环境下的虚拟机来运行工作流程，也可以自己搭建自托管服务器

代码风格

目前没有参考的对象
google开源项目风格指南typescript