spark-store/DOCS/write-preview-skeleton.md

关于编写 "描述主体结构预览说明" 的规范

1. 主体结构预览

   一般以 tree 命令进行获取目录结构进行展示所需要描述的预览内容。

2. 对主体结构中的内容单独说明

   并使用所用语言进行非侵入式独立描述，而不是在代码中填充说明与注释。

   在单行描述中，尽量不超过您认为最大的字符数量宽度，可以收缩内容的重要性。

   在此种说明文档中，尽量使用您所描述的对象支持的代码注释，而不是以白底黑字进行描述。

   对于规范的全部：主体结构 + 单独内容中进行简单(而不是简少)的说明。

一个简单的例子，例如: 有关项目源代码结构的预览说明

• 项目结构预览

  .
  ├── assets
  ├── debian
  ├── DOCS
  ├── patchs
  ├── src
  ├── tool
  └── translations
  
  10 directories, 9 files
  

• 来自 debian 目录的说明

  # 将此项目进行 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 目录的说明

  # 一种用于可扩展的补丁，主要目的是为项目提供可选的应用方案，而不是直接堆砌到
  # 当前项目的分支中。您可以认为所有分支都是主线分支。
  # 例如:
      # 主线稳定分支: master
      # 主线开发分支: dev
      # 主线其它:    ...
  
  # 注意:
  #   当您认为您所提交的内容并不会为主线带来 bug fix 之类的内容，请使用补丁。
  #   当您所提交的内容会带来不可预知的问题的时候，或会改变目前主线的开发模式时，
  #   此种方式可确保您提交的方案可被任意时间被弃用，而不是由其它维护者耗费精力
  #   去试图移除您提交的内容，而不是等待由提交者进行新的维护。
  

• 来自其它的内容...可随时由任何人进行补充

• 一些在关此种预览描述的文档

  # 此种描述还将出现在 `src/README.md` 的描述中。
  # 当然，我预期会由其它维护者进行移动到 `DOCS` 之下。
  
  # 另外在 `patchs/zinface-community-cmake-build-system.patch` 补丁文件中，
  # 也随附过一个简要的文档内容，而它是记录了 `Spark` 为名的构建模式。
  
  # 在未应用此补丁时，将不会出现在任何地方。