贡献¶

Datasette 是一个开源项目。我们欢迎贡献！

本文档介绍了如何为 Datasette 核心做贡献。您也可以通过创建新的插件为更广泛的 Datasette 生态系统做出贡献。

一般准则¶

main 分支应始终保持可发布状态。未完成的功能应放在分支中。这确保了任何小的错误修复都可以快速发布。
理想的提交应包含实现、单元测试以及相关的文档更新。提交消息应链接到相关的 issue。
新的插件钩子只有在使用它们的非演示插件单独发布时才应发布。

设置开发环境¶

如果您的计算机上安装了 Python 3.7 或更高版本（在 OS X 上最快的方法是使用 homebrew），您可以使用以下步骤安装 Datasette 的可编辑副本。

如果您想使用 GitHub 发布您的更改，请首先在您自己的 GitHub 账户下创建 datasette 的 fork。

现在将该仓库克隆到您计算机上的某个位置

git clone git@github.com:YOURNAME/datasette

如果您想不创建自己的 fork 就开始，可以这样做

git clone git@github.com:simonw/datasette

下一步是为您的项目创建一个虚拟环境，并使用它来安装 Datasette 的依赖项

cd datasette
# Create a virtual environment in ./venv
python3 -m venv ./venv
# Now activate the virtual environment, so pip can install into it
source venv/bin/activate
# Install Datasette and its testing dependencies
python3 -m pip install -e '.[test]'

最后一行完成了大部分工作：pip install -e 意味着“以允许我原地编辑源代码的方式安装此软件包”。.[test] 选项意味着“使用此目录中的 setup.py 并同时安装可选的测试依赖项”。

运行测试¶

完成此操作后，您可以在 datasette/ 目录中使用 pytest 运行 Datasette 单元测试，如下所示

pytest

您可以使用 pytest-xdist 利用多个 CPU 核更快地运行测试，如下所示

pytest -n auto -m "not serial"

-n auto 自动检测可用的核心数。-m "not serial" 跳过在并行测试环境中运行不佳的测试。您可以单独运行这些测试，如下所示

pytest -m "serial"

使用 fixtures¶

要运行 Datasette 本身，输入 datasette。

您至少需要一个 SQLite 数据库。快速入门的方法是使用 Datasette 用于自身测试的 fixtures 数据库。

您可以运行此命令创建该数据库的副本

python tests/fixtures.py fixtures.db

现在您可以针对新的 fixtures 数据库运行 Datasette，如下所示

datasette fixtures.db

这将启动一个服务器，地址为 http://127.0.0.1:8001/。

您在 datasette/templates 或 datasette/static 文件夹中所做的任何更改都会立即生效（不过您可能需要在浏览器中强制刷新才能看到 CSS 或 JavaScript 的更改）。

如果您想更改 Datasette 的 Python 代码，可以使用 --reload 选项，使 Datasette 在底层代码更改时自动重新加载

datasette --reload fixtures.db

您还可以使用 fixtures.py 脚本重新创建单元测试使用的 metadata.json 测试版本。为此

python tests/fixtures.py fixtures.db fixtures-metadata.json

或者要输出测试使用的插件，运行此命令

python tests/fixtures.py fixtures.db fixtures-metadata.json fixtures-plugins
Test tables written to fixtures.db
- metadata written to fixtures-metadata.json
Wrote plugin: fixtures-plugins/register_output_renderer.py
Wrote plugin: fixtures-plugins/view_name.py
Wrote plugin: fixtures-plugins/my_plugin.py
Wrote plugin: fixtures-plugins/messages_output_renderer.py
Wrote plugin: fixtures-plugins/my_plugin_2.py

然后这样运行 Datasette

datasette fixtures.db -m fixtures-metadata.json --plugins-dir=fixtures-plugins/

调试¶

Datasette 运行时发生的任何错误都将在控制台上显示堆栈跟踪。

您可以使用 --pdb 选项告诉 Datasette 在发生错误时打开交互式 pdb 调试会话

datasette --pdb fixtures.db

代码格式化¶

Datasette 使用有风格倾向的代码格式化工具：Python 使用 Black，JavaScript 使用 Prettier。

这些格式化工具由 Datasette 的持续集成强制执行：如果提交包含与这些工具强制执行的风格不匹配的 Python 或 JavaScript 代码，测试将失败。

在本地开发时，您可以使用这些工具来验证和更正代码的格式。

运行 Black¶

运行 pip install -e '.[test]' 时将安装 Black。要测试您的代码是否符合 Black 规范，请在您的 datasette 仓库根目录中运行以下命令

$ black . --check
All done! ✨ 🍰 ✨
95 files would be left unchanged.

如果您的任何代码不符合 Black 规范，您可以运行此命令自动修复这些问题

$ black .
reformatted ../datasette/setup.py
All done! ✨ 🍰 ✨
1 file reformatted, 94 files left unchanged.

blacken-docs¶

blacken-docs 命令将 Black 格式化规则应用于文档中的代码示例。像这样运行它

blacken-docs -l 60 docs/*.rst

Prettier¶

要安装 Prettier，请安装 Node.js，然后在您的 datasette 仓库根目录中运行以下命令

$ npm install

这将在 node_modules 目录中安装 Prettier。然后您可以检查您的代码是否符合编码风格，如下所示

$ npm run prettier -- --check
> prettier
> prettier 'datasette/static/*[!.min].js' "--check"

Checking formatting...
[warn] datasette/static/plugins.js
[warn] Code style issues found in the above file(s). Forgot to run Prettier?

您可以通过运行以下命令修复任何问题

$ npm run fix

编辑和构建文档¶

Datasette 的文档位于 docs/ 目录中，并使用 Read The Docs 自动部署。

文档使用 reStructuredText 编写。您可能会发现这篇关于值得记住的 reStructuredText 子集的文章很有用。

您可以通过在 Datasette 开发环境中安装 sphinx 和 sphinx_rtd_theme，然后直接在 docs/ 目录中运行 make html 来在本地构建文档

# You may first need to activate your virtual environment:
source venv/bin/activate

# Install the dependencies needed to build the docs
pip install -e .[docs]

# Now build the docs
cd docs/
make html

这将在 docs/_build/html 中创建文档的 HTML 版本。您可以像这样在浏览器中打开它

open _build/html/index.html

每当您更改 .rst 文件时，您可以重新运行 make html 来更新构建的文档，然后在浏览器中刷新它们。

为了提高效率，您可以使用 sphinx-autobuild 在自动构建模式下运行 Sphinx。这将运行一个本地 Web 服务器，提供文档服务，每当您在编辑器中保存时，它会自动重新构建文档并刷新页面。

运行 pip install -e .[docs] 时将安装 sphinx-autobuild。在您的 docs/ 目录中，您可以通过运行以下命令启动服务器

make livehtml

现在浏览到 http://localhost:8000/ 查看文档。您进行的任何编辑都应立即反映在浏览器中。

运行 Cog¶

文档的某些页面（特别是 CLI 参考）使用 Cog 自动更新。

要更新这些页面，运行以下命令

cog -r docs/*.rst

持续部署的演示实例¶

latest.datasette.io 上的演示实例会在每次通过测试套件的 main 推送时自动重新部署到 Google Cloud Run。这是通过 .github/workflows/deploy-latest.yml 中的 GitHub Actions 工作流程实现的。

通过将它们添加到工作流程 YAML 文件顶部的 on: push: branches 块中，也可以设置特定分支自动部署。这样配置的分支将部署到新的 Cloud Run 服务，无论其测试是否通过。

分支演示的 Cloud Run URL 可以在 GitHub Actions 日志中找到。

发布流程¶

Datasette 发布是使用标签进行的。当在 GitHub 上发布新版本时，GitHub Action 工作流程将执行以下操作

对所有支持的 Python 版本运行单元测试。如果测试通过...
构建该版本的 Docker 镜像并推送一个标签到 https://hub.docker.com/r/datasetteproject/datasette
将 Docker Hub 上的“latest”标签重新指向新的镜像
构建底层 Python 源代码的 wheel 包
将新的 wheel 推送到 PyPI：https://pypi.ac.cn/project/datasette/

要部署新版本，您需要对主要的 Datasette GitHub 仓库具有推送权限。

Datasette 遵循语义版本控制（Semantic Versioning）

major.minor.patch

对于向后不兼容的版本，我们增加 major 版本号。Datasette 目前处于 1.0 之前，因此主版本号始终是 0。

对于新功能，我们增加 minor 版本号。

对于错误修复版本，我们增加 patch 版本号。

Alpha 和 Beta 版本可能带有额外的 a0 或 b0 前缀 - 整数部分会随着后续的 alpha 或 beta 版本而递增。

要发布新版本，首先创建一个提交，更新 datasette/version.py 中的版本号，并在更新日志中突出新版本的主要内容。一个示例提交可以在这里看到

# Update changelog
git commit -m " Release 0.51a1

Refs #1056, #1039, #998, #1045, #1033, #1036, #1034, #976, #1057, #1058, #1053, #1064, #1066" -a
git push

在提交消息中引用包含在发布中的 issue，可以确保发布名称显示在这些 issue 页面上，例如这里。

您可以将发布说明或 GitHub 自上次发布以来的更改视图中的文本复制粘贴到这个从粘贴文本中提取 issue 号工具中，为特定发布生成 issue 引用列表。

要为该发布创建标签，请在 GitHub 上创建新版本，使其与新版本号匹配。您可以通过将渲染的 HTML 复制粘贴到这个粘贴到 Markdown 工具中，将发布说明转换为 Markdown。

最后，通过编辑 news.yaml 文件在该网站的仓库中，在 datasette.io 上发布关于该版本的新闻条目。

Alpha 和 Beta 发布¶

发布 Alpha 和 Beta 版本是为了预览可能尚未稳定的即将推出的功能——特别是为了预览新的插件钩子。

欢迎您试用这些版本，但请注意，在最终版本发布之前，细节可能会发生变化。

请加入issue 跟踪器上的讨论，分享您试用 alpha 和 beta 功能的想法和经验。

从分支发布错误修复¶

如果需要在不发布已合并到 main 分支的新功能的情况下发布错误修复版本，可以使用发布分支。

从相关的最后标记的发布版本创建分支，如下所示

git branch 0.52.x 0.52.4
git checkout 0.52.x

接下来挑选包含错误修复的提交 (cherry-pick)

git cherry-pick COMMIT

在该分支中编写发布说明，并更新 version.py 中的版本号。然后推送分支

git push -u origin 0.52.x

测试完成后，使用 GitHub 的创建新版本草稿表单从该分支目标发布版本。

最后，将包含发布说明和版本号更新的提交挑选到 main 分支

git checkout main
git cherry-pick COMMIT
git push

升级 CodeMirror¶

Datasette 集成了用于 SQL 编辑界面的 CodeMirror，例如在此页面上。以下是升级到新版本 CodeMirror 的步骤

从 https://codemirror.net/codemirror.zip 下载并解压最新的 CodeMirror zip 文件
将 lib/codemirror.js 重命名为 codemirror-5.57.0.js（使用最新的版本号）
将 lib/codemirror.css 重命名为 codemirror-5.57.0.css
将 mode/sql/sql.js 重命名为 codemirror-5.57.0-sql.js
编辑两个 JavaScript 文件，将顶部的许可证注释更改为 /* */ 块，而不是多个 // 行

像这样压缩（Minify）JavaScript 文件

npx uglify-js codemirror-5.57.0.js -o codemirror-5.57.0.min.js --comments '/LICENSE/'
npx uglify-js codemirror-5.57.0-sql.js -o codemirror-5.57.0-sql.min.js --comments '/LICENSE/'

检查 LICENSE 注释是否确实在压缩后保留了下来

像这样压缩（Minify）CSS 文件

npx clean-css-cli codemirror-5.57.0.css -o codemirror-5.57.0.min.css

编辑 _codemirror.html 模板以引用新文件
git rm 删除旧文件，git add 添加新文件