Projects Migrator

将一个或多个ZenHub工作区迁移到GitHub项目

安装

pip install projectsmigrator

使用

projectsmigrator https://github.com/orgs/myorg/myproj/1 -w="Workspace 1" --w="Workspace 2" -f="Estimate:Size" 

详情

Projects Migrator: Sync Zenhub workspaces into a single Github Project

Usage:
  projectsmigrator PROJECT_URL [--workspace=NAME]... [--exclude=FIELD:PATTERN]... [--field=SRC:DST]... [options]
  projectsmigrator (-h | --help)

Options:
  -w=NAME, --workspace=NAME            Name of a Zenhub workspace to import or none means include all.
  -f=SRC:DST:CNV, --field=SRC:DST:CNV  Transfer SRC field to DST field. "Text" as DST will add a checklist
                                       for Epic and Blocking issues, and values into the text for other fields.
                                       CNV "Scale" (match by rank), Exact or Closest (default).
                                       One SRC can have many DST fields.
                                       [Default: Estimate:Size:Scale, Priority:Priority, Pipeline:Status,
                                       Linked Issues:Text, Epic:Text, Blocking:Text, Sprint:Iteration]
                                       "SRC:" Will not transfer this field
  -x=FIELD:PAT, --exclude=FIELD:PAT    Don't include issues with field values that match the pattern
                                       e.g. "Workspace:Private*", "Pipeline:Done".
  --disable-remove                     Project items not found in any of the workspace won't be removed.
  --github-token=<token>               or use env var GITHUB_TOKEN.
  --zenhub-token=<token>               or use env var ZENHUB_TOKEN.
  -h, --help                           Show this screen.

For zenhub the following fields are available.
- Estimate, Priority, Pipeline, Linked Issues, Epic, Blocking, Sprint, Position, Workspace

For Projects the fields are customisable. However the following are special
- Status: the column on the board
- Position: Id of the item to place after
- Text: turns the value into a checklist/list in the body
- Linked Pull Requests: changes to the body of each PR to link back to the Issue  

或最新使用方法或运行

projectsmigrator --help

注意：如果您想安装最新代码的github checkout版本

python3 -m pip install -e .

项目

该项目必须是已经存在的组织ProjectV2项目。

您应首先手动添加您想要的状况和其他字段选项。

列/状况

默认设置是-f="Pipeline:Status"

如果该列/状况值不存在，则不会自动添加，而是将问题放置在匹配的最接近的现有列中。

在该列中的位置使用默认的-f="Position:Position"设置。

您可以使用--exclude=Pipeline:MyIgnoredPipelines*排除管道。

您可以通过-f="Pipeline:Status:Exact"将最接近的匹配行为更改为精确匹配。

史诗

默认设置是-f="Epic:Text"

这将作为以下形式的检查表重新创建史诗：

# Dependencies

## Epic
- [ ] #23
- [ ] otherorg/otherepo#42

虽然“项目”没有对史诗的原生支持，但这似乎正是GitHub推荐将条目相关联的方法。当你在其他地方查看一个清单问题时，你将看到在标题下方突出显示的内容，并包括“依赖史诗”标题，这样你就可以看到它们之间的关联。

你会失去的一个功能是按史诗筛选看板。如果你想的话，可以将史诗作为一个子问题的字段。

-f="Epic:MyEpicField"。这将设置值为史诗的名称。

或者你同时设置。

-f="Epic:Text" -f="Epic:MyEpicField"

GitHub目前不支持多值字段，因此无法通过字段在史诗问题本身上设置链接。

阻塞/被阻塞

默认设置为 -f="Blocking:Text"

被阻塞的问题将添加一个依赖项部分，其中列出阻塞的问题

例如：

# Dependencies

## Blocked by
- [ ] #23
- [ ] otherorg/otherepo#42

阻塞的问题将保持不变。

关联问题

默认设置为 -f="Linked Issues:Text"

由于Zenhub有自己将拉取请求与问题相关联的方式，因此此信息通过修改PR以添加文本来传输，然后使用GitHub的自动PR链接功能。

例如：

- [ ] fixes otherorg/otherepo#42

它不会对组织中项目之外的仓库的PR做此操作。

注意：GitHub关联的PR在合并到主分支后将自动关闭关联的条目。这与Zenhub不同。虽然你不能改变这种行为，GitHub在关闭时也不会自动移动项目中的条目，因此这不应该太大地改变你的工作流程。

工作区

你可以使用以下方式指定要合并的工作区：

--workspace="Workspace 1" --workspace="Workspace 2"

或者合并所有工作区，排除一些

--exclude="Workspace:Workspace 1*"

它们将按照优先级列表合并。即如果字段/管道数据不同，则使用第一个工作区数据

如果没有指定工作区，则将按最近使用顺序合并所有工作区

你可以选择性地将问题来自的工作区名称添加到新的自定义字段中，但如果不启用，则不会传输此信息。这可以通过 -f="Workspace:MyWorkspaceField" 启用。

优先级

默认设置为 -f="Priority:Priority"

默认情况下，“项目”有一个名为“优先级”的自定义字段，其选项比ZenHub的“高优先级”标志更多。如果此字段存在，我们将迁移高优先级问题到最接近的匹配项。

估算

默认设置为 -f="Estimate:Size:Scale"

默认的“项目”等效项是“大小”，其比例与默认Zenhub故事点不同。

这是按排名（:Scale后缀）映射的，而不是按单词匹配。第一个估算选项成为第一个大小选项。最后一个估算选项成为最后一个大小选项，其余按比例映射。目前似乎没有从Zenhub读取估算选项的API，因此它假设默认故事点。如果值不匹配这些之一，它将选择最接近的故事点。

如果你想按最接近的匹配，请使用 -f="Estimate:Size:Closest"。最接近的是基于字母，而不是数值。

冲刺

你可以通过使用 -f="Sprint:MySprintField" 启用冲刺信息的传输。

如果该字段是单选字段，它将选择最接近的匹配选项。

身份验证

你需要访问Zenhub GraphQL API和GitHub GraphQL API。

一旦你获得了两者的认证令牌，你可以：

• 将它们放入环境变量 ZENHUB_TOKEN 和 GITHUB_TOKEN
• 使用 --zenhub-token=<token> 和 --github-token=<token> 命令行选项

对于GitHub，目前似乎只有经典令牌可以工作。为此，你需要 repo、admin:org 和 project 权限。细粒度的个人访问令牌目前似乎不起作用。

待办事项

• 干运行模式
• 详细或不太详细的模式。特别是为了更清楚地查看管道映射
• CSV导入
• 迁移项目 -> 项目
• 通过src字段值过滤问题
• 黑名单某些字段值
• 将标签作为字段目标，例如：将工作区名称作为新标签
• 处理来自已关闭问题的同步数据
• 仅处理Zenhub史诗和问题
• Zenhub里程碑 - 已弃用，无法从graphql获取
• Zenhub版本报告？
• 处理不同的估算尺度
• 修复无法添加更多选项到工作区字段或删除添加字段的问题。
• 设置全局默认值。例如：常规优先级

贡献

欢迎PR或票据

致谢

由PretaGov UK/AU赞助 https://pretagov.com

受此迁移Zenhub到项目的手动流程的启发，但我们受以下因素激励：

• 需要更长的过渡期，因此需要某种同步方式，因此需要更自动化的东西
• 需要将许多工作区合并到单个项目中
• 认为以清单而不是字段表示史诗的想法会更好
• 惊喜的是，没有人编写过这样的工具，其他人可能也会觉得它有用。