byggleaf 0.1.0__tar.gz

byggleaf-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# 变更日志
+
+本文件记录 ByggLeaf 的重要变更。版本号的唯一来源是 `pyproject.toml`。
+
+## 未发布
+
+### 新增
+
+- 首页、分页页和独立页面输出 canonical、description 与 Open Graph 元数据。
+- 自动生成 `sitemap.xml` 与 `rss.xml`。
+- 所有页面 `<head>` 增加 RSS 与站点地图发现链接。
+- 构建开始时自动恢复中断的发布，并清理遗留 staging 目录。
+- 预检阶段增加输出路径冲突检测。
+- 增加 HTML/无障碍结构测试和 HTTP 预览冒烟测试。
+- CI 增加 Ruff、mypy、覆盖率、wheel 构建和安装冒烟。
+- tag push 后由 `publish.yml` 自动校验、构建、发布 PyPI 并创建 GitHub Release。
+- README 增加本地化状态表，CONTRIBUTING 增加本地化指南。
+- 使用 GPL-3.0-or-later 许可证。
+
+### 变更
+
+- 语言文件按规范 BCP 47 标签精确匹配，不再提供地区回退。
+- 缺少或为空的翻译 key 会显示 key 名，不再中断构建。
+- 发布失败时恢复旧 `public/`；下一次构建修复崩溃残留。
+
+## 0.1.0
+
+- 初始版本：Markdown 文章与独立页面、分页、固定模板、原生 CSS、
+  零 JavaScript、构建/预览/清理命令、文章 SEO 与内置界面翻译。

byggleaf-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# 为 ByggLeaf 贡献
+
+ByggLeaf 是一个刻意保持狭窄、有主见的个人数字花园静态网站生成器。它**不是**
+通用 SSG，也没有主题、插件、自定义模板、自定义 CSS/JS 或任意输出管线的路线图。
+把它推向通用平台的方向会被拒绝。
+
+欢迎的贡献包括：
+
+- 正确性和安全性修复；
+- 无障碍和 HTML 质量修复；
+- 构建与发布可靠性改进；
+- 翻译；
+- 让固定模型更容易理解的文档。
+
+## 开发
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check .
+mypy byggleaf
+coverage run -m unittest discover -s tests -v
+coverage report
+python -m build
+```
+
+测试使用标准库 `unittest`。不要增加运行时依赖：安装后的包只能依赖 `markdown`
+和 `jinja2`。开发工具放在 `dev` 可选依赖组中。
+
+## 本地化
+
+语言标签必须是规范的 BCP 47 标签，文件名必须正好是该标签加 `.toml`，例如：
+
+```text
+locales/zh-CN.toml
+locales/zh-HK.toml
+locales/yue.toml
+```
+
+没有回退机制。`zh-SG` 不会使用 `zh-CN`，必须有自己的 `zh-SG.toml`。缺少文件时
+会报错并列出所有可用语言文件。
+
+### 新增语言
+
+1. 复制最接近的现有语言文件，例如：
+
+   ```bash
+   cp byggleaf/locales/zh-CN.toml byggleaf/locales/zh-SG.toml
+   ```
+
+2. 翻译 `[ui]` 下的每个值。缺失或为空的 key 会在运行时显示 key 名，因此部分翻译
+   的文件可以安全加载；但合并进包的内置语言文件仍应保持完整。
+
+3. 保持标签规范：
+
+   - 语言小写；
+   - 文字系统首字母大写，例如 `Hans`、`Hant`；
+   - 地区大写，例如 `CN`、`HK`、`TW`。
+
+4. 在 README 状态表中用准确代码和 ✅/❌ 标出支持情况。
+
+5. 运行数据驱动的本地化测试：
+
+   ```bash
+   python -m unittest tests.test_locales tests.test_architecture -v
+   ```
+
+测试会扫描 `locales/*.toml`，故意不维护硬编码的支持语言列表。新增语言文件不应
+需要修改测试预期列表。
+
+6. 如果语言文件仍不完整，README 中保持 ❌。不要把半成品文件作为内置语言合并。
+
+## 提交请求
+
+- 保持架构单向：`app` 负责装配，`cli` 不导入 `core`，`core` 不导入入口层。
+- 不要向模板或 Markdown 输出加入 JavaScript。
+- 不要增加用户可覆盖的模板或主题钩子。
+- 每个行为变更都要有测试。
+- 用户可见输出保持克制、明确；错误要说明失败原因和下一步。
+
+## 许可证
+
+提交贡献即表示你同意该贡献按 GPL-3.0-or-later 授权，与本项目许可证一致。