README

README作为说明文件，作用是让浏览者快速、鸟瞰式地了解项目。

为了做到这点，写 README的时候应该注意层次和格式，用 Markdown书写为佳。

一般至少包含三大部分，

1. 介绍项目背景和用处，
2. 使用方法（包括导入/安装暴露的调用接口等），
3. 遵守的协议（针对开源项目）

推荐结构

1. logo，项目名称，项目介绍
2. 基础要求
3. 环境安装
4. 使用方法
5. 文件夹结构及各配置文件简单说明
6. 可能问题及解决方案

示例 :

1. https://github.com/ant-design/ant-design
2. https://github.com/maxcountryman/flask-login
3. https://github.com/vinta/awesome-python

CHANGELOG

是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒序的列表，以记录一个项目中所有版本的显著变动。

什么作用？

为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动

如何书写

1. 每个版本都应该有独立的入口。
2. 新版本在前，旧版本在后应包括每个版本的发布日期。
3. 注明是否遵守语义化版本格式。

几种类型

• Added新添加的功能。
• Changed对现有功能的变更。
• Deprecated已经不建议使用，准备很快移除的功能。
• Removed已经移除的功能。
• Fixed对bug的修复

指导意见 : https://keepachangelog.com/zh-CN/1.0.0/

API文档

流程图

Flowchart

https://www.yuque.com/yuque/help/flowchart

时序图（UML交互图）

PlantUML

https://www.yuque.com/yuque/help/editor-puml

版本语义化

主版本号.次版本号.修订号，版本号递增规则如下

• 主版本号：当你做了不兼容的AP修改
• 次版本号：当你做了向下兼容的功能性新增
• 修订号：当你做了向下兼容的问题修正。

先行版本号及版本编译元数据可以加到“主版本号次版本号修订号”的后面，作为延伸。

指导原则 : https://semver.org/lang/zh-CN/