贡献

我们非常高兴欢迎新的贡献者加入slidgeqq！在开始之前，请加入 我们的聊天室 打个招呼，看看是否已经有人在处理你想修复的bug或想实现的功能。

快速开始

要开始开发slidgeqq，你需要：

  1. 克隆仓库：git clone https://codeberg.org/slidge/slidgeqq。

  2. 安装所需的依赖项。（见下文）

  3. 启动一个供slidgeqq连接的开发用XMPP服务器。（见下文）

简单模式：docker-compose

同时完成步骤2和3最简单的方法是使用提供的 docker-compose.yml 文件。在你刚刚克隆的仓库目录中运行 docker compose up``（或 ``podman-compose up）。它将：

  • 启动一个为开发配置的 prosody 实例；

  • 在一个专用容器中启动slidgeqq，并支持热代码重载。

然后，你就可以使用任何XMPP客户端连接到那个prosody服务器，使用"test@localhost"作为JID，"password"作为密码。我们推荐使用 gajim，它允许你启动一个不同于主配置文件的配置文件：gajim -p slidge -c ~/.local/share/gajim-slidge。

为了避免接受自签名证书，你可以将prosody的证书添加到本地存储中。在Debian系统中，你可以这样做：

# download the certificate
curl https://codeberg.org/goodspeed/prosody-dev-container/raw/branch/main/localhost.crt | sudo tee /usr/local/share/ca-certificates/localhost.crt
# set the right perms
sudo chmod 600 /usr/local/share/ca-certificates/localhost.crt
# import it
sudo update-ca-certificates

稍难模式：设置虚拟环境

在某些情况下，在容器中进行开发并不理想，例如，如果你想将交互式调试器附加到slidgeqq进程。

slidgeqq在一个符合 PEP 517 标准的 pyproject.toml 文件中定义了其依赖项。这意味着你可以使用不同的工具来设置一个包含适当依赖项的虚拟环境。

我们推荐使用 uv，它速度快且有一些不错的功能。通过运行 uv sync --frozen --all-groups --all-extras，一个标准的虚拟环境将被安装到 ./.venv 中。然后你可以使用 source .venv/bin/activate 激活它，并运行 slidgeqq --help。

注意：你需要设置一个本地 XMPP 服务器。一个简单的方法是使用 slidge-prosody-dev 容器：docker run --network host codeberg.org/goodspeed/prosody-slidge-dev。使用它，你将能够通过 slidgeqq --jid slidge.localhost --secret secret --debug --home-dir ./persistent 启动 slidgeqq。

同时修改 slidge 核心

也许你会发现你想要更改、添加或修复的部分并不在 slidgeqq 中，而是在 slidge 核心中。要修改 slidge 核心，首先你需要在计算机上的某个位置克隆 slidge 仓库。

假设你将 slidge 克隆在与 slidgeqq 相同的根目录下，例如 ~/src/slidgeqq 和 ~/src/slidge。在使用基于 docker-compose 的开发设置时，你需要为 slidge 目录添加一个额外的挂载，例如 ../slidge:/build/slidge。如果你选择了 virtualenv 方案，你可以使用 [uv] pip install -e ../slidge 以可编辑模式在你的 virtualenv 中安装 slidge。

指南

slidgeqq 使用以下工具来确保一定程度的代码质量：

  • mypy 用于静态类型检查，

  • ruff 用于检测常见的 Python 错误并强制执行一致的代码风格，

  • pytest 用于自动化测试。

提交信息应采用 约定式提交 的形式，并包含 ./commitlinx.config.js 中定义的一些附加类型。这使得在发布时自动生成变更日志成为可能，这是值得的！我们使用 git-cliff 来实现这一点。你无需在本地安装 git-cliff，这些魔法在 CI 中完成。

我们建议设置 pre-commit 以确保每次提交都能通过这些检查：pre-commit install && pre-commit install --hook-type commit-msg。

创建一个新的 git 分支，提交你的更改，将其推送到你的复刻仓库并打开一个拉取请求！

注意：我们也接受不通过拉取请求的贡献。只需将您的更改推送到某处，并通过群聊告知我们从何处拉取。