jira-cycle-extract 0.10

安装

安装Python 2.7和pip。请参阅http://pip.readthedocs.org/en/stable/installing/。

使用pip安装

$ pip install jira-cycle-extract

如果您遇到错误，请首先尝试分别安装numpy和pandas

$ pip install numpy pandas
$ pip install jira-cycle-extract

这将安装一个名为jira-cycle-extract的二进制文件。您可以使用以下命令测试它是否正确安装：

$ jira-cycle-extract --help

如果这不起作用，请检查pip install jira-cycle-extract的输出，以查看可能安装二进制文件的位置。

要使用内置的图表功能，您需要安装Seaborn（它反过来安装Matplotlib和SciPy）和Statsmodels。您可以使用charting额外功能来获取这些。

$ pip install jira-cycle-extract[charting]

默认情况下不会安装这些依赖项，因为它们有时可能有点难以安装。

使用Docker

如果您已安装Docker，则可以运行jira-cycle-extract作为docker镜像

$ docker run --rm -it -v "$PWD":/data optilude/jira-cycle-extract:latest --help

这将映射容器化应用程序的工作目录（/data）到当前工作目录（$PWD）。您在命令行上指定的任何文件（无需任何进一步路径前缀）都将从当前目录读取或输出到当前目录，例如

$ docker run --rm -it -v "$PWD":/data optilude/jira-cycle-extract:latest config.yml cycle.csv

配置

编写一个类似以下的 YAML 配置文件，例如命名为 config.yaml

# How to connect to JIRA?
Connection:
    Domain: https://myserver.atlassian.net
    Username: myusername # If missing, you will be prompted at runtime
    Password: secret     # If missing, you will be prompted at runtime

# What to search for?
Criteria:
    Project: ABC # JIRA project key to search
    Issue types: # Which issue types to include
        - Story
        - Defect
    Valid resolutions: # Which resolution statuses to include (unresolved is always included)
        - Done
        - Closed
    JQL: labels != "Spike" # Additional filter as raw JQL, optional

# Describe the workflow. Each step can be mapped to either a single JIRA
# status, or a list of statuses that will be treated as equivalent
Workflow:
    Open: Open
    Analysis IP: Analysis in Progress
    Analysis Done: Analysis Done
    Development IP: Development in Progress
    Development Done: Development Done
    Test IP: Test in Progress
    Test Done: Test Done
    Done:
        - Closed
        - Done

# Map field names to additional attributes to extract
Attributes:
    Components: Component/s
    Priority: Priority
    Release: Fix version/s

如果您不熟悉 YAML，请记住以下内容：

• 注释以 # 开头

• 使用名称后跟冒号定义部分，然后在下面使用缩进的块。在上面的例子中，Connection、Criteria、Workflow 和 Attributes 都是部分。

• 缩进必须使用空格，而不是制表符！

• 可以使用 键: 值 对来设置单个值。例如，上面的 Project: ABC 将 Project 键设置为 ABC 值。

• 可以通过缩进一个新块并在每个列表值前放置一个 - 来设置值列表。在上面的例子中，Issue types 列表包含 Story 和 Defect 值。

Connection、Criteria 和 Workflow 部分是必需的。

在 Conection 下，只有 Domain 是必需的。如果未指定，当运行脚本时将提示用户输入用户名和密码。

在 Criteria 下，所有字段在技术上都是可选的，但您应该指定其中的一些，以避免无界查询。Issue types 和 Valid resolutions 可以设置为单个值或列表。

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

文件以及像工作流程状态和属性这样的值都不区分大小写。

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

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

在指定 Component/s 或 Fix version/s 等可能包含值列表的字段时，仅使用设置的第一个值。

多个查询

如果很难构建一个返回所有所需问题的单个条件集，可以将多个 Criteria 部分包装在 Queries 块中，如下所示：

Queries:
    Attribute: Team
    Criteria:
        - Value: Team 1
          Project: ABC
          Issue types:
              - Story
              - Bug
          Valid resolutions:
              - Done
              - Closed
          JQL: Component = "Team 1"

        - Value: Team 2
          Project: ABC
          Issue types:
              - Story
              - Bug
          Valid resolutions:
              - Done
              - Closed
          JQL: Component = "Team 2"

在此示例中，JIRA 中的 Component 字段用于表示交付工作的团队，但也可以用于其他目的。将运行两个 JIRA 查询，对应于两个 Criteria 块。

此外，将添加一个名为 Team 的新列，如 Queries 下 Attribute 字段中指定的。对于第一个查询返回的所有项，值将为 Team 1，如 Value 字段中所述，对于第二个查询返回的所有项，它将为 Team 2。

多值字段

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

要这样做，请添加以下类型的块：

Attributes:
    Release: Fix version/s

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

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

运行

要生成基本周期时间数据，请运行 jira-cycle-extract，传递 YAML 配置文件的名称和输出 CSV 文件的名称

$ jira-cycle-extract config.yaml data.csv

这将提取一个名为 data.csv 的 CSV 文件，其中包含基于 config.yaml 中的配置的周期数据，该格式与 ActionableAgile 工具集兼容。

如果您更喜欢 Excel 文件进行手动分析

$ jira-cycle-extract --format=xlsx config.yaml data.xlsx

如果您更喜欢 JSON

$ jira-cycle-extract --format=json config.yaml data.json

如果您自行托管 Actionable Agile Analytics 工具，并且 AAA 工具的单页 HTML 文件和 JSON 文件可以通过相同的 Web 服务器通过 URL 参数访问，则 Actionable Agile Analytics 工具可以加载 JSON 格式。

http://myserver/analytics.html?url=data.json

您可以选择路径或完整URL，但由于同源请求限制，浏览器很可能不会允许您加载来自与分析Web应用本身不同域的内容。

注意：当设置< cite>–format时，它适用于所有写入的文件，而不仅仅是主要周期数据文件（见以下其他选项）。保持文件扩展名的一致性很重要。特别是，如果您使用< cite>xlsx格式，还应该确保所有输出文件使用< cite>.xlsx扩展名。

还有很多其他选项。请参阅

$ jira-cycle-extract --help

使用< cite>-v选项在提取过程中打印更多信息。

使用< cite>-n选项根据最新更新的问题限制从JIRA获取的项目数量。这对于在没有等待长时间下载的情况下测试配置很有用。

$ jira-cycle-extract -v -n 10 config.yaml data.csv

要生成< strong>Cumulative Flow Diagram统计信息，请使用< cite>–cfd选项

$ jira-cycle-extract --cfd cfd.csv config.yaml data.csv

这将生成一个< cite>cfd.csv文件，其中每行对应一个日期，每列对应工作流程中的每个步骤，以及当天该工作流程状态的待解决问题数量。要绘制CFD，将这些数据绘制为（非堆叠）面积图。您实际上应该排除第一列中的系列，如果它表示积压！

要生成< strong>cycle time散点图统计信息，请使用< cite>–scatterplot选项

$ jira-cycle-extract --scatterplot scatterplot.csv config.yaml data.csv

这将生成一个< cite>scatterplot.csv文件，其中每行对应一个已完成的项（即它达到了最后的工作流程状态），列给出了完成日期以及从项进入第一个活动状态（即工作流程的第二步，基于第一个项代表积压或接收队列）到项进入完成状态的经过天数。这两个列可以绘制为X/Y散点图。其他列包含进入每个工作流程状态的日期以及各种问题元数据，以便进行进一步筛选。

要轻松绘制循环时间值的< strong>直方图，请使用< cite>–histogram选项

$ jira-cycle-extract --histogram histogram.csv config.yaml data.csv

这将生成一个< cite>histogram.csv文件，包含两列：范围和每个范围内的循环时间项的数量。这些可以绘制为柱状图或条形图。

要找出30th，50th，70th，85th和95th < strong>percentile循环时间值，传递< cite>–percentiles选项

$ jira-cycle-extract --percentiles percentiles.csv config.yaml data.csv

使用< cite>–quantiles选项计算不同的百分位数

$ jira-cycle-extract --percentiles percentiles.csv --quantiles=0.3,0.5,0.8 config.yaml data.csv

请注意，逗号之间不应有空格！

要找出过去60天的< strong>每日吞吐量，请使用< cite>–throughput选项

$ jira-cycle-extract --throughput throughput.csv config.yaml data.csv

要使用不同的时间窗口，例如过去90天

$ jira-cycle-extract --throughput throughput.csv --throughput-window=90 config.yaml data.csv

可以组合使用各种选项，并且技术上可以跳过第二个位置（< cite>data.csv）参数（在这种情况下，将不会写入文件）。

如果您已安装图表依赖项（见上文），则有一些选项可供您绘制< strong>图表，例如

$ jira-cycle-extract --charts-scatterplot=scatterplot.png config.yaml data.csv

可用的图表有

• < cite>–charts-scatterplot以绘制带有百分位线的循环时间的< strong>散点图

• < cite>–charts-histogram以绘制带有百分位线的循环时间的< strong>直方图

• < cite>–charts-cfd以绘制< strong>Cumulative Flow Diagram

• < cite>–charts-throughput以绘制每日< strong>吞吐量条形图

• < cite>–charts-burnup以绘制简单的< strong>burn-up图（完成项数与时间的关系）

• –charts-burnup-forecast 用于绘制一个显示向完成目标路径的 蒙特卡洛模拟燃尽图。默认情况下，完成目标将是待办事项中的项目数量，但可以使用 –charts-burnup-forecast-target 选项显式设置。默认情况下，模拟使用 100 次试验。可以使用 –charts-burnup-forecast-trials 选项设置试验次数。您可以使用 –charts-burnup-forecast-deadline 选项设置一个截止日期作为标记，应将其设置为日期。如果您还设置 –charts-burnup-forecast-deadline-confidence 为一个分数（例如 0.85），则它将用于在模拟中找到一个置信区间，与截止日期进行比较。

• –charts-wip 用于绘制 WIP 箱线图，显示每周的最小值、最大值、中位数和平均 WIP。默认情况下，这将显示最后 5 或 6 周的数据（具体取决于工作日）。您可以使用 –charts-wip-window 参数来更改此设置，将其设置为周数。

• –charts-ageing-wip 用于绘制 WIP 老化图：当前周期时间与周期状态（即项目如何趋向完成）的散点图。

• –charts-net-flow 用于显示 每周净流量的条形图：出发 - 到达。默认情况下，这将显示最后 5 或 6 周的数据（具体取决于工作日）。您可以使用 –charts-net-flow-window 参数来更改此设置，将其设置为周数。

注意：所有 –charts-* 选项都有一个相应的 –charts-*-title 选项，可以用于设置图表的标题。

最后，要限制图表中显示的数据的日期范围，可以使用 –charts-from 和 –charts-to 选项来指定起始日期和/或结束日期（包括）。两者都是可选的。

故障排除

• 如果 Excel 抱怨 SYLK 格式错误，请忽略它。单击“确定”。参见 https://support.microsoft.com/en-us/kb/215591。

• JIRA 错误消息可能以 HTML 的形式在控制台打印出来。错误可能在其中，但可能难以看到。最可能的原因是认证失败（用户名/密码错误或账户被封锁），或者是 条件 部分中的错误导致无效的 JQL。

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

• 在修改工作流程后，旧的工作流程状态仍然可能是问题历史的一部分。使用 -v 选项来查找尚未映射的工作流程状态。

• Excel 有时会在 CSV 文件中的数据选择奇怪的格式。只需将其设置为合理的格式即可。

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

  backend : Agg

• 在 Mac 上安装图表依赖项时，您可能需要安装 scipy 的 gfortran 编译器。使用 Homebrew（《https://brew.sh.cn》）并安装 gcc brew。

临时分析

有时，您可能想要对周期数据执行更多探索性、临时的分析。 jira-cycle-extract 使用 Python Pandas（《https://pandas.ac.cn》）来执行大部分繁重的工作，Pandas 提供了一个丰富的数据科学环境。

Jupyter Notebook（《https://jupyter.pythonlang.cn》）是使用 Pandas（以及更多！）进行交互式、临时分析的一种流行方式。

如果您正在运行此操作，以下是一个使用 jira-cycle-extract 和给定的 YAML 文件配置查询 JIRA 并使数据可用于进一步分析的笔记本示例

import getpass
import datetime

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl
import seaborn as sns

from jira import JIRA
from jira_cycle_extract import cycletime, config

# Print charts in the notebook, using retina graphics
%matplotlib inline
%config InlineBackend.figure_format = 'retina'
sns.set_context("talk")

# Prompt for JIRA username, password and config file:
username = raw_input("Username:")
password = getpass.getpass("Password:")
config_filename = raw_input("Config file:")

# Parse options
options = {}
with open(config_filename) as config_file:
    options = config.config_to_options(config_file.read())

# Connect to JIRA
jira = JIRA(options={'server': options['connection']['domain']}, basic_auth=(username, password))

# Fetch issues and calculate cycle data as a Pandas DataFrame
q = cycletime.CycleTimeQueries(jira, **options['settings'])
cycle_data = q.cycle_data(verbose=False)

# Calculate other DataFrames for CFD, scatterplot, histogram, percentile and throughput data
cfd_data = q.cfd(cycle_data)
scatter_data = q.scatterplot(cycle_data)
histogram_data = q.histogram(cycle_data)
percentile_data = q.percentiles(cycle_data, percentiles=quantiles)
daily_throughput_data = q.throughput_data(cycle_data[cycle_data])

现在您可以对各种 DataFrame（《cycle_data》、《cfd_data》等）进行分析。

变更日志

0.10 - 2016年6月8日

• 为所有图表添加了标题选项

• 为燃尽预测图添加了截止日期选项

0.9 - 2016年5月31日

• 添加 Docker 文档

0.8 - 2016年5月30日

• 修复了在跳过状态时计算CFD的bug

• 添加了 –throughput 输出

• 使用 –percentiles 时，百分位数现在保存到文件中，而不是打印出来

• 添加了图表输出（带可选依赖项 - 见上方）

0.7 - 2016年1月22日

• 添加了对 –format=json 的支持

• 以ISO格式（YYYY-MM-DD）输出所有日期

0.6 - 2016年1月20日

• 添加了对 查询 和 已知值 的支持。

0.5 - 2015年11月8日

• 当问题从一个映射到相同工作流程步骤的两个JIRA状态之间移动时，记录 最早的 日期，而不是最近的日期

• 当问题按照工作流程步骤的顺序向后移动时，保留问题进入给定步骤的 最早 日期（并擦除为所有后续步骤记录的任何日期）

0.4 - 2015年10月31日

• 修复了当摘要包含非ASCII字符时的编码错误

0.3 - 2015年10月11日

• 添加了对 –cfd、–scatterplot、–percentiles 和 –histogram 的正确支持

• 修复了主要周期数据提取中的一些打字错误

0.2 - 2015年10月10日

• 修复了文档错误

0.1 - 2015年10月10日

• 初始发布