grimoirelab/sortinghat

Sorting Hat

概述和主要用途

Sorting Hat 是一款管理身份的工具。它维护一个SQL数据库，存储来自不同来源的身份信息。对应同一真实人物的身份可合并为具有唯一UUID的唯一身份，并可为每个唯一身份定义个人资料，包含默认显示的姓名和其他数据。此外，每个唯一身份可关联一个或多个不同时间段的隶属关系，通常对应个人在这些时间段内受雇的不同组织。

Sorting Hat 是 https://grimoirelab.github.io 的一部分，该工具集提供Python模块和脚本，用于分析软件开发相关的数据源信息，并生成交互式仪表板进行数据可视化。在GrimoireLab中，Sorting Hat通常在使用 https://github.com/grimmoirelab/perceval 获取数据后运行，将获取的身份存储到数据库中，随后合并为唯一身份（可能还会关联隶属关系）。

核心功能和特性

• 身份管理：维护SQL数据库中的身份信息，支持添加、删除身份。
• 身份合并：将来自不同来源的同一人身份合并为唯一身份，分配唯一UUID。
• 个人资料：为唯一身份定义个人资料，包含默认显示的姓名、***等信息。
• 隶属关系管理：关联唯一身份与不同时间段的隶属关系，记录个人在不同组织的任职情况。
• 组织和域名管理：支持添加、删除组织及关联域名。
• 数据导入导出：可导入/导出身份、组织等数据。
• 黑名单管理：管理黑名单条目。

使用场景和适用范围

Sorting Hat 主要用于软件开发数据分析领域，作为GrimoireLab工具集的关键组件，适用于以下场景：

• 整合来自代码仓库、邮件列表、Issue跟踪系统等不同数据源的开发者身份信息。
• 解决同一开发者在不同平台使用不同身份（如不同用户名、***）导致的数据分散问题。
• 维护开发者的组织隶属关系历史，支持按时间段分析开发者与组织的关联。
• 为软件开发数据可视化仪表板提供准确、整合的身份和隶属关系数据。

详细使用方法和配置说明

安装

Docker 安装（推荐）

可直接使用DockerHub上的镜像 grimoirelab/sortinghat，或自行构建镜像：

sh
# 从DockerHub拉取镜像（推荐）
docker pull grimoirelab/sortinghat

# 或自行构建镜像
docker build -t grimoirelab/sortinghat .

启动依赖的MySQL容器

Sorting Hat需要MySQL数据库存储数据，首先启动MySQL容器：

sh
docker run --name mysql \
             -e MYSQL_ROOT_PASSWORD=sortinghat \
             -d mysql

运行Sorting Hat容器

以交互模式运行Sorting Hat容器，并链接到MySQL容器：

sh
docker run -i -t --rm \
             --link mysql:mysql \
             -e SORTINGHAT_DB_HOST=mysql \
             -e SORTINGHAT_DB_PASSWORD=sortinghat \
             -e SORTINGHAT_DB_DATABASE=sortinghat \
             grimoirelab/sortinghat \
             /bin/bash

初始化数据库

进入容器后，初始化Sorting Hat数据库：

sh
sortinghat init sortinghat

命令用法

Sorting Hat提供多种命令，基本用法如下：

usage: sortinghat [--help] [-c <file>] [-u <user>] [-p <password>]
                  [--host <host>] [--port <port>] [-d <name>]
                  command [<cmd_args>]

常用命令包括：

• add: 添加身份
• affiliate: 关联身份隶属关系
• autoprofile: 自动补全个人资料
• blacklist: 管理黑名单
• config: 获取/设置配置参数
• countries: 列出国家信息
• enroll: 将身份加入组织
• export: 导出数据（如身份）
• init: 创建空注册表
• load: 导入数据（如身份、组织）
• merge: 合并唯一身份
• mv: 将身份移至唯一身份
• log: 列出注册信息
• orgs: 管理组织和域名
• profile: 编辑个人资料
• rm: 从注册表中删除身份
• show: 显示唯一身份信息
• unify: 使用匹配算法合并身份
• withdraw: 将身份从组织中移除

运行 sortinghat <command> --help 获取特定命令的详细信息。

配置

可通过 config 命令或环境变量设置数据库参数。

通过 config 命令配置

sh
# 设置数据库主机
sortinghat config set db.host <mysql-host>
# 设置数据库用户
sortinghat config set db.user <user>
# 设置数据库密码
sortinghat config set db.password <password>
# 设置数据库名称
sortinghat config set db.database <name>
# 设置数据库端口
sortinghat config set db.port <port>

通过环境变量配置

sh
export SORTINGHAT_DB_HOST=<mysql-host>
export SORTINGHAT_DB_USER=<user>
export SORTINGHAT_DB_PASSWORD=<password>
export SORTINGHAT_DB_DATABASE=<name>
export SORTINGHAT_DB_PORT=<port>

配置后初始化数据库：

sh
sortinghat init <database-name>

基本命令示例

添加唯一身份

sh
# 添加包含姓名、邮箱、用户名和来源的身份
sortinghat add --name "John Smith" --email "jsmith@example.com" --username "jsmith" --source scm
# 输出：New identity a9b403e150dd4af8953a52a4bb841051e4b705d9 to a9b403e150dd4af8953a52a4bb841051e4b705d9

设置个人资料

sh
# 为指定UUID的身份设置个人资料
sortinghat profile --name "John Smith" --email "jsmith@example.com" --country US a9b403e150dd4af8953a52a4bb841051e4b705d9

合并身份

sh
# 合并两个唯一身份
sortinghat merge a7637bb1737bc2a83f3a3e25b9b441cba62d97c2 a9b403e150dd4af8953a52a4bb841051e4b705d9

管理组织和隶属关系

sh
# 添加组织
sortinghat orgs -a Example
# 为组织添加域名
sortinghat orgs -a Example example.com --top-domain
# 将身份加入组织（指定时间段）
sortinghat enroll --from 2014-06-01 --to 2015-09-01 a9b403e150dd4af8953a52a4bb841051e4b705d9 Example

导入/导出数据

sh
# 导入数据
sortinghat load sh.json
# 导出身份
sortinghat export --identities sh_ids.json
# 导出组织
sortinghat export --orgs sh_orgs.json

版本兼容性

• 0.5.0之前版本：数据库架构不兼容，需执行以下SQL语句更新：

  sql
  ALTER TABLE uidentities ADD COLUMN last_modified DATETIME(6) DEFAULT NULL;
  ALTER TABLE identities ADD COLUMN last_modified DATETIME(6) DEFAULT NULL;
  

• 0.3.0之前版本：身份UUID生成种子改变，需通过导出-删除数据库-重新初始化-导入的方式迁移数据：

  sh
  # 导出数据
  sortinghat export --orgs orgs.json
  sortinghat export --identities identities.json
  # 重新初始化数据库
  sortinghat init <new-db-name>
  # 导入数据
  sortinghat load orgs.json
  sortinghat load identities.json
  

系统要求

• Python：2.7 及 >= 3.4
• MySQL：>= 5.5
• 依赖库：SQLAlchemy >= 1.0.0、Jinja2 >= 2.7、python-dateutil >= 2.6、python-yaml >= 3.12
• MySQL Python驱动：推荐 MySQLdb（仅Python 2.7）或 PyMySQL
• 可选：python-pandas >= 0.15（加速匹配过程）

许可证

采用 GNU General Public License (GPL) 许可证，版本 3 或更高。

源代码和贡献

源代码托管在 https://github.com/grimoirelab/sortinghat%E3%80%82%E6%AC%A2%E8%BF%8E%E6%8F%90%E4%BA%A4%E6%8B%89%E5%8F%96%E8%AF%B7%E6%B1%82%E8%B4%A1%E7%8C%AE%E4%BB%A3%E7%A0%81%EF%BC%8C%E6%88%96%E9%80%9A%E8%BF%87 issue 报告 bug、请求新功能。