github 自动化集成_使用GitHub Actions进行软件开发指标自动化

github 自动化集成

Most Software Engineers would agree on the ineffectiveness of measuring productivity based on lines code, however, I’ ve seen that because of this, the industry has fallen on a cynism thinking that Software Productivity cannot be measured accurately.

大多数软件工程师都会同意基于行代码来衡量生产力的无效性，但是，我已经看到，因此，整个行业都在愤世嫉俗地认为无法准确衡量软件生产力。

Just because something is hard, does not mean it is not possible.

仅仅因为有些困难，并不意味着不可能。

For some of us is quite often the opposite, we thrive on challenges and look to push the boundaries of innovation. As a Software Engineer, I see three main reasons why quantifying Software Productivity would be desirable.

对于我们中的某些人而言，情况往往恰恰相反，我们在挑战中壮成长，并寻求突破创新的界限。 作为软件工程师，我看到了需要量化软件生产率的三个主要原因。

1. For business owners, managers, tech leaders, or engineers looking to evaluate and get feedback on their work and/or project.2. Open source users, to quickly assess a project before committing to it.3. Data scientists recognizing that knowledge comes only after a hypothesis can be tested and validated.

1.对于希望评估其工作和/或项目并获得反馈的企业所有者，经理，技术领导者或工程师。2。 开源用户，以便在提交项目之前快速评估项目3。 数据科学家认识到，只有在对假设进行检验和验证之后才能产生知识。

主要软件指标： (Main Software Metrics:)

As an introduction to metrics and following a rather arbitrary but pragmatic taxonomy I will classify metrics in 5 categories: Code Lifecycle, Code Quality, Team Dynamics, Project Health & Business Requirements.

作为指标的介绍，并遵循一种相当随意但务实的分类法，我将指标分为5类：代码生命周期，代码质量，团队动态，项目健康和业务需求。

The code lifecycle is the simplest of all, and also the less subjective. It rather measures the amount of time your development pipeline takes to implement, as an added bonus it is almost always the easiest to interpret as in most cases the fastest your code lifecycle is the better your project should be. To explain the implementation let’s identify key milestones on the software development lifecycle: first commit (branch creation), pull request created & pull request merged & feature release.

代码生命周期是最简单的，也是主观的。 它宁可衡量您的开发管道实现所需的时间，而额外的好处是，它几乎总是最容易解释的，因为在大多数情况下，代码生命周期越快，项目就应该越好。 为了解释实现，让我们确定软件开发生命周期中的关键里程碑：首次提交(创建分支)，创建拉取请求，合并拉取请求和功能发布。

From this milestones is easy, to abstract simple, yet very useful metrics:

从这些里程碑很容易，可以抽象出简单但非常有用的指标：

• Development time: from the first commit to PR merged.

  开发时间：从第一次提交到PR合并。

• Deployment time: from PR merged to release.

  部署时间：从PR合并到发布。

• Code review time: from PR created to PR merged.

  代码检查时间：从创建PR到合并PR。

Now, depending on your CI/CD pipeline additional steps may be added, some examples include unit test coverage threshold on new code (usually between 60% - 90%), E2E and/or integration testing completion based on the feature requirements, code review approvals (highlighting the first review as the most relevant to measure), and user story creation time & assignment.

现在，根据您的CI / CD管道，可能会添加其他步骤，一些示例包括新代码的单元测试覆盖率阈值(通常在60％-90％之间)，基于功能要求的E2E和/或集成测试完成，代码审查批准( 突出显示与度量最相关的第一条评论 )以及用户故事创建时间和任务。

The two last milestones, create a metric that encompasses the full product development lifecycle.

最后两个里程碑创建了一个包含整个产品开发生命周期的指标。

However, while it is tempting to reduce this time to the most possible. In practice, it should not be, as good development practices would allow a time to plan and mature user stories before actively working on them. As a rule of thumb, the “maturing” would be proportional to the development time.

但是，虽然很可能会尽量减少这种时间。 实际上，不应该这样，因为良好的开发实践将允许有一段时间计划并完善用户故事，然后再积极研究它们 。 根据经验，“成熟”将与开发时间成正比。

To finalize the exposition of code-lifecycle metrics, there is another breed o that does not focus on duration but rather on the frequency of the events. The most important of is how often does the team release new code, is it on a daily basis, weekly, monthly, or more?

为了最终确定代码生命周期度量标准的说明，还有另外一个品种，它不关注持续时间，而是关注事件的发生频率。 最重要的是团队多长时间发布一次新代码，它是每天，每周，每月还是更多？

Photo by Mathew Schwartz on Unsplash

Mathew Schwartz在 Unsplash上的 照片

The rest of the metrics are not as straightforward to implement nor interpret thus, I will only cover them briefly:

其余指标并不是很容易实现或解释，因此，我将仅简要介绍它们：

代码质量 (Code Quality)

Code coverage is fairly well developed, easy to understand and implement, a second step on this is to measure the degree of change in code coverage with new commits, the percentage of new code is well tested and how many “legacy” code is revisited with increased testing.

代码覆盖范围相当完善，易于理解和实施，第二步是通过新提交来衡量代码覆盖范围的变化程度，对新代码的百分比进行了良好的测试，并使用了多少“遗留”代码增加测试。

Using standardized linting, we can get a good approximation on how many tests per lines of code there are, a great idea is to visualize directories and files as a graph with colored nodes based on relative wellness of test coverage.

使用标准化的衬里，我们可以很好地估计每行代码中有多少个测试，一个好主意是根据测试覆盖范围的相对状况将目录和文件可视化为带有彩色节点的图形 。

Code quality does not come from test coverage only but also from collaboration.

代码质量不仅来自测试范围，还来自协作。

The number of comments per PR is a good way to measure that, more advanced use cases include the quality and tone of the comments, assessed using NLP.

每个PR的评论数量是一种很好的衡量方式，更高级的用例包括使用NLP评估的评论的质量和基调。

Two last comments on code quality: the ratio of bug-fixes and the percentage of high-risk PRs. Here, we start getting subjective but classifying a PR as a bug fix can be as simple as labeling it, more advanced cases include tracing the origin of the bug (git blame) and how many tests were in place before fixing it. As for the high risks PRs they can be determined from the size of the PR, medium risk PRs are big with mostly new code in them or small refactors, high-risk PRs are big reactors.

关于代码质量的最后两个评论： 错误修复率和高风险PR的百分比。 在这里，我们开始变得主观，但是将PR作为错误修复进行分类就像标记它一样简单，更高级的案例包括跟踪错误的来源(git blame)以及在修复之前进行了多少测试。 至于高风险PR，可以通过PR的大小来确定，中风险PR很大，其中大多数是新代码，重构较小，高风险PR是大React堆。

团队动力 (Team Dynamics)

Software is not only about code & engineering but also about people. Sure, a good first step to evaluate the team is to segment the above metrics by contributor but more interesting cases turn around on how the team collaborates with each other.

软件不仅与代码和工程有关，而且与人员有关。 当然，评估团队的一个很好的第一步是按贡献者对上述指标进行细分，但更有趣的案例是团队之间如何进行协作。

There are “hidden” productivity metrics that can be measured by individual, to better assess his or her global contribution to the team.

有一些“隐藏的”生产率指标可以由个人进行衡量，以更好地评估其对团队的全球贡献。

These include: documentation, PR reviews & library or reusable code developed, sure developing a dozen API endpoints is good, but developing an abstraction to catch and monitor errors can be better and more difficult to replace.

其中包括：开发了文档，PR评论和库或可重用代码，确保开发十二个API端点是好的，但是开发用于捕获和监视错误的抽象可能会更好并且更难替换。

项目健康 (Project Health)

It can be measured by what direction/services are being worked on using once again a graph, how many new contributors are being added, and how many new issues are created.

可以通过再次使用图表，正在添加多少新贡献者以及创建了多少新问题来衡量正在朝哪个方向/服务进行工作。

Also important is how fast are the issues being resolved (especially, the critical ones), and who is creating them, is it business, QA, developers, or the end-users? Curiously, the answer to that last question depends on the maturity of your project as you would hope that when starting end-users catch and report bugs while on later stages it is your QA and other internal teams.

解决问题(特别是关键问题)的速度有多快，以及由谁来创建，是业务，质量保证，开发人员还是最终用户，这也很重要。 奇怪的是，最后一个问题的答案取决于项目的成熟度，因为您希望当最终用户开始时捕获并报告错误，而在以后的阶段是您的质量保证和其他内部团队。

业务需求。 (Business Requirements.)

While highly subjective is good to measure to know how many iterations for new features until it becomes stale, how long each user story takes to complete, and how many “pivots” of a new feature occur, this last captures how many change of requirements there are.

主观性很强，可以用来衡量新功能在变旧之前要进行多少次迭代，每个用户故事要花多长时间才能完成，以及新功能发生了多少“支点”，这最后捕获了那里需求的多少变化是。

Carryover, or what percentage of tasks are passed from one Sprint to the next is also relevant.

结转或从一个Sprint传递到下一个Sprint的任务百分比也很重要。

Photo by Jan Padilla on Unsplash

Jan Padilla在 Unsplash上 拍摄的照片

GitHub动作介绍。 (Introducing GitHub Actions.)

In November 2019, Github released Actions and per its own definition,

在2019年11月，Github发布了Actions并根据其自己的定义，

it makes it easy to automate all your software workflows, with world-class CI/CD. Build, test, and deploy your code right from GitHub. Make code reviews, branch management, and issue triaging work the way you want.

它具有世界一流的CI / CD ，可轻松实现所有软件工作流程的自动化。 直接从GitHub构建，测试和部署代码。 使代码审查，分支机构管理和问题分类工作按您想要的方式进行。

Github has built a marketplace where you can incorporate to your own projects third-party tools or develop your own. It is with capability that measuring productivity becomes a real possibility. By tracking events (commits, pull requests, code reviews, and more) directly into your repository:

Github建立了一个市场，您可以在其中集成第三方工具或开发自己的项目。 具备测量生产力的能力。 通过将事件(提交，拉取请求，代码审查等)直接跟踪到存储库中：

Is possible to automatize, standardize, and report the metrics using code.

可以使用代码自动化，标准化和报告指标。

Github documentation is amazing, nevertheless let's get to some basic definitions:

Github文档很棒，但是让我们了解一些基本定义：

工作流程 (Workflow)

Is a set of instructions executed by a specific event. This can be as simple as running your unit tests, deploying your infrastructure, or running a particular JS script.

是由特定事件执行的一组指令。 这可以像运行单元测试，部署基础结构或运行特定的JS脚本一样简单。

Workflows are composed of jobs: independent set of instructions that can be executed concurrently, each job in turn, is composed of steps that contain one or several commands executed in a Docker container. Normally, Ubuntu flavored.

工作流由作业组成：一组可以同时执行的独立指令，每个作业又由包含一个或多个在Docker容器中执行的命令的步骤组成。 通常，Ubuntu具有风味。

扳机 (Triggers)

Are the set of events that start workflows besides commits and other usual ones. they are executed by schedule (cron jobs), when issues are created, commented or labeled, or when new tasks are created on projects. At the repository level events such as starring, forking or watching can also create triggers, and there are also trigger from webhooks, manual actions, and much more…

是除了提交和其他常见事件之外启动工作流的事件集。 它们是按计划执行的(定时作业)，在创建，注释或标记问题时或在项目上创建新任务时执行。 在存储库级别，诸如加注星标，分叉或观看之类的事件也可以创建触发器，并且还存在来自Webhook，手动操作等的触发器…

动作 (Actions)

Actions are developed solutions by top SaaS providers, leading Open Source projects, and motivated individuals that abstract a group of commands in a single request. An example of a really interesting one is Cypress.

行动是由顶级SaaS提供商，领先的开源项目以及有动机的个人在单个请求中抽象出一组命令而开发的解决方案。 赛普拉斯是一个非常有趣的例子。

A great way to get started to develop your actions are learning labs provided by GitHub in particular the one on Javascript is really easy to follow. Besides that, actions can be implemented in Python, Java & Docker.

GitHub提供的学习实验室是开始制定行动的一个好方法，特别是Javascript上的学习实验室非常容易遵循。 除此之外，可以在Python，Java和Docker中实现操作。

八度 (Octokit)

Is the last piece we need to get started automatizing Software Metrics, it is the official Github API client, and with it, the breadth of possibilities is intimidating. As a rule of thumb if you can do it in GitHub you can do it with Ocktokit.

这是我们开始自动执行软件度量标准的最后一步，它是Github API的官方客户端，随之而来的是，无限的可能性令人生畏。 根据经验，如果可以在GitHub中进行操作，则可以使用Ocktokit进行操作。

实施软件指标收集器MVP (Implementing a Software Metrics Collector MVP)

Photo by Murilo Viviani on Unsplash

Murilo Viviani在 Unsplash上 拍摄的照片

Designing an MVP is all about simplification

设计MVP就是为了简化

And thus code lifecycle metrics are the natural candidate for implementation. As for reporting them it gets more complicated, my initial thought was to create a simple React dashboard, however, on a closer look, that is more like a full product. Then I thought of a Slack bot, it is handy, quick, and simple to develop. Fortunately, there is one more straightforward approach to it:

因此，代码生命周期指标自然是实现的候选对象。 至于报告它们变得更加复杂， 我最初的想法是创建一个简单的React仪表板，但是仔细观察，它更像是一个完整的产品。 然后我想到了一个Slack机器人，它很容易，快速且易于开发。 幸运的是，还有一种更简单的方法：

注释将指标直接发送到GitHub： (Commenting put the metrics directly to GitHub:)

Main lifecycle metrics as a comment.

主要生命周期指标作为注释。

My first attempt was commenting to an issue, I thought about creating a particular label opening the issue and closing it once all the metrics were collected.

我的第一个尝试是评论一个问题，我考虑过要创建一个特定的标签来打开该问题，并在收集所有指标后将其关闭。

In the end, things got simpler as I commented directly to the PR.

最后，当我直接向PR发表评论时，事情变得简单了。

Dependencies: Besides Octokit to query and interact with GitHub, there was the need to preserve events. I choose Mongo for that and with MomentJS to work with dates I was ready to get started.

依赖关系：除了使用Octokit来查询和与GitHub交互之外，还需要保留事件。 我为此选择了Mongo，并选择MomentJS处理准备开始的日期。

Photo by Kaleidico on Unsplash

Kaleidico在 Unsplash上 拍摄的照片

发展历程 (Development)

First step detecting relevant events:

第一步，检测相关事件：

1. Branch creation
   创建分支
2. Commits
   提交
3. Pull requests creation
   拉取请求创建
4. Commits during PR
   公关期间提交
5. Merge
   合并

First, configure the workflow to listen to those particular events:

首先，配置工作流以侦听那些特定事件：

# Workflow triggers
on:
  push:
    branches-ignore:
      — master
  pull_request:
    types: [opened, closed]

What is it doing here? We listen to every push except the ones done to master. With this, we handle events 1, 2 & 4.

这是在做什么 我们聆听每一次推送，除了需要掌握的推送。 这样，我们就可以处理事件1、2和4。

Why is it ignoring master? it is easier to comment on the issue if is handle through a pull request event.

为什么忽略高手？ 如果通过拉取请求事件进行处理，则更容易评论该问题。

The second triggers listen to pull requests being opened and closed (yes merging is actually a closure). If we were not to ignore the push to master, we would be creating two pipelines from the merge event.

第二个触发器侦听打开和关闭的拉取请求(是的，合并实际上是一个关闭)。 如果我们不忽略对主控的推动，那么我们将从合并事件中创建两个管道。

That handles triggering the pipeline, now let’s differentiate the events:

处理触发管道的操作，现在让我们区分事件：

const github = require(“@actions/github”);
const core = require(“@actions/core”);async function run() {  const action = github.context.payload.action;  const isNewBranch = github.context.payload.created;
  const isOpened = action === ‘opened’;  const isClosed = action === ‘closed’;
  const pull_request = github.context.payload.pull_request;
  const isMerged = isClosed && pull_request.merged;  ...
}

That is a JS script that gets all the information required, most is included in the GitHub context, and through very similar code we can get the branch name to identify to what feature it relates.

这是一个JS脚本，可获取所需的所有信息，大部分信息都包含在GitHub上下文中，并且通过非常相似的代码，我们可以获取分支名称来标识与其相关的功能。

Now only two more things to go: initialize the DB and comment on the issue:

现在只剩下两件事了：初始化数据库并对问题发表评论：

steps:
   — uses: actions/checkout@v2
   — name: collect-metrics
     uses: ./.github/actions/metrics
     with:
       repo-token: ${{secrets.GITHUB_TOKEN}}
       mongo-password: ${{secrets.MONGO_PWD}}

The actions/checkout@v2 is usually the first step of every pipeline, with that we pull the code from GitHub to the Docker container. The second part invokes the metrics action with two “secret” values: the GITHUB_TOKEN is automatically created by the pipeline, and the MONGO_PWD is defined on the repository. It will be used to connect to the DB in a safe way.

actions / checkout @ v2通常是每个管道的第一步，我们将代码从GitHub拉到Docker容器。 第二部分使用两个“秘密”值调用度量动作：GITHUB_TOKEN由管道自动创建，而MONGO_PWD在存储库上定义。 它将用于以安全的方式连接到数据库。

Let’s see how to comment on the PR:

让我们看看如何对PR发表评论：

const github = require(“@actions/github”);
const core = require(“@actions/core”);async function run() {
  …  const token = core.getInput(“repo-token”); # Get the token passed.
  const octokit = github.getOctokit(token); # Initiate octokit.  # Get data relevant to find the PR issue.
  const repository = github.context.repo.repo;
  const owner = github.context.repo.owner;
  const issue = github.context.payload.number  # Comment on the issue.
  await octokit.issues.createComment({
    repo: repository,
    owner: owner,
    issue_number: issue,
    body: body # This data is retrieved from MongoDB.
  }); 
}

As simple as that! Initialize Octokit, find the issue and create a comment :)

就如此容易！ 初始化Octokit，找到问题并创建评论:)

下一步 (Next Steps)

Natural first steps would be to build a front-end and export the action to the market place. However, there are a couple of concerns I have in doing that:

自然而然的第一步是建立一个前端并将动作导出到市场。 但是，在执行此操作时我有一些担忧：

1. How to protect the DB, against abusive behavior. This example works because the secret is stored inside my project, however, how to safely open a connection from other projects?2. Not many projects would gladly share their GitHub tokens, even more important, there might some restrictions from GitHub on doing that. 3. Marketing a new action is though, how to know what front-end to build if the action has no users

1.如何保护数据库，防止滥用行为。 此示例有效，因为机密存储在我的项目中，但是，如何安全地打开其他项目的连接？2。 没有多少项目会很乐意共享他们的GitHub令牌，更重要的是，GitHub可能对此有一些限制。 3.不过，营销一项新的操作是，如果该操作没有用户，如何知道要构建哪个前端？

Based on that, I decided the best way to go is the option to evaluate Open Source projects’ health instead.

基于此，我认为最好的方法是评估开放源代码项目的运行状况。

I imagine a simple search Google-like UI connected to Github's API. Where a user can select a repository and get some metrics on its health. Since most of the methods to the API would be open, I might be able to get some valuable data from them.

我想象一个连接到Github API的类似于Google的简单搜索UI。 用户可以在其中选择存储库并获取有关其运行状况的一些指标。 由于API的大多数方法都是开放的，因此我也许可以从中获取一些有价值的数据。

Maybe at the bottom, I could split the section with “featured” repos based on recent activity and possibly a “ranking” system in the second section.

也许在底部，我可以根据最近的活动以及第二部分中的“排名”系统，以“功能性”存储库来划分该部分。

Advertisement could be a good source of side revenue while, while the path of integrating it natively to GitHub would be less direct. For projects, a good first step would be to embed the metrics in the ReadMe via a snippet.

广告可能是附带收入的良好来源，而将其本地集成到GitHub的途径则不太直接。 对于项目，一个好的第一步是通过代码片段将指标嵌入自述文件中。

While for contributors I’m thinking a more ambitious approach:

对于贡献者，我正在考虑一种更雄心勃勃的方法：

How about getting recommendations on what Open Source to collaborate based on your commit history?

如何根据您的提交历史记录获取有关要协作的开放源代码的建议？

Photo by Steve Johnson on Unsplash

史蒂夫·约翰逊 ( Steve Johnson)在 Unsplash上的 照片

Thank you for reading.

感谢您的阅读。

翻译自: https://medium.com/swlh/software-development-metrics-automation-using-github-actions-30a51fd56df0

github 自动化集成