Contrib

A python package for making stacked area plots of contributions to a git repository over time. Plots can show contributions by authors, or by organizations.

安装

contrib 在PyPI上，因此您可以直接使用 pip install 安装它

$ pip install contrib

或者，您可以克隆此项目，将其目录添加到您的 PYTHONPATH 中，并将 bin 目录添加到您的 PATH 中。

使用方法

要使用 contrib，您需要创建一个配置文件，告诉它您的代码所在的位置。以下是Spack的一个示例；您可以在 spack-contributions 仓库中找到完整的代码。

以下是一个示例 contrib.yaml

contrib:
  # Path to your git repository. to run git blame on.
  # Consider making this a git submodule.
  repo:   ./spack

  # JSON file mapping authors to organizations (optional)
  orgmap: ./author-to-org.json

  # Separate parts of the repository to process (optional).  For each
  # commit, contrib will look for files that match the patterns in each
  # part.  For a simple repo, you may only need one regular expression
  # per part.  In Spack, the packages have moved around in the repo over
  # time, so we provide multiple patterns.  Contrib will use the first
  # pattern matched by any file in each commit.
  parts:
    packages:
      - ^var/spack/repos/builtin/packages/.*\.py$
      - ^var/spack/packages/.*\.py$
      - ^lib/spack/spack/packages/.*\.py$

repo 需要在您的本地文件系统中，最好在 contrib.yaml 相同的目录下。 orgmap 是可选的（下面将说明如何生成它）。 parts 也是可选的；如果您没有指定它，将有一个名为 all 的部分，它匹配所有内容

    parts:
      all:
        - ^.*$

您可以为您的部分命名任何名称；请参见上面的示例，了解如何模拟一个在子目录中移动了不同逻辑部分的仓库。

将作者映射到组织

orgmap（上面的示例中的 author-to-org.json）是可选的。如果您选择提供它，它应该是一个简单的 json 字典，将作者映射到组织

{
  "Author 1": "UIUC",
  "Author 2": "LBL",
  ...
  "Author N": "LLNL"
}

您可以通过运行 contrib --update-org-map 来生成一个初始的 orgmap。 contrib 将查看您的仓库历史并自动生成文件

$ contrib --update-org-map
==> Added 503 new authors to 'author-to-org.json'
==> New orgmap file created in 'author-to-org.json'.
==> Add it to './contrib.yaml' like this:

    contrib:
        orgmap: author-to-org.json

然后，如果您将此文件添加到您的 contrib.yaml 中，您可以在仓库发展过程中更新它

$ contrib --update-org-map
==> Added 10 new authors to 'author-to-org.json'

新添加的作者将在json文件中被标记为unknown <email from git>

  "Author 1": "unknown <foo@bar.com>",
  "Author 2": "unknown <444532+someusername@users.noreply.github.com>",
  "Author 3": "unknown <user@example.com>",

您可以替换这些为有效的组织，或者保留它们，它们将显示为“unknown”在contrib图中。

运行

在您设置好所有这些后，您可以在contrib.yaml所在的目录中运行contrib。

$ ls
author-to-org.json  contrib.yaml
$ contrib
==> Indexing 49 commits.

STARTED       0/49 53ab298e88f80454f7f7c20ef200a3dbd0870473
    packages: processed 45/3487 blames (9.04/s)
...

默认情况下，contrib将从您的仓库中采样50个提交并绘制它们。如果您想绘制较少的样本，可以运行contrib --samples SAMPLES，其中SAMPLES是您选择的数字。contrib会尝试使用运行它的机器上的可用处理器，默认情况下它将并行运行git blame任务。您可以使用--jobs JOBS参数控制并行性。

contrib必须为每个采样的提交以及与您的contrib.yaml文件中的parts部分匹配的每个文件（如果没有提供parts，则为所有文件）运行git blame，因此如果您的仓库历史记录很长，它可能需要很长时间。 contrib的输出显示了剩余多少个git blame调用以及当前完成的速度有多快。

缓存数据

contrib将git blame的结果缓存到一个名为line-data的目录中。对于大型仓库，这可能会变得相当大，因此请确保您有足够的可用空间（大型仓库需要数GB）。

许可

Contrib是Spack项目的一部分。Spack根据MIT许可证和Apache许可证（版本2.0）的条款进行分发。用户可以选择任一许可证。

所有新的贡献都必须在MIT和Apache-2.0许可证下进行。

有关详细信息，请参阅LICENSE-MIT、LICENSE-APACHE、COPYRIGHT和NOTICE。

SPDX-License-Identifier: (Apache-2.0 OR MIT)

LLNL-CODE-647188