mirror of
https://gitee.com/spark-store-project/spark-store
synced 2025-09-06 19:32:22 +08:00
82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# 关于编写 "描述主体结构预览说明" 的规范
|
||
|
||
1. 主体结构预览
|
||
|
||
一般以 `tree` 命令进行获取目录结构进行展示所需要描述的预览内容。
|
||
|
||
2. 对主体结构中的内容单独说明
|
||
|
||
并使用所用语言进行非侵入式独立描述，而不是在代码中填充说明与注释。
|
||
|
||
在单行描述中，尽量不超过您认为最大的字符数量宽度，可以收缩内容的重要性。
|
||
|
||
在此种说明文档中，尽量使用您所描述的对象支持的代码注释，而不是以白底黑字进行描述。
|
||
|
||
对于规范的全部：主体结构 + 单独内容中进行简单(而不是简少)的说明。
|
||
|
||
一个简单的例子，例如: 有关项目源代码结构的预览说明
|
||
|
||
- 项目结构预览
|
||
|
||
```
|
||
.
|
||
├── assets
|
||
├── debian
|
||
├── DOCS
|
||
├── patchs
|
||
├── src
|
||
├── tool
|
||
└── translations
|
||
|
||
10 directories, 9 files
|
||
```
|
||
|
||
- 来自 debian 目录的说明
|
||
|
||
```shell
|
||
# 将此项目进行 debian 的标志，基于 debian 系列的发行版可对包含
|
||
# 此种目录的开源项目进行构建 deb 软件包。
|
||
|
||
# 1. 构建软件包(打包)
|
||
# 执行 dpkg-buildpackage 命令以尝试构建此软件包
|
||
dpkg-buildpackage
|
||
# 如果构建将会在上级目录中产生一个 deb，而源代码目录不会有任何变化。
|
||
|
||
# 如果出现以下内容可忽视，仅需要查看是否已成功构建软件包:
|
||
# gpg: 已跳过 ""： 无效的用户ID
|
||
# gpg: ...: clear-sign failed: 无效的用户ID
|
||
# dpkg-buildpackage: error: failed to sign .dsc file
|
||
```
|
||
|
||
- 来自 patchs 目录的说明
|
||
|
||
```shell
|
||
# 一种用于可扩展的补丁，主要目的是为项目提供可选的应用方案，而不是直接堆砌到
|
||
# 当前项目的分支中。您可以认为所有分支都是主线分支。
|
||
# 例如:
|
||
# 主线稳定分支: master
|
||
# 主线开发分支: dev
|
||
# 主线其它: ...
|
||
|
||
# 注意:
|
||
# 当您认为您所提交的内容并不会为主线带来 bug fix 之类的内容，请使用补丁。
|
||
# 当您所提交的内容会带来不可预知的问题的时候，或会改变目前主线的开发模式时，
|
||
# 此种方式可确保您提交的方案可被任意时间被弃用，而不是由其它维护者耗费精力
|
||
# 去试图移除您提交的内容，而不是等待由提交者进行新的维护。
|
||
```
|
||
|
||
- 来自其它的内容...可随时由任何人进行补充
|
||
|
||
|
||
- 一些在关此种预览描述的文档
|
||
|
||
```shell
|
||
# 此种描述还将出现在 `src/README.md` 的描述中。
|
||
# 当然，我预期会由其它维护者进行移动到 `DOCS` 之下。
|
||
|
||
# 另外在 `patchs/zinface-community-cmake-build-system.patch` 补丁文件中，
|
||
# 也随附过一个简要的文档内容，而它是记录了 `Spark` 为名的构建模式。
|
||
|
||
# 在未应用此补丁时，将不会出现在任何地方。
|
||
```
|
||
|