﻿/*
	Copyright by FrankHB 2013.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file ProjectRules.txt
\ingroup Documentation
\brief 项目组织和管理规则。
\version r176
\author FrankHB <frankhb1989@gmail.com>
\since build 381
\par 创建时间:
	2013-02-14 17:59:49 +0800
\par 修改时间:
	2013-04-09 04:58 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::ProjectRules
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
本文档适用范围为项目范围， 参见 @1 。 

@1 项目范围：
 YSLib 项目(the YSLib project) 是以库为主要产出的项目。

@1.1 顶级子项目：
 YBase ： YSLib 基础库。
 YFramework ： YSLib 框架库。
 YSTest ： YSTest 测试项目，是包含测试代码的应用程序项目，包含示例（当前为 YReader ）。

@1.2 平台环境：
使用的平台除了配置管理(@2.1) 需另行说明外，由 YFramework 特定部分的实现定义。其它部分除 YSTest 外，都保持平台中立([Documentation::CommonRules @@2.2.2.1]) 。
使用 ISO C++ 作为主要开发语言。具体的环境限定（语言版本和语言实现等）参见 [Documentation::Designation @@1.3.2] 。

@1.3 依赖结构：
 YFramework 依赖于 YBase 。
 YSTest 依赖于 YBase 和 YFramework 。
具体的调用依赖和架构见 /vsd 。
不由 YSLib 项目提供的库称为外部依赖项。

@2 项目管理：
如无特别说明，不修改外部依赖项。
以下是非外部依赖项设计和管理约定。
注意具体的 IDE （集成开发环境）等工具不一定支持以下所有项。

@2.1 配置管理：
适用于各个子项目。
各目标平台统一包含的基本配置为 debug 和 release （注意大小写），分别对应于调试和发布。
对于有其它生成目标的平台可以追加配置。

@2.2 版本控制：
此规则用于对 YSLib 项目中的文件的修订和项目发布的顺序标识提供的一种简便方式。适用于任意非外部依赖项。
被版本库识别并归档的文件称为托管文件。
任意托管文件的被版本库识别的改动都是项目的修订。除此之外，存档与临时文件的临时版本记录区域不视为文件修订。
项目构建版本号独立于文件版本号。

@2.2.1 项目构建：
自 build 132 起使用版本控制工具。

@2.2.1.1 构建版本：
以 (release) rev （缩写 r ）加整数序号表示用于在构建之间迭代的编译版本。一个编译版本具有一次或多次修订后的一个或多个配置的一次构建。

@2.2.1.2 提交版本：
以 build （缩写 b ）加整数序号表示经过完整构建的提交版本。一个提交版本应至少具有一次（各个平台）所有配置的全部重新构建。
原则上对于 N 个发布平台，一个提交版本具有至少 8N 个编译版本，其中最后的连续几个版本作为各个配置的提交发布版本。

@2.2.1.3 库提交版本：
包含库源代码的文件的修改的提交版本称为库提交版本。
大部分提交版本应为库提交版本。

@2.2.1.4 主分支版本：
在主要开发路径分支（主分支）上的库提交版本称为主分支版本。
主分支版本也可以仅包含库的文档改进，但应在提交记录说明。
仅包含库的程序或文档以外修订的版本，不是主分支版本。

@2.2.2 文件创建和修改时间：
文件创建时间应不晚于最早的提交时间。
分支版本使用新的文件创建时间，但父文件不再存在时都继承父文件创建时间。
文件修改时间应保证和对应提交时间一致，除非最近一次修订是回滚前一次操作。
当从其它分支合并或提交未在版本库中的文件时，文件创建时间可早于提交时间。

@2.2.3 文件版本号：
文件版本号表示版本的修订行数，即增加、删除、修改或移动的行的有效计数。
有多种计数时以较小者为准（如移动优先于修改）。
版本说明、修改时间的修改不列入计数。
除非一次修订仅涉及空行（这里指仅含空白符的行），对空行的修改不列入计数。
自 build 334 起严格执行（之前大部分文件版本号在新增时加入偏移而偏大）。
文件版本号以 Doxygen 指令 \version 标示。

@2.2.4 实体版本标识：
表示和文件版本号关联的版本，适用范围较文件版本号更广。
实体包括文件实体（文本文件）和程序实体（ ISO C++ 定义的实体，参见 ISO/IEC 14882 Clause 3 ）。
更新实体版本标识的充分必要条件是存在简单名称的变更的修订。
当从其它分支合并或提交未在版本库中的文件时，实体版本标识可早于提交版本。
实体版本标记以 Doxygen 指令 \since 标示。

@2.2.4.1 实体转移：
项目内部转移忽略以下变更：
对于文件，忽略目录路径变更；
对于代码中的宏和实体，忽略所在命名空间（若存在）、文件名及头文件公开性(@3.3) 变更。
项目间转移不忽略任何变更，按删除和添加处理。

@2.2.4.2 同名实体变更：
对于重载，不视为相同实体；
对于模版特化，不视为相同实体。
包括所有实体名称的链接（或对应实现的符号(symbol) 可见性(visibility)）变化；除此以外忽略所有 ISO C++ 或实现扩展的属性(attribute) 的变化。
对于函数、函数模板和模板特化，包括类型和默认参数变更；
对于类成员，包括访问权限变更。

@2.2.5 头文件包含守护宏(include guard marco) ：
除非重复包含不影响语义，否则应使用特定名称的宏以保证头文件不被包含超过一次。
一般包含模式如下：

#ifndef 宏名
#define 宏名 非零整数字面量

//被保护的代码，常以 #include 起始。

#endif

不同头文件应使用不同的宏名。
具体宏名由实现定义，一般应使用特定保留前缀（但不应与标准名称冲突，除非实现标准库，参见 [Documentation::CommonRules @@5.3.2.2.2] ）。

@3 组织约定：

@3.1 单元(unit) ：
编译单元简称单元，是一组包含源代码的文本文件，包含一个不作为头文件包含的源文件（默认后缀名 .cpp ）和若干个被这个源文件直接或间接包含的头文件，经过预处理后成为翻译单元(translation unit) 。
编译单元可以包含类/结构体等类型，以及 API（Application Programming Interface ，应用程序编程接口）的实现。
单元可以作为测试的基本单位之一，即进行单元测试(unit testing) 。

@3.2 模块和模块目录：
此处模块特指静态的组织构成单位。注意和一般意义的模块（参见 [Documentation::CommonRules @@3.7.1] ）之间的区别与联系。
一个单元或无源文件对应的头文件称为模块(module) 。一个模块目录是某个抽象路径中的模块的集合。
一个模块仅可属于一个模块目录。
模块和模块目录以类 C++ qualified-id 语法组成的名称表示，形式定义如下：
module-name:
	identifier
module-directory:
	identifier
	module-directory :: identifier
nested-module-name:
	module-name
	module-directory :: module-name
如无特别指明，以下使用的模块名称都是（简单）模块名 module-name 。
 :: 两边的空白仅作区分记号的示意，实际使用时和标识符之间不保留空格。
对于清晰的上下文，可以使用部分的模块名称。特别地，在标识库的组件时顶级的标识符（表示库的名称）通常省略。

@3.3 源文件组织：
用于存储源文件的文件系统中的一组目录称为模块目录。
典型情况下，模块目录包含存储公开头文件 "/include" 和存储其它源文件的 "/source"。
 "/include" 中的头文件是公开头文件，它的内容是公开的接口。公开头文件和 "/source" 中的不作为头文件包含的源文件对应组成的模块，称为公开模块。
 "/source" 包含的头文件不是公开头文件，它的内容不是公开的接口。非公开头文件可能和同一个目录下的其它源文件组成模块，称为非公开模块。

@4 程序部署：
使用 YFramework 和 YBase 需要维持目录结构。其它暂略。
关于 YReader 的部署配置参见 [Documentation::YSLib @@5] 。

@5 用户配置：
暂略。

*/
////

