JIRA Agile Metrics

从JIRA项目提取敏捷指标和图表的工具。

安装

需要Python 3.6或更高版本。

安装Python 3和包管理器pip。然后运行

$ pip install jira-agile-metrics

您可以在全局范围内执行此操作，但您可能希望使用虚拟Python环境（venv）来保持内容的自包含。

有关如何安装Python和venv的完整详细信息，请参阅《Python搭便车指南》。

这应该在相关的bin目录中安装一个名为jira-agile-metrics的二进制文件。您可以使用以下命令进行测试

$ jira-agile-metrics --help

... 应该会打印出帮助信息。

使用Docker

如果您愿意，可以使用Docker安装并运行jira-agile-metrics，其中包含所有相关的依赖项。安装Docker后，运行

$ docker run -it --rm -v $PWD:/data optilude/jira-agile-metrics:latest config.yml

这将使用当前目录中的配置文件config.yml运行jira-agile-metrics，并将输出写入当前目录。参数-v $PWD:/data将输出文件将被写入的/data卷挂载到当前工作目录。当然，您可以指定不同的挂载点。

批量模式下使用Docker

还有一个第二个Docker镜像，可以用于批量模式下运行多个配置文件，例如在夜间生成指标。

要使用它，创建一个包含一个或多个配置文件（扩展名为.yml或.yaml）的目录，以及一个用于输出的不同目录。假设这些是/path/to/config和/path/to/output，您可以通过定期运行以下Docker命令来使用它，例如使用cron或另一个调度程序

$ docker run --rm -v /path/to/config:/config -v /path/to/output:/data optilude/jira-agile-metrics:batch-latest

当此操作完成后，您应该在 output 目录下为 config 目录中的每个配置文件看到一个目录，其中包含报告和图表。您还将找到一个名为 metrics.log 的文件，其中包含运行期间的日志输出，这可能有助于诊断任何问题。

传递给 docker run 命令行参数（在镜像名称之后）将直接传递给 jira-agile-metrics。例如，如果您想使用 -n 选项限制从 JIRA 获取的结果数量（用于测试目的），可以在上述命令行末尾传递 -n 10（或某个不同的数字）。

用法

基本用法是在 YAML 格式的配置文件中运行 jira-agile-metrics（见下文），该文件描述了

• 如何连接到远程 JIRA 实例（这也可以通过命令行选项设置）；
• 要输出的指标（类似电子表格的数据文件，图像形式的图表）；
• 用于计算这些指标的各种设置；以及
• 与相关 JIRA 票据相关的流程阶段描述。

然后，该工具将使用其网络服务 API 连接到 JIRA，对相关票据及其历史记录运行查询，并计算所需的指标。

输出将写入本地文件系统文件。数据文件可以以 CSV、XLSX 或 JSON 格式写入（取决于所需输出文件的扩展名），而图表将以 PNG 图像的形式写入。

服务器模式

jira-agile-metrics 随附一个简单的网络服务器，可以用于通过上传配置文件并下载包含数据和图表的 ZIP 文件来生成指标。要启动它，请运行

$ jira-agile-metrics --server 5000

这将在一个端口 5000 上启动一个服务器（您也可以指定绑定主机名或 IP 地址，例如 0.0.0.0:5000）。在网页浏览器中访问此地址并上传文件。

在此模式下，忽略所有其他命令行选项。

注意： 网络服务器仅设计用于低流量使用，并且没有复杂的安全模型。它仅仅是命令行工具功能的更易于访问的前端。服务器将在 JIRA 查询和图表生成时同步等待，这可能需要很长时间。在此期间，浏览器将等待，线程将阻塞。

警告： 网络服务器不加密请求，这意味着默认情况下 JIRA 凭据将以纯文本形式传输。强烈建议在它前面配置一个带有 SSL 启用的反向代理（例如 nginx）。

使用 Docker 运行网络服务器

有一个用于运行网络服务器的单独 Docker 镜像，该镜像使用 nginx 和 uwsgi 以提高性能和稳定性（但仍然没有 SSL，这需要使用特定域的证书进行配置）

$ docker run -d --rm -p 8080:80 --name jira_metrics optilude/jira-agile-metrics:server-latest

这将以守护进程模式运行服务器并将其绑定到本地主机的端口 8080。要停止它，请运行

$ docker stop jira_metrics

有关更多详细信息，请参阅 Docker 文档。

关于密码的重要注意事项

该工具使用简单的用户名/密码组合来连接到 JIRA。您需要确保此用户存在于远程 JIRA 实例中，并且具有所需的权限。

有三种方式提供 JIRA 的凭据，特别是密码，应保密。您应仔细考虑哪种方法最适合您。

• 最安全的选项是既不在配置文件中设置，也不作为命令行选项设置。在这种情况下，每次运行工具时都会提示您输入密码（如果尚未设置用户名，则也会提示输入用户名）。
• 您可以在调用 jira-agile-metrics 命令时使用 --username 和/或 --password 命令行选项来设置凭据。这样做可以将它们从配置文件中排除，但如果您在记录命令历史的交互式外壳（即几乎所有外壳）中这样做，那么您的密码可能会以明文形式存储在命令历史中！
• 如果您确信可以保密配置文件，您可以将它们存储在其中的 Connection 部分（见下文）。

应该包括哪些问题？

最常见的用例是为一个团队计算使用名为 Story 的 JIRA 问题类型，通过包含如 Backlog（待办）、Committed（已提交）、Elaboration（细化）、Build（构建）、Code review（代码审查）、Test（测试）和 Done（完成）等阶段的流程，并允许一系列的解决方式，如 Completed（完成）、Withdrawn（撤回）和 Duplicate（重复）。

jira-agile-metrics 允许您使用 JIRA JQL 语法来指定您感兴趣的问题。请参阅 JIRA 文档以获取更多信息（或使用 JIRA UI 构建搜索，然后让 JIRA 显示相应的 JQL）。

创建配置文件

以下是一个基本示例的配置文件，该示例使用上述工作流程

# How to connect to JIRA. Can also include `Username` and `Password`
Connection:
    Domain: https://myjira.atlassian.net # your JIRA instance

# What issues to search for. Uses JQL syntax.
Query: Project=ABC AND IssueType=Story AND (Resolution IS NULL OR Resolution IN (Completed, Withdrawn))

# The workflow we want to analyse. By convention, the first stage should be
# the backlog / initial state, and the final stage should indicate the work
# is done.
#
# We map analytics names to JIRA status names. It's possible to collapse
# multiple JIRA statuses into a single workflow stage, as with `QA` below.
Workflow: 
    Backlog: Backlog
    Committed: Committed
    Elaboration: Elaboration
    Build: Build
    QA:
        - Code review
        - Test
    Done: Done

# What outputs to produce. These are all optional. If an option isn't set
# the relevant metric will not be produced.

Output:

    # CSV files with raw data for input to other tools or further analysis in a spreadsheet
    # If you use .json or .xlsx as the extension, you can get JSON data files or Excel
    # spreadsheets instead

    Cycle time data:
        - cycletime.csv
        - cycletime.json
    CFD data: cfd.csv
    Scatterplot data: scatterplot.csv
    Histogram data: histogram.csv
    Throughput data: throughput.csv
    Percentiles data: percentiles.csv

    # Various charts

    Scatterplot chart: scatterplot.png
    Scatterplot chart title: Cycle time scatter plot

    Histogram chart: histogram.png
    Histogram chart title: Cycle time histogram

    CFD chart: cfd.png
    CFD chart title: Cumulative Flow Diagram

    Throughput chart: throughput.png
    Throughput chart title: Throughput trend

    Burnup chart: burnup.png
    Burnup chart title: Burn-up

    Burnup forecast chart: burnup-forecast.png
    Burnup forecast chart title: Burn-up forecast
    Burnup forecast chart trials: 100 # number of Monte Carlo trials to run to estimate completion date

    # Burnup forecast chart throughput window: 60 # Days in the past to use for calculating historical throughput
    # Burnup forecast chart throughput window end: 2018-06-01 # Calculate throughput window to this date (defaults to today)
    # Burnup forecast chart target: 100 # items to complete in total; by default uses the current size of the backlog
    # Burnup forecast chart deadline: 2018-06-01 # deadline date, in ISO format; if not set, no deadline is drawn.
    # Burnup forecast chart deadline confidence: .85 # percentile to use to compare forecast to deadline

    WIP chart: wip.png
    WIP chart title: Work in Progress

    Ageing WIP chart: ageing-wip.png
    Ageing WIP chart title: Ageing WIP

    Net flow chart: net-flow.png
    Net flow chart title: Net flow

提示：如果您更喜欢将查询作为保存的过滤器在 JIRA 中管理，您可以使用特殊的 JQL 语法 filter=123，其中 123 是过滤器 ID。

如果将此文件保存为例如 config.yaml，则可以运行

$ jira-agile-metrics config.yaml

这将提示您输入用户名和密码，然后连接到您的 JIRA 实例，获取与查询匹配的问题，计算指标，并将多个 CSV 和 PNG 文件写入当前工作目录（您可以使用 --output-directory 选项将它们写入另一个目录）。

在测试配置时，通常很有帮助的是仅获取少量问题以加快速度。您可以这样做，要么通过使您的查询更加限制性，要么通过使用 -n 标志来限制获取的问题数量。

$ jira-agile-metrics -n 20 config.yaml

如果您想了解更多信息，请使用 -v 标志。

$ jira-agile-metrics -v config.yaml

如果您真的很想知道

$ jira-agile-metrics -vv config.yaml

重用配置文件中的元素

如果您想跨多个配置文件重用一些配置元素（例如，Connection、Workflow），则可以使用 Extends 选项将一个文件“导入”到另一个文件中。

例如，如果您有一个名为 common.yaml 的文件，其中包含

Connection:
    Domain: https://myjira.atlassian.net

Workflow: 
    Backlog: Backlog
    Committed: Committed
    Elaboration: Elaboration
    Build: Build
    QA:
        - Code review
        - Test
    Done: Done

Output:

    Quantiles:
        - 0.5
        - 0.75
        - 0.95

另一个文件，例如 team1.yaml，可以随后使用以下方式重用这些设置

Extends: common.yaml

Output:
    Cycle time data: team1-cycletime.csv
    CFD chart: team1-cfd.png
    CFD chart title: Team 1: CFD

扩展的文件名相对于正在加载的文件进行解析，所以在这个例子中它们会在同一目录下。您可以使用相对路径或绝对路径。请注意，相对路径的分隔符始终是 /（正斜杠），即使在 Windows 上也是如此！

当一个文件扩展另一个文件时，扩展文件可以覆盖扩展文件中设置的任何选项。例如，如果 team1.yaml 还在 Output 下设置了 Quantiles，则 common.yaml 中的列表将完全被覆盖。这是任何 Output 选项以及 Query / Queries 和 Workflow 选项的情况。任何 Attributes 都将合并。

您可以使用 Extends 递归，即扩展的文件可以扩展另一个文件。

注意： Extends 功能在服务器模式下不可用。如果上传包含 Extends 行的文件到服务器，则会引发错误。

可用的指标

jira-agile-metrics 可以生成多个数据文件和图表，这些可以在配置文件的 Output 部分或相应的命令行选项中启用。

注意：在配置文件中，您可以指定输出文件名称，但不能指定绝对或相对路径。文件总是会被写入当前工作目录。这是为了防止意外行为以及当配置文件在移动或在远程机器上使用时覆盖其他文件的可能性。对命令行参数中指定的输出文件没有此类限制。

周期时间详情

关于每个工单及其进入工作流程每个阶段的详细信息。CSV和JSON版本的此文件都可以由Actionable Agile Analytics工具使用，该工具提供强大的交互式敏捷流程分析。

在配置文件中

Output:
    Cycle time data: cycletime.csv

您还可以使用.json或.xlsx格式。要输出多个文件，请使用类似以下格式的列表

Output:
    Cycle time data:
        - cycletime.json
        - cycletime.xlsx
        - cycletime.csv

注意：“阻塞天数”的计算依赖于JIRA中的“标记”功能，显示每个工单标记为受阻的总天数（向上取整到最近的整数天）。工单在待办事项或完成状态期间提出的阻碍不计入。

累积流量图（CFD）

用于创建有效的累积流量图（CFD）的原始数据，以电子表格格式，以及/或相同内容的图像文件。CFD以堆叠面积图的形式显示每个阶段中工作项的数量，按日统计。这使我们能够可视化WIP、周期时间和吞吐量。

在配置文件中

Output:
    CFD data: cfd.csv
    CFD chart: cfd.png
    CFD chart title: Cumulative Flow Diagram

对于数据文件，您也可以使用.json或.xlsx格式。要输出多个文件，请使用类似以下格式的列表

Output:
    CFD data:
        - cfd.json
        - cfd.xlsx
        - cfd.csv

仅显示图表中的最近30天

    CFD window: 30

周期时间散点图

用于创建有效的周期时间散点图图形的原始数据，以及/或相同内容的图像文件。此图显示了每个工作项从开始到结束的周期时间（不包括在待办事项中花费的时间），并将其与完成日期相对应，并叠加分位数（例如，85%的工单在18天或更短的时间内完成）

在配置文件中

Output:
    Scatterplot data: scatterplot.csv
    Scatterplot chart: scatterplot.png
    Scatterplot chart title: Cycle time scatter plot

对于数据文件，您也可以使用.json或.xlsx格式。要输出多个文件，请使用类似以下格式的列表

Output:
    Scatterplot data:
        - scatterplot.json
        - scatterplot.xlsx
        - scatterplot.csv

默认情况下，使用的分位数是第50、第85和第95百分位数，但您可以通过在Output下的Quantiles选项中指定不同的列表来指定不同的列表

    Quantiles:
        - 0.3
        - 0.5
        - 0.75
        - 0.85
        - 0.95

请注意，此选项会影响所有使用分位数的图表。

要在数据文件中获取分位数值（每个分位数的天数），请使用

    Percentiles data: percentiles.csv

仅显示图表中的最近30天

    Scatterplot window: 30

周期时间直方图

这是周期时间的不同视图，以直方图形式计算和/或绘制。

在配置文件中

Output:
    Histogram data: histogram.csv
    Histogram chart: histogram.png
    Histogram chart title: Cycle time histogram

对于数据文件，您也可以使用.json或.xlsx格式。要输出多个文件，请使用类似以下格式的列表

Output:
    Histogram data:
        - histogram.json
        - histogram.xlsx
        - histogram.csv

这也遵循上述的Quantiles选项。

仅显示图表中的最近30天

    Histogram window: 30

吞吐量

每周吞吐量，即每周完成的项目数量。图表还显示趋势线。

在配置文件中

Output:
    Throughput data: throughput.csv
    Throughput chart: throughput.png
    Throughput chart title: Throughput trend

对于数据文件，您也可以使用.json或.xlsx格式。

要更改频率从每周到其他，请使用

    Throughput frequency: 1D

这里，1D表示每天。默认值为1W-MON，表示每周从星期一开始。

仅显示图表中的最近6个周期（例如，周）

    Throughput window: 6

WIP箱形图

显示每周（或某些其他频率）的WIP箱形图。

在配置文件中

    WIP chart: wip.png
    WIP chart title: Work in Progress

要更改频率从每周到其他，请使用

    WIP frequency: 1D

这里，1D表示每天。默认值为1W-MON，表示每周从星期一开始。

仅显示图表中的最近6个周期（例如，周）

    WIP window: 6

净流量图

显示每周到达和离开之间的差异。在一个完全稳定的系统中，净流量应该是0。

在配置文件中

    Net flow chart: net-flow.png
    Net flow chart title: Net flow

要更改频率从每周到其他，请使用

    Net flow frequency: 1D

这里，1D表示每天。默认值为1W-MON，表示每周从星期一开始。

仅显示图表中的最近6个周期（例如，周）

    Net flow window: 6

老化WIP图

显示每个工作项的周期时间，按工作流程的阶段分组。这可以帮助识别缓慢移动的工单。

在配置文件中

    Ageing WIP chart: ageing-wip.png
    Ageing WIP chart title: Ageing WIP

燃尽图

基于已完成的项和在待办事项中的项数的基本敏捷燃尽图。

在配置文件中

    Burnup chart: burnup.png
    Burnup chart title: Burn-up

仅显示图表中的最近30天

    Burnup window: 30

带有预测线的燃尽图

这是燃尽图的高级版本，它将基于历史吞吐量运行蒙特卡洛模拟，以预测范围完成的日期。

可以通过一系列选项对模拟进行校准来设置

• 要运行的试验次数。每次试验都将被绘制为假设的燃尽图直到完成。
• 从该时间段内抽样历史吞吐量。这应该代表近期，理想情况下为6-12周。
• 要达到的目标，即完成的故事数量。默认为待办事项的大小，但可以设置为假设的数字。
• 一个截止日期，如果设置了，可以在给定的置信区间内与预测进行比较。

在配置文件中

    Burnup forecast chart: burnup-forecast.png
    Burnup forecast chart title: Burn-up forecast
    Burnup forecast chart trials: 100 # number of Monte Carlo trials to run to estimate completion date

    Burnup forecast chart throughput window: 60 # Days in the past to use for calculating historical throughput
    Burnup forecast chart throughput window end: 2018-06-01 # Calculate throughput window to this date (defaults to last day of burnup)
    Burnup forecast chart target: 100 # items to complete in total; by default uses the current size of the backlog
    Burnup forecast chart deadline: 2018-06-01 # deadline date, in ISO format; if not set, no deadline is drawn.
    Burnup forecast chart deadline confidence: .85 # percentile to use to compare forecast to deadline

仅显示图表中的最近30天

    Burnup forecast window: 30

障碍

如果您使用JIRA中的“标记”功能来标记（并取消标记）受阻的工单，您可以生成显示提出障碍数量的图表，以及工单受阻累积花费的时间，按月份和标记设置或工单在设置标记时的工作流程阶段进行细分。您还可以将障碍事件写入文件。

可以通过以下方式启用图表

Impediments data: impediments.csv
Impediments window: 6
Impediments chart: impediments.png
Impediments chart title: Number of impediments
Impediments days chart: impediments-days.png
Impediments days chart title: Total impeded days
Impediments status chart: impediments-status.png
Impediments status chart title: Number of impediments by status
Impediments status days chart: impediments-status-days.png
Impediments status days chart title: Total impeded days by status

请注意，默认情况下，JIRA中的“标记”字段仅有一个值（"障碍"）可用，并且当在JIRA Agile板上使用“设置标记”选项时，确实只能设置一个字段。但是，您可以在相关字段的字段配置中启用额外的值，并在问题编辑屏幕上使该字段可用。

可选的“障碍窗口”可以用来限制图表仅显示最近几个月的数据：在这种情况下为六个月。

“障碍图表”和“障碍状态图表”将计算每个月活跃的障碍事件数量，即工单在某个月份被标记为受阻。

“障碍天数图表”和“障碍状态天数图表”使用相同的底层逻辑，但不是计算障碍，而是计算每个月所有障碍的天数总和。

请注意

• 不会显示针对待办事项或“完成”列中的工单提出的障碍。
• 如果工单被标记并解决，然后再取消标记，受阻时间将计算到解决日期。
• 如果工单在生成图表时仍然被标记，受阻天数计数将运行到今天。
• 阻塞时间始终向上取整到最近的整数天。

缺陷密度

三个图表用于分析历史上已打开的缺陷数量，以各种方式分组到堆叠条形图中。

这些图表都依赖于一个单独的JIRA查询

Defects query: issueType = Bug

同样，您可以使用filter=123 JQL语法将查询的详细信息委托给命名的过滤。

三种可用的分组是

• 按优先级分组显示每个月保留的缺陷数量。
• 按类型分组显示每个月保留的缺陷数量。
• 按环境分组显示每个月保留的缺陷数量。

它们各自需要您指定相关字段名称和图表输出。您还可以可选地指定每个字段的允许值列表，这可以让您控制顺序。最后，您可以指定一个“窗口”，显示最近几个月的多少个月（默认为显示所有有数据记录的月份）。以下是一个示例，启用了所有图表，并限制显示每个六个最近的月份

Defects query: issueType = Bug
Defects window: 6
Defects priority field: Priority
Defects priority values:
    - Low
    - Medium
    - High
Defects type field: Root cause
Defects type values:
    - Config
    - Data
    - Code
Defects environment field: Environment
Defects environment values:
    - SIT
    - UAT
    - PROD

Defects by priority chart: defects-by-priority.png
Defects by priority chart title: Defects by priority
Defects by type chart: defects-by-type.png
Defects by type chart title: Defects by type
Defects by environment chart: defects-by-environment.png
Defects by environment chart title: Defects by environment

如果您省略任何图表名称，则不会生成相关图表。如果您省略任何字段名称，则不会堆叠相关图表。如果您省略值列表，则将显示所有唯一值。

技术债务

两个图表显示了记录的（未解决的）技术债务的性质和年龄。

这些需要单独的JIRA查询。您还应该确定表示优先级的字段

Debt query: issueType = "Tech debt"
Debt priority field: Priority
Debt priority values:
    - Low
    - Medium
    - High

一如既往，使用filter=123来使用命名过滤器。如果您省略了“债务优先级值”选项，则将使用所有唯一的优先级值，按字母顺序排列。

第一张图表显示了每个月的技术债务项的开放状态，按优先级分组，以堆叠柱状图的形式展示。您可以指定一个“窗口”以仅显示最近几个月的有限数量。

Debt window: 3
Debt chart: tech-debt.png
Debt chart title: Technical debt

第二张图表显示了按其当前年龄（以天为单位）划分的开放技术债务项的数量，按优先级细分，并堆叠到“箱”中。

Debt age chart: tech-debt-age.png
Debt age chart title: Technical debt age
Debt age chart bins:
    - 30
    - 60
    - 90

这将使用0-30天、31-60天、61-90天和超过90天的年龄段（这也是默认值）。

浪费（撤回的项目）

此图表显示了在开始工作后撤回或取消的工作项的数量。它依赖于单独的JIRA查询，并假设撤回的工作项在JIRA中都是“已解决”的。此外，它假设这些工作项遵循与其他图表和文件相同的流程，即映射到配置文件的工作流程部分。

以下是一个示例

Waste query: issueType = Story AND resolution IN (Withdrawn, Invalid)
Waste window: 10
Waste frequency: 2W-WED
Waste chart: waste.png
Waste chart title: Waste

这将按撤回的时间段划分撤回的项目，对于最近10个时间段。默认时间段长度为每月，但这里我们将其设置为2W-WED，这意味着从周三开始的两周期。浪费窗口和浪费频率都是可选的。

进度报告

这是一个使用蒙特卡洛模拟在史诗级别进行预测的状态报告。

报告以自包含的HTML文件形式呈现，其中包含嵌入的图像。它依赖于少量常用的外部托管库（例如Bootstrap CSS/JS库及其jQuery依赖项；Fontawesome图标字体），但可以从任何静态Web服务器提供，或者在任何现代Web浏览器上作为本地文件打开。它也应该打印得很好，尽管嵌入的图像显示上下文特定的累积流量图和周期时间散点图，但只能通过在浏览器中点击相关的图标来访问。

状态报告基于结果（例如项目、发布、目标）的原则，这些结果被分解为史诗，最终将被进一步分解为故事。假设史诗完全由一个团队拥有。史诗和故事由JIRA票据表示，可以通过配置文件中指定的JQL查询发现，而结果和团队则直接在配置文件中列出。

然后通过以下方式为每个史诗生成一个完成的预测

• 史诗中假设的故事数量（在JIRA中史诗票据设置的最小和最大故事数量之间随机采样，或者使用针对史诗提出的故事总数，如果更高）；
• 迄今为止针对史诗提出并已完成的故事数量；
• 以及相关团队的预期吞吐量（随机采样，要么是从每周可以完成的最小和最大故事数量范围内，要么是通过一个JQL查询来识别团队的业绩历史）。

这将在蒙特卡洛模拟中多次进行，以确定一系列可能的完成日期。如果史诗上设置了截止日期，则完成的预测将与它进行比较，以突出达到截止日期的可能性。（也可能在结果级别设置截止日期，在这种情况下，结果截止日期是所有史诗的默认值。）

模拟考虑一个团队可能需要完成多个史诗级任务。团队可以配置为具有史诗级任务的WIP限制为1（默认）或更多。如果团队同时处理多个史诗级任务，则假定其将工作均匀分配到所有活跃的史诗级任务中，并按照配置文件中列出各自结果的顺序以及查询返回的顺序处理史诗级任务。

以下是一个完整的配置文件示例，生成的报告类似于上面的截图

Connection:
    # not shown

# ...

# Used for calculating progress against an epic, and team throughput: to
# identify whether stories are in the backlog, in progress, or completed.
Workflow:
    Backlog: Backlog
    Committed: Next
    Build: Build
    Test:
        - Code review
        - QA
    Done: Done

Output:
    # Used to determine which percentiles to show in the forecast
    Quantiles:
        - 0.75
        - 0.85
        - 0.95

    # The name of the file to write. If not set, the progress report will
    # not be produced
    Progress report: progress.html

    # Report title
    Progress report title: Acme Corp Websites

    # Names of JIRA fields on epics, used to determine the deadline, team,
    # and min/max stories. All are optional:

    # - if no deadline field is set, the report will not include any
    #   deadline calculations
    Progress report epic deadline field: Due date

    # - if no team field is set, you must specify exactly one team under
    #   `Progress report teams`, which will be used for all epics
    Progress report epic team field: Team

    # - if no min stories field is set, the story count will be based solely
    #   on the number of stories raised against each epic, rather than an
    #   estimated range; if no max stories field is set, the min stories
    #   field will be used to identify an absolute value
    Progress report epic min stories field: Min stories
    Progress report epic max stories field: Max stories

    # The query used to identify epics for each outcome. The special
    # placeholder `{outcome}` will be replaced by the outcome key (or name,
    # if the key is not set). May be overridden by the `Epic query` set on
    # an individual outcome. If not set, the `Epic query` must be specified
    # on each outcome, and it is not possible to use outcomes as tickets.
    Progress report epic query template: project = ABC AND type = Epic AND Outcome = {outcome} ORDER BY created

    # The query used to identify stories for an epic. The placeholders
    # `{epic}`, `{outcome}`, and `{team}` may be used to parameterise the
    # query.
    Progress report story query template: project = ABC AND type = Story AND "Epic link" = {epic}

    # A list of teams. At least one team is required, and each team must
    # have a `Name` and *either* `Min throughput` and `Max throughput`
    # (stories per week), *or* a query in `Throughput samples`. `WIP`
    # (number of epics the team may work on in parallel) and
    # `Throughput samples window` (number of weeks in the past from which to
    # draw samples) are optional. The placeholder `{team}` can be used to
    # reference the team name in the samples query.
    Progress report teams:
        - Name: Red
          Min throughput: 5
          Max throughput: 10
        - Name: Blue
          WIP: 2
          Throughput samples: project = ABC AND type = Story AND Team = {team}
          Throughput samples window: 6

    # A list of outcomes. May be omitted, in which case epics will not be
    # grouped into outcomes and the `Progress report epic query template`
    # specifies a non-parameterised query for all relevant epics. If
    # included, each outcome must have a `Name`. `Key`, which is used in
    # the epic query template, is optional, defaulting to the same value as
    # `Name`. `Deadline` can be used to specify a deadline for all epics
    # in the report, which can be overridden on a per-epic basis.
    # `Epic query` may be used to specify a particular query for
    # epics, overriding the more general `Progress report epic query template`.
    Progress report outcomes:
        - Name: MVP
          Key: O1
          Deadline: 2019-01-01
        - Name: Asia launch
          Key: O2
        - Name: Europe revamp
          Key: O3
          Epic query: project = ABC and type = Feature

在此示例中，我们已在配置文件中明确列出结果。结果也可以作为JIRA工单（甚至可以混合两种方法）进行管理。为此，您需要指定用于查找结果的查询

    Progress report outcome query: project = ABC AND type = Outcome AND resolution IS EMPTY ORDER BY summary

    # Optionally give a field name for the outcome-level deadline, which
    # will be used as a fallback if epic-level deadlines are not set
    Progress report outcome deadline field: Due date

如果使用工单指定结果，则必须设置进度报告史诗级查询模板。占位符{outcome}将被相关结果的工单key替换。您可以使用链接问题字段来指定结果。

在更简单的用例中，您可以模拟一个团队执行所有工作，并且/或者可以完全丢弃“结果”级别，仅模拟史诗级任务。估计的最小/最大故事数以及整个截止日期的概念也是可选的。

以下是一个最小示例

# ...

Workflow:
    Backlog: Backlog
    Committed: Next
    Build: Build
    Test:
        - Code review
        - QA
    Done: Done

Output:

    Quantiles:
        - 0.75
        - 0.85
        - 0.95

    Progress report: progress-minimal.html
    Progress report title: Acme Corp Websites
    Progress report epic min stories field: Story count
    Progress report epic query template: project = ABC AND type = Epic AND resolution IS EMPTY ORDER BY created
    Progress report story query template: project = ABC AND type = Story AND "Epic link" = {epic}
    Progress report teams:
        - Name: Default
          Min throughput: 5
          Max throughput: 10

如果您对团队步伐的预测性或基础数据质量没有信心，您也可以关闭某些团队或所有团队的预测。您仍然会得到进度条和图表。在这种情况下，您可以选择省略特定团队的最小吞吐量 / 最大吞吐量字段，或者省略其全部的进度报告团队部分。团队名称将从史诗级任务的相关字段中获取（假设已指定史诗级团队字段名称）

# ...

Workflow:
    Backlog: Backlog
    Committed: Next
    Build: Build
    Test:
        - Code review
        - QA
    Done: Done

Output:

    Quantiles:
        - 0.75
        - 0.85
        - 0.95

    Progress report: progress-teams.html
    Progress report title: Acme Corp Websites
    Progress report epic min stories field: Story count
    Progress report epic query template: project = ABC AND type = Epic AND resolution IS EMPTY ORDER BY created
    Progress report story query template: project = ABC AND type = Story AND "Epic link" = {epic}
    Progress report epic team field: Team

技术上您可以省略团队列表（因此没有预测）和团队字段名称，在这种情况下，您将仅获得没有预测或分组的史诗级任务分解。

请注意，如果您指定了团队列表和史诗级团队字段，团队列表将自动扩展到配置中未明确列出的任何团队名称。

有关配置文件格式的更多详细信息

配置文件是用YAML格式编写的。如果您不熟悉YAML，请了解

• 注释以#开头
• 部分由名称后跟冒号定义，然后是下方的缩进块。在上面的示例中，Connection、Output、Workflow和Attributes都是部分。
• 缩进必须使用空格，而不是制表符！
• 可以使用Key: value对设置单个值。例如，上面的Burnup chart: burnup.png将键Burnup chart设置为值burnup.png。
• 可以使用缩进一个新块并在每个列表值前放置一个-来设置值列表。在上面的示例中，QA列表包含值Code review和Test。

Workflow部分是必需的。另外，您必须指定单个Query，或者一个Queries块（见下文）。连接详细信息必须在Connection文件中设置或作为命令行参数。

在Workflow下，至少需要两个步骤。按照顺序指定步骤。您可以选择单个工作流程值或列表（如上例所示），在这种情况下，多个JIRA状态将合并为一个状态以进行数据分析。

文件以及如工作流程状态和属性之类的值对大小写不敏感。

提取附加属性

您可能希望向周期时间输出数据添加更多字段。使用Attributes块来完成此操作

Attributes:
    Priority: Priority
    Release: Fix version/s
    Team: Team name

在此处，将添加三个附加列：Priority、Release和Team，分别对应于JIRA字段的Priority、Fix version/s和Team name。

在指定属性时，请使用字段（在JIRA屏幕上显示）的名称，而不是其id（如你可能在JQL中所做的那样），例如，使用Component/s而不是components。

属性Type（问题类型）、Status和Resolution始终包含在内。

多值字段

JIRA中的一些字段可以包含多个值，例如fixVersion。默认情况下，提取器将使用该字段中指定的第一个值。但是，你可能只想提取特定值。

为此，添加一个如下所示的块：

Attributes:
    Release: Fix version/s

Known values:
    Release:
        - "R01"
        - "R02"
        - "R03"

提取器将选择该字段找到的第一个“已知值”。如果没有已知值匹配，则单元格将为空。

组合多个查询

如果难以构建一个单一的标准集返回所有必要的问题，可以添加多个查询到Queries块中，如下所示

Queries:
    Attribute: Team
    Criteria:
        - Value: Team 1
          JQL: (filter=123)

        - Value: Team 2
          JQL: (filter=124)

在这个例子中，将运行两个查询，基于两个过滤器123和124（你可以使用任何有效的JQL）。

在周期时间输出中，将添加一个名为Team的新列，这是在Queries下的Attribute字段中指定的。对于第一个查询返回的所有项，其值将是Team 1，按照Value字段，而对于第二个查询返回的所有项，它将是Team 2。

故障排除

• 如果Excel关于SYLK格式错误抱怨，请忽略它。点击确定。查看https://support.microsoft.com/en-us/kb/215591。

• JIRA的错误消息可能会以HTML格式打印在控制台上。错误在其中某个地方，但可能难以看到。最可能的是，这是一个认证失败（用户名/密码错误或账户被阻止），或者Query选项中的错误导致无效的JQL。

• 如果你没有得到期望看到的问题，请使用-v选项来查看发送到JIRA的JQL。将其粘贴到JIRA问题过滤器搜索框（“高级模式”）以查看JIRA如何评估它。

• 旧的流程状态在修改流程后仍可以是问题历史的一部分。使用-v选项来了解尚未映射的流程状态。

• Excel有时会给CSV文件中的数据选择奇怪格式。只需将其设置为任何有意义的格式即可。

• 如果你在Mac上，并且收到有关Python没有作为框架安装的错误，请尝试创建一个包含以下内容的文件~/.matplotlib/matplotlibrc

  backend : Agg

• 在Mac上安装图表依赖项时，你可能需要为scipy安装一个gfortran编译器。使用Homebrew并安装gcc brew。

输出设置参考

可以在配置文件的Output:部分设置以下选项。

通用选项

这些选项影响多个图表和文件。

• Quantiles: <list> – 在计算百分位数时使用的分位数。
• Backlog column: <name> -- 后备列的名称。默认为第一列。
• Committed column: <name> – 从中考虑工作已提交的列的名称。默认为第二列。
• Final column: <name> – 最终“工作”列的名称。默认为倒数第二列。
• Done column: <name> – “完成”列的名称。默认为最后一列。

数据文件

这些选项命名要写入的数据文件。使用所需的文件格式扩展名.csv、.xlsx或.json。可以是文件名列表，也可以是单个文件名。

• 周期时间数据: <filename>.[csv,xlsx,json] – 适用于处理可操作敏捷的输出文件。包含配置文件中描述的所有问题、元数据和周期中每个状态的进入日期。
• CFD数据: <filename>.[csv,xlsx,json] – 计算绘制累积流量图的数据并写入文件。提示：以（非堆叠）面积图的形式绘制。
• 散点图数据: <filename>.[csv,xlsx,json] – 计算绘制周期时间散点图的数据并写入文件。提示：以散点图的形式绘制。
• 直方图数据: <filename>.[csv,xlsx,json] – 计算绘制周期时间直方图的数据并写入文件。提示：以柱状图的形式绘制。
• 吞吐量数据: <filename>.[csv,xlsx,json] – 计算每日吞吐量数据并写入文件。提示：以柱状图的形式绘制。尊重以下设置的吞吐量频率。
• 百分位数数据: <filename>.[csv,xlsx,json] – 计算周期时间百分位数并写入文件。
• 阻碍数据: <filename>.[csv,xlsx,json] – 输出与票证相关的阻碍开始和结束日期。

散点图图表

• 散点图窗口: <number> – 散点图中显示的最近天数。默认显示所有数据。
• 散点图图表: <filename>.png – 绘制周期时间散点图。
• 散点图图表标题: <title> – 周期时间散点图的标题。

直方图图表

• 直方图窗口: <number> – 直方图中显示的最近天数。默认显示所有数据。
• 直方图图表: <filename>.png – 绘制周期时间直方图。
• 直方图图表标题: <title> – 周期时间直方图的标题。

累积流量图

• CFD窗口: <number> – 在CFD中显示的最近周期数。默认显示所有周期。
• CFD图表: <filename>.png – 绘制累积流量图。
• CFD图表标题: <title> – CFD的标题。

吞吐量图表

• 吞吐量频率: <freq> – 用于计算频率的间隔，例如1D为每日或1W为每周。
• 吞吐量窗口: <number> – 在吞吐量图表中显示的最近周期数。默认显示所有周期。
• 吞吐量图表: <filename>.png – 绘制带有趋势线的每周吞吐量图表。
• 吞吐量图表标题: <title> – 吞吐量图表的标题。

燃尽图

• 燃尽窗口: <number> – 在燃尽图中显示的最近周期数。默认显示所有周期。
• 燃尽图: <filename>.png – 绘制简单的燃尽图。
• 燃尽图标题 <title> – 燃尽图_scatterplot的标题。

燃尽预测图

• 燃尽预测窗口: <number> – 在燃尽预测图表中显示的最近周期数。默认显示所有周期。
• 燃尽预测图表: <filename>.png – 绘制带有蒙特卡洛模拟预测完成的燃尽图。
• 燃尽预测图表标题: <title> – 燃尽预测图表的标题。
• 燃尽预测图表目标: <number> – 预测完成的目标范围。默认为当前待办事项的大小。
• 燃尽预测图表截止日期: <date> – 待办事项完成截止日期。如果设置，则会在图表上显示，并且也会显示预测偏差。使用ISO日期格式，例如2018-01-02表示2018年1月2日。
• 燃尽预测图表截止日期置信度: <number> – 比较截止日期和预测时使用的分位数。使用分数，例如0.85。
• 燃尽预测图表迭代次数: <number> – 蒙特卡洛模拟中的迭代次数。
• 燃尽预测图表吞吐量窗口: <number> – 用于计算吞吐量的过去天数。
• 燃耗预测图表吞吐量窗口结束时间：<日期> – 默认情况下，吞吐量窗口运行至今天日期。使用此选项设置窗口的替代结束日期。使用ISO日期格式，例如 2018-01-02 表示2018年1月2日。

在制品图表

• 在制品频率：<freq> – 在制品图表的频率间隔。1W-Mon 表示每周，从星期一开始。
• 在制品窗口：<数量> – 在制品图表中显示的最近周期的数量。默认显示所有周期。
• 在制品图表：<文件名>.png – 绘制每周在制品箱线图。
• 在制品图表标题：<标题> – 在制品图表的标题。

老化WIP图

• 老化在制品图表：<文件名>.png – 绘制当前的在制品老化图表。
• 老化在制品图表标题：<标题> – 老化在制品图表的标题。

净流量图

• 净流量频率：<freq> – 净流量图表的频率间隔。1W-Mon 表示每周，从星期一开始。
• 净流量窗口：<数量> – 在净流量图表中显示的最近周期的数量。默认显示所有周期。
• 净流量图表：<文件名>.png – 绘制每周净流量条形图。
• 净流量图表标题：<标题> – 净流量条形图的标题。

阻碍因素图表

• 阻碍因素窗口：<数量> – 显示多少个月。
• 阻碍因素图表：<文件名>.png – 绘制每月活动阻碍因素的条形图，按阻碍因素标记堆叠。
• 阻碍因素图表标题：<标题> – 阻碍因素图表的标题。
• 阻碍因素天数图表：<文件名>.png – 绘制每月所有活动阻碍因素的总天数条形图，按阻碍因素标记堆叠。
• 阻碍因素天数图表标题：<标题> – 阻碍因素天数图表的标题。
• 阻碍因素状态图表：<文件名>.png – 绘制每月活动阻碍因素的条形图，按阻碍因素提出时的票据状态堆叠。
• 阻碍因素状态图表标题：<标题> – 阻碍因素状态图表的标题。
• 阻碍因素状态天数图表：<文件名>.png – 绘制每月所有活动阻碍因素的总天数条形图，按每个阻碍因素提出时的票据状态堆叠。
• 阻碍因素状态天数图表标题：<标题> – 阻碍因素状态天数图表的标题。

缺陷密度图表

• 缺陷查询：<查询> – 用于识别缺陷的JQL查询。

• 缺陷窗口：<数量> – 显示多少个月。

• 缺陷优先级字段：<字段名> – 识别缺陷优先级的字段名称。

• 缺陷优先级值：<列表> – 缺陷优先级的有效值列表，按顺序排列。

• 缺陷类型字段：<字段名> – 识别缺陷类型的字段名称。

• 缺陷类型值：<列表> – 缺陷类型的有效值列表，按顺序排列。

• 缺陷环境字段：<字段名> – 识别缺陷发现环境的字段名称。

• 缺陷环境值：<列表> – 缺陷环境的有效值列表，按顺序排列。

• 按优先级缺陷图表：<文件名>.png – 绘制按优先级分组并随时间变化的缺陷堆叠条形图。

• 按优先级缺陷图表标题：<标题> – 按优先级缺陷图表的标题。

• 按类型缺陷图表：<文件名>.png – 绘制按类型分组并随时间变化的缺陷堆叠条形图。

• 按类型缺陷图表标题：<标题> – 按类型缺陷图表的标题。

• 按环境缺陷图表：<文件名>.png – 绘制按环境分组并随时间变化的缺陷堆叠条形图。

• 环境缺陷图表标题：<title> – 环境缺陷图表的标题。

债务密度图表

• 债务查询：<query> – 用于识别技术债务项的JQL查询。

• 债务窗口：<number> – 在债务图表中显示多少个月。默认显示所有有数据的月份。

• 债务优先级字段：<fieldname> – 识别技术债务项优先级的字段名称。

• 债务优先级值：<list> – 技术债务项优先级的有效值列表，按顺序排列。

• 债务图表：<filename>.png – 绘制按优先级分组的技术债务随时间堆叠柱状图。

• 债务图表标题：<title> – 技术债务图表的标题。

• 债务年龄图表：<filename>.png – 绘制按优先级分组的技术债务按年龄堆叠柱状图。

• 债务年龄图表标题：<title> – 技术债务年龄图表的标题。

• 债务年龄图表箱：<list> – 显示年龄的箱列表。默认为 30、60 和 90，将年龄分组为 0-30天、31-60天、61-90天 和 91天或以上。

浪费图表

• 浪费查询：<query> – 用于识别浪费项的JQL查询，例如工作开始后撤回的项目。
• 浪费频率：<freq> – 按频率分组浪费图表。默认为月份开始（MS）。例如，使用 2W-WED 可按每周三开始的半月分组。
• 浪费窗口：<number> – 显示多少个月。
• 浪费图表：<filename>.png – 绘制按最后非解决状态分组的浪费项堆叠柱状图。
• 浪费图表标题：<title> – 浪费图表的标题。

进度报告

• 进度报告：<filename>.html – 将进度报告写入独立的HTML文件。
• 进度报告标题：<title> – 进度报告页面的标题。
• 进度报告史诗截止日期字段：<fieldname> – 给出史诗截止日期的日期字段名称。
• 进度报告史诗团队字段：<fieldname> – 给出史诗责任团队名称的字段名称。
• 进度报告史诗最小故事字段：<fieldname> – 给出史诗预期的最小故事数量的整数字段名称，用于预测目的。
• 进度报告史诗最大故事字段：<fieldname> – 给出史诗预期的最大故事数量的整数字段名称，用于预测目的。
• 进度报告史诗查询模板：<query> – 用于识别结果的史诗的查询。占位符 {outcome} 将替换为给定的结果键（如果设置）或名称。
• 进度报告故事查询模板：<query> – 用于识别史诗中的故事的查询。占位符 {epic} 将替换为给定的史诗键（JIRA引用）。占位符 {outcome} 和 {team} 也可用于识别结果键/名称和团队名称。
• 进度报告团队：<list> – 包含键 Name、WIP、Min throughput、Max throughput、Throughput samples 和/或 Throughput samples window 的记录列表，这些键指定可能与史诗关联的团队。 Name 是必需的，您可以选择指定 Min/Max throughput（每周故事数）或 Throughput samples，这是一个用于计算历史吞吐量的JQL查询以识别给定团队的故事。如果给出了 Throughput samples window，它指定在计算历史吞吐量时使用从今天日期往回推算的周数。您可以在 Throughput samples 中使用占位符 {team} 作为重复团队名称的快捷方式。WIP 默认为 1。
• 进度报告结果：<列表> – 包含键 名称、键、截止日期 和/或 史诗查询 的记录列表，这些键指定要在进度报告中列出的结果。默认情况下，键 将与 名称 的值相同。截止日期 将用作未设置史诗级别截止日期时的后备。如果提供了 史诗查询，则当查找此结果的相关史诗时，它将优先于 进度报告史诗查询模板。
• 进度报告结果查询：<查询> – 允许在 JIRA 问题上列出结果，而不是使用 进度报告结果 列表。每个匹配的问题都将用作结果，史诗查询模板的结果键为问题键，问题摘要为结果标题。如果使用，则必须设置 进度报告史诗查询模板。
• 进度报告史诗截止日期字段：<字段名> – 提供结果截止日期的日期字段名称。如果未设置史诗级别截止日期，则用作后备。可选。

变更日志

0.24

• 允许在进度报告中使用字段 id 或标题作为字段名称。
• 修复了配置文件中没有定义团队或结果时运行时出现的几个错误。

0.23

• 允许在结果上设置截止日期，作为史诗级别截止日期的后备。
• 添加了对 进度报告结果查询 和 进度报告结果截止日期字段 的支持。
• 允许进度报告在没有预测的情况下运行（对于某些/所有团队）。
• 允许进度报告在没有显式定义团队的情况下运行。如果指定了史诗团队字段，则从史诗团队字段中获取团队名称，并且不会对这些团队进行预测。
• 将目标和截止日期行添加到进度报告中史诗级别的 CFD 中。
• 将结果级别的 CFD 添加到进度报告中。

0.22

• 添加了对配置文件中 Extends 的支持。
• 允许 -o 作为 --output-directory 的别名。

0.21

• 允许按团队或结果查看进度报告的输出。

0.20

• 在计算达到截止日期的可能性时，使用百分位数累积分布函数定义来计算（基本上：如果截止日期与预测最坏情况日期在同一周，则将其视为 100% 而不是 50% 可能）。

0.19

• 修复了使用 Pandas 更新版本计算 CFD 图表时崩溃的问题。

0.18

• 对于已完成的相关史诗，不显示预测。

0.17

• 再次在日志输出中显示日期/时间以及日志级别，以便更容易调试。

0.16

• 尝试修复在某些边缘情况下吞吐量计算器崩溃的问题。

0.15

• 棕色包裹

0.14

• 即使 JIRA 中的字符串字段，也将最小/最大故事字段强制为整数。
• 记录导致向后移动的状态更改。

0.13

• 确保即使 JIRA 返回的方式不同，更改历史也始终按日期顺序迭代。

0.12

• 在进度报告中保留打印 CSS 中的背景颜色。
• 允许在团队吞吐量样本查询中使用 {team} 占位符。

0.11

• 添加了进度报告计算器。
• 修复了模板无法加载的问题，因为软件包是以 egg 格式安装的（即不是从源安装）。

0.10

• 使能够可选地指定多个输出文件（通过 YAML 列表）为 * 数据： 文件名。这里的用例是输出 cycletime 计算的 CSV/XLSX 和 JSON 版本。
• 在计算器中停止吞咽异常（但在写入输出文件时继续这样做）。问题调试太混乱了。

0.9

• 使默认的阻碍图表使用阻碍标志值作为分解，并添加了按状态分解的特定 阻碍状态 * 图表。

0.8

• 添加了 --http-proxy 和 --https-proxy 命令行选项，以及 连接 部分的相应 HTTP 代理 和 HTTPS 代理。

0.7

• 将吞吐量图表转换为折线图。

0.6

• 在调试时不要记录每个列表值的解析。

0.5

• 添加了批处理模式 Docker 镜像。

0.4

• 添加了阻碍图表。

0.3

• 添加了债务、缺陷和浪费图表。
• 将大多数图表添加了 窗口 选项。

0.2

• 添加了 --output-directory 选项。

0.1

• 源自 jira-agile-metrics