Stackalytics

注意事项

Stackalytics.com 是由 Mirantis 运营和托管的服务

Stackalytics.io 是由 Stackalytics 核心团队成员在 support@stackalytics.io 处私下运营和托管的替代服务

使命

Stackalytics 项目的目标是提供关于对许多开源项目贡献的透明且有意义的统计数据。但是，“透明且有意义”意味着什么？透明度很重要，以便社区可以确信所有计算都是正确和公平的。因此，“透明”意味着任何人都可以复查 Stackalytics 使用的计算方法。与此同时，结果必须有意义才能有用。“有意义”意味着任何人都可以提交更正，从而调整适当统计数据的权重。例如，自动生成的代码、批量重命名、自动重构、自动生成的配置文件等可能会人为地夸大各种统计数据。Stackalytics 可以在发现这些问题时避免这些问题。

描述

Stackalytics 是一项收集和处理开发活动数据（如提交、修改的代码行数、代码评审、蓝图等）的服务，并使其能够在便捷的 Web 控制面板中可视化。Stackalytics 控制面板可以按项目、公司、贡献者和其他因素查看数据。

Stackalytics 的主要数据来源是 Git 仓库、Gerrit 代码评审历史记录（或 GitHub 活动）。

Git 提交历史

Stackalytics 处理三个主要的贡献指标

提交数量
修改的文件数量
修改的行数

基本的代码相关统计信息是从以下命令的输出中检索的

git log --pretty="commit_id:'%H%ndate:%at%nauthor:%an%nauthor_email:%ae%nsubject:%s%nmessage:%b%n'" --shortstat -M --no-merges

此命令的输出如下所示

commit_id:b5a416ac344160512f95751ae16e6612aefd4a57
date:1369119386
author:Akihiro MOTOKI
author_email:motoki@da.jp.nec.com
subject:Remove class-based import in the code repo
message:Fixes bug 1167901
This commit also removes backslashes for line break.
Change-Id: Id26fdfd2af4862652d7270aec132d40662efeb96
diff_stat:
21 files changed, 340 insertions(+), 408 deletions(-)

此提交更改了 21 个文件和 340 + 408 = 748 行代码 (LOC)。即 LOC 是插入和删除的总和。

公司隶属关系

每个提交作者的公司隶属关系根据以下规则确定

首先，Stackalytics 检查作者的电子邮件域名。如果域名在 Stackalytics 配置文件 (default_data.json) 中，则根据电子邮件地址确定提交的隶属关系。
如果电子邮件域名没有提供足够的信息，Stackalytics 会使用电子邮件地址从 LaunchPad 中检索作者资料。如果 LaunchPad 没有识别作者，则除非下一步提供足够的信息来确定作者的隶属关系，否则该提交将隶属于 *independent*。
接下来，LaunchPad ID 用作进一步作者识别的主要键。Stackalytics 在相同的配置文件 (default_data.json) 中存储已知贡献者的资料。此资料具有贡献者隶属关系的历史列表。例如

      {
           "launchpad_id": "boris-42",
           "companies": [
               {
                   "company_name": "*independent",
                   "end_date": "2013-Apr-10"
               },
               {
                   "company_name": "Mirantis",/* Git commits history */ 
                   "end_date": null
               }
           ],
           "user_name": "Boris Pavlovic",
           "emails": [
               "boris@pavlovic.me"
           ]
       },

如上所示，Stackalytics 具有 *company_name* 和 *end_date*。这些信息足以根据提交的日期确定任何给定提交的隶属关系，以便为在多家公司工作过的个人正确归因其提交。

最后，如果以上所有检查都失败，则该提交将隶属于 *independent*。

如果您的公司隶属关系或电子邮件地址在 Stackalytics 中没有正确反映，您可以将正确的信息添加到 default_data.json 文件中。

为此，克隆 https://github.com/stackalytics/default_data 仓库，然后在 default_data.json 文件中添加新记录或更新现有记录。该文件不在通常的 OpenStack 层次结构之外，并且不经过正常的 Gerrit 审批流程；只需进行更改并提交 GitHub pull request。一旦 PR 合并，更改将在数据库重建的下一次（12 小时内）生效。

stackalytics.io 使用 https://opendev.org/x/stackalytics/src/branch/master/etc/default_data.json，通过正常的 OpenDev Gerrit 流程。

头像

我们为 Stackalytics 用户头像使用 Gravatar。对于相关的 gravatar，使用与记录关联的电子邮件，对于资料 - 使用 https://opendev.org/x/stackalytics/src/branch/master/etc/default_data.json 的用户资料部分中的第一个电子邮件。如果用户在 default_data.json 中没有部分，则使用按字母顺序排列的第一个被识别为属于用户资料的电子邮件。

Gerrit 代码评审历史

Gerrit 提供了一个命令行界面来检索评审源数据。授权用户可以通过 ssh 连接到 review.openstack.org 并执行以下命令

gerrit query --all-approvals --patch-sets --format JSON module branch:master limit:100

s 此命令输出 module 上最新评审的列表。Stackalytics 解析此信息并将其存储在运行时存储中。Web 前端轮询运行时存储以获取任何新记录和现有记录的更改，并将数据检索到内存中以进行实时处理。

Stackalytics 为评审提供以下分析

评审数量
正面和负面评审的统计信息
正面与负面评审的比例。

邮件列表活动

Stackalytics 通过基于 Web 的 OpenStack-dev 存档轮询邮件列表活动。在 Stackalytics 控制面板中，邮件列表活动以与提交和评审相同的方式呈现。Stackalytics 搜索以下位置以选择电子邮件相关的 OpenStack 模块，顺序如下

电子邮件主题中的方括号中的模块名称
电子邮件正文中指向蓝图或错误的 HTTP 链接
电子邮件主题中没有方括号的模块名称

如果以上位置没有产生已知模块，则电子邮件将归因于“unknown”模块。

跟踪的网页列表和邮件存档在 default_data.json 的“mail_lists”部分中管理。

蓝图和 Bug 上的活动

LaunchPad 提供了一个 API 用于蓝图和 Bug 跟踪。Stackalytics 轮询 LaunchPad 并提供关于蓝图和 Bug 活动的标准向下钻取分析。Stackalytics 控制面板中有四个指标描述蓝图：“已完成的蓝图”、“草稿蓝图”、“已提交的 Bug”和“已解决的 Bug”。“已完成的蓝图”显示已完成的蓝图并列出努力将蓝图交付到上游代码的人员，而“草稿蓝图”显示 LaunchPad 中的所有蓝图并列出每个蓝图的原始作者。

除了这种标准分析之外，还有两个额外的报告。第一个显示特定蓝图的活动历史记录（通过蓝图名称上的链接可用），第二个为特定模块的蓝图提供参考分析（蓝图流行度）。

提交指标修正和一种“常识”方法

OpenStack 贡献的历史表明，由于不具代表性的提交（例如代码自动生成或自动代码重构），代码行数 (LOC) 指标不可靠。最著名的例子是

将 Quantum 重命名为 Neutron Change-Id: Ib86e068aa8e4f48993809b6b25444407b7c1f17e
从 Transifex 更新翻译 Change-Id: I4810c45d15413bdf21b9f68f59096c907bb1e624

Stackalytics 提供了一个社区驱动的修正流程框架。它的工作原理如下。修正存储在 Stackalytics 仓库中的 corrections.json JSON 文件中。这些修正如下所示

{
   "corrections": [
       {
           "commit_id": "ee3fe4e836ca1c81e50a8324a9b5f982de4fa97f",
           "correction_comment": "Reset LOC to 0",
           "lines_added": 0,
           "lines_deleted": 0
       }
   ]
}

这些记录的结构是自描述的，任何 OpenStack 贡献者都可以提交 Bug 并提供补丁集以应用于此文件，以应用特定的修正。此补丁集经过标准评审流程，一旦合并到上游项目，更改将立即在 Stackalytics 数据中可见。请注意，此流程由社区驱动，不应用于不当操纵统计数据。修正的提交在 Web 控制面板中以红色注释标记，并且完全透明，以便其他人可以提出进一步的挑战。

设计此框架是为了使统计数据更可靠和具有代表性。应使用以下“常识”方法

包含自动生成文件的提交应进行调整，以表示贡献者实际产生的努力量，不包括生成输出。
包含自动代码重构结果的提交应相应地进行调整。
由于不正确重命名文件（“shell”重命名而不是“git”重命名）而导致的提交应归零。
包含二进制和第三方文件的提交应相应地进行调整。

默认修正文件包含过去两个发布周期（Grizzly 和 Havana）中 LOC 高于 3000 的手动筛选提交。

跟踪的项目和分类

Stackalytics 能够跟踪使用标准 OpenStack 开发基础设施（Git、Gerrit 和 Launchpad）的任何项目。在最高级别，所有项目分为两个主要组：OpenStack（在 governance 的 projects.yaml 中列出的官方项目）和 OpenStack Others（托管在 openstack 中，但未正式列出）。此分类由 http://git.openstack.org/cgit 中的组织帐户确定。Stackalytics 在其主配置文件中存储项目列表。任何 OpenStack 贡献者都可以提交 Bug 并提供补丁集以添加未跟踪的项目。repos 部分表示跟踪的项目列表。它具有以下格式

   "repos": [
       {
           "module": "nova",
           "uri": "git://github.com/openstack/nova.git",
           "releases": [
               {
                   "release_name": "Essex",
                   "tag_from": "2011.3",
                   "tag_to": "2012.1"
               },
               {
                   "release_name": "Folsom",
                   "branch": ["stable/folsom"],
                   "tag_from": "2012.1",
                   "tag_to": "2012.2"
               },
               {
                   "release_name": "Grizzly",
                   "branch": ["stable/grizzly"],
                   "tag_from": "2012.2",
                   "tag_to": "2013.1"
               },
               {
                   "release_name": "Havana",
                   "tag_from": "2013.1",
                   "tag_to": "HEAD"
               }
           ]
       }
 ]

提供 git 标签或已知发布周期的 commit_id 至关重要。否则，Stackalytics 将根据提交日期将提交归因于发布周期。发布周期的结束日期在 Stackalytics 的配置文件的“releases”部分 default_data.json 中指定。默认情况下，Stackalytics 跟踪“master”分支，但可以为每个特定发布指定稳定分支的名称。OpenStack 项目根据其官方 https://git.openstack.org/cgit/openstack/governance/plain/reference/programs.yaml 进行分类。对于 OpenStack 项目，确定了以下组

integrated - 在 https://git.openstack.org/cgit/openstack/governance/plain/reference/programs.yaml 中具有 integrated-since 属性
incubated - 具有 incubated-since 属性
documentation - 列在 Documentation 部分
infra - 诸如 zuul 和 jenkins-job-builder 等对于整体项目基础设施是必需的，但技术上不属于 OpenStack 的项目。列在 Infrastructure 部分。
other - 托管在 OpenStack GitHub 仓库中且未按上述规则分类的项目。

Stackalytics 能够自动配置大多数 OpenStack 项目。为此，Stackalytics 配置文件 default_data.json 包含“project_sources”部分。它是一个包含项目分类所需属性的 Git 仓库列表。例如，记录

       {
           "organization": "openstack",
           "exclude": ["openstack", "gantt", "python-ganttclient"]
       },

表示来自 Git OpenStack 仓库的所有项目都将归因于“project_type”: “openstack”。自动导入项目的发布周期边界将根据提交日期进行归因。默认情况下，自动导入项目仅跟踪“master”分支。

Stackalytics 提供了一种机制，可以将多个项目分组到模块下拉菜单中的一个项目下。这些组可以手动配置在 module_groups 部分。对于所有官方程序，相应的模块组是根据官方程序列表自动创建的。

OpenStack 基金会成员

Stackalytics 轮询 openstack.org 成员目录以获取新注册信息，并提供关于此数据的向下钻取报告。用户可以获取有关过去一周/月/季度加入的新成员/公司的统计信息。成员隶属关系是根据 openstack.org 上的用户资料中的启发式方法确定的。

DriverLog

Stackalytics 根据 DriverLog api 提供的外部 CI 测试运行状态提供报告。

发行说明

Release 0.5/0.6

基于 programs.yaml 实现模块分类，并进行回顾性集成/孵化归属
修复了性能和内存消耗问题
添加了对共同提交者的支持
添加了关于已提交和已解决的 Bug 的指标
添加了关于 OpenStack 基金会成员的向下钻取报告
修复了杂项 Bug

Release 0.4

添加了评审统计报告，显示按标记和与核心决策不一致率分解的顶级评审者
添加了开放评审报告，显示最长的评审和整个积压总结
添加了活动报告，其中包含工程师的活动日志和通常在线时间（UTC）的打卡。相同的报告适用于公司
修复了评审统计计算，现在 Approve 标记单独计数
修复了提交日期计算，现在是合并日期，而不是提交日期
筛选器选择器中的小改进
合并了 21 个用户和公司资料更新到默认数据

Release 0.3

添加了邮件列表轮询和仪表板中此数据源的标准分析。
添加了关于蓝图的分析。实现了蓝图流行度报告。它显示蓝图在电子邮件或提交消息中被提及的次数。
添加了关于顶级导师的报告。它显示了对新贡献者补丁的评审统计信息。
添加了关于 API 的文档。
实现了项目分组。现在可以将多个项目分组到一个元模块中。
实现了对旧版本稳定分支的跟踪。
改进了 Bug ID 解析器。
实现了 GitHub 的故障转移处理。
修复了一些错误，并为许多人添加了关联信息。添加了 Havana 发布周期统计数据的修正。

发布 0.2

更改了内部架构。去除了 Mongo 中的持久化存储。配置文件 default_data.json 现在作为持久化存储。
添加了 Gerrit 轮询，用于检索与评审相关的源代码数据。
实现了评审的基本统计信息：随时间变化的评审数量、负面/正面评审数量、正面和负面评审的比例。
重新设计了统计页面导航和布局。
实现了基于日期自动将提交分配到发布周期。
实现了从 GitHub API 自动检索项目列表。
清理了 default_data.json（从 14k LOC 减少到 4k）
将所有超过 3k LOC 且看起来像是自动生成的提交添加到 corrections.json 中。
实现了功能请求将 Bug ID 作为数字排序，而不是作为字符串排序
修复了从 memcached 中批量删除的错误

发布 0.1

更改了内部架构。主要特性：高级实时处理和水平可扩展性。
去除了所有第三方非 Apache 许可的库，并将源代码发布在 StackForge 上，采用 Apache2 许可。
通过 Git 标签而不是近似的日期段改进了发布周期跟踪。
将项目分类更改为两级结构。OpenStack（核心、孵化器、文档、其他）和 StackForge。
实现了一种修正机制，允许用户调整特定提交的指标。
添加了一堆新项目（Tempest、文档、Puppet 脚本）。
在用户个人资料页面上添加了公司关联贡献细分。

操作指南

Stackalytics/HowToRun - 如何安装 Stackalytics 并在开发或生产环境中运行它

代码