FreeKill/docs/dev/package.rst

.. SPDX-License-Identifier: GFDL-1.3-or-later

FreeKill 的包管理策略
=====================

FreeKill使用git进行包管理，具体而言是使用libgit2库进行管理。

包的组织
--------

所有拓展包都位于packages/目录下。其中，standard（标包）、standard_cards（标包卡牌）和manuvering_cards（军争卡牌，
TODO
）属于基础拓展，其直接处于FreeKill的项目仓库之下。其他所有的拓展均处于项目之外。

每个拓展包都是一个单独的文件夹，内含代码文件（init.lua，以及诸如其他lua文件和fkp文件等等）和音图等资源文件。关于具体如何组织各种文件，请参照已有的拓展包。

包的管理
--------

包管理使用git，以下使用类似git命令行的方式解说。

首先，packages中除了基本的三个包之外，其他的包都要从仓库中排除掉。这方面由一个.gitignore文件控制。

然后，在packages目录下，有一个名为packages.db的文件统领所有拓展包。这是个sqlite数据库，结构详见\ :doc:`./database`\ 。

下面从连接过程中简要分析这个文件的作用：

1. 当一个客户端尝试对服务端发起连接请求的时候，首先它们之间会先比较MD5值。
2. 如果MD5通过则无事发生，否则服务端会把自己的packages.db中的关键信息发送给客户端。
3. 客户端根据文件内容检查自己的拓展包。如果那个文件夹存在，那么就git
   fetch -> git checkout <hash>。
4. 如果文件夹不存在，那么先git clone，然后再checkout。
5. 做完这些后，客户端再次发起请求。若仍不通过，则向用户通知错误信息。

在这个过程中，如果出现任何一个文件夹内有未提交的更改（拓展包开发者有时候可能因为疏忽而未通过MD5检查），或者出现根本不是git仓库的文件夹，那么都会直接进入报错环节。

有时候客户端会包含服务端所没有的拓展包，这时候比起直接删除之，更加明智的选择是将其标记为禁用。将拓展包文件夹的名字设为xxx.disabled即可将拓展包标记为禁用的拓展包。禁用的拓展包不会被游戏加载，也不会被MD5检测计入。

包的托管
--------

一般来说都是推荐将项目放在github上面的，但由于FreeKill暂且不考虑国际化且必须照顾广大玩家的体验，因此将拓展包托管到github可能不是一个明智的选择。推荐将拓展包托管到gitee平台，或者其他的好办法也行。

总之有一点要注意的是，packages.db中的url需要是国内访问比较方便的网站才行。

包的部署
--------

此处不讨论具体如何编写代码，单论在这个管理框架下如何进行开发。

一般来说，在对一个仓库进行开发时，由于目前各托管平台都用SSH
Key认证而非用户名密码，因此仓库的URL通常为git@gitxxx.com:xxxx/xxxx.git。这样的URL有一个问题就在于只有认证过的用户可以clone，而非所有人。

因此在部署的时候，一定要保证所有url都是https://xxxx。这一点FreeKill是不会进行检测的。

包的下载与更新（TODO）
----------------------

客户端使用GUI，服务端使用Fk shell或者直接编辑packages.db。