Package: contrib
ContribA python package for making stacked area plots of contributions to a git
repository over time.  Plots can show contributions by authors, or by
organizations.Installationcontribis on PyPI, so you can justpip installit:$pipinstallcontribAlternately, you can clone this project, add its directory to yourPYTHONPATH, and add thebindirectory to yourPATH.UsageTo usecontrib, you'll need to create a configuration file telling it
where to find your code.  Below is an example for Spack; you can find
complete code in thespack-contributionsrepo.Here's an examplecontrib.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$Thereponeeds to be in your local filesystem, preferably in the same
directory ascontrib.yaml.orgmapis optional (see below for how to
generate it).partsis also optional; if you do not specify it, there
will be one part calledallthat matches everything:parts:all:-^.*$You can name your parts anything; see the example above for how to model
a repository where different logical parts have moved around in
subdirectories.Mapping authors to organizationsTheorgmap(author-to-org.jsonin the example above) is optional.  If
you choose to provide it, it should be simplejsondictionary mapping
authors to organizations:{"Author 1":"UIUC","Author 2":"LBL",..."Author N":"LLNL"}You can runcontrib --update-org-mapto generate anorgmapto start
with.contribwill look at your repository's history and generate the
file automatically:$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.jsonIf you then add this file to yourcontrib.yaml, you can update it later
as your repository evolves:$contrib--update-org-map==> Added 10 new authors to 'author-to-org.json'Newly added authors will be labeled asunknown <email from git>in thejsonfile:"Author 1":"unknown <foo@bar.com>","Author 2":"unknown <444532+someusername@users.noreply.github.com>","Author 3":"unknown <user@example.com>",You can replace these with valid organizations, or just leave them and
they'll show up as "unknown" in thecontribplots.RunningOnce you've got all of that set up, you can runcontribin the
directory wherecontrib.yamllives:$lsauthor-to-org.json  contrib.yaml$contrib==> Indexing 49 commits.STARTED       0/49 53ab298e88f80454f7f7c20ef200a3dbd0870473packages: processed 45/3487 blames (9.04/s)...By default,contribwill sample 50 commits from your repository and
plot them.  If you want it to plot fewer samples, you can runcontrib --samples SAMPLESwhereSAMPLESis a number of your choosing.contribtries to use the available processors on the machine it is
run, and by default it will run parallelgit blamejobs.  You can
control the parallelism with the--jobs JOBSargument.contribhas to rungit blamefor each sampled commit and for each
file matched by thepartssection of yourcontrib.yamlfile (or for
all files ifpartsis not provided), so it can take a long time to run
if your repo's history is long.contrib's output shows how manygit blamecalls remain and how fast blames are currently completing.Cached datacontribcaches results ofgit blamein a directory calledline-data.  For large repositories, this can get to be quite large, so
make sure you have a decent amount of space available (gigabytes for
large repositories).LicenseContrib is part of the Spack project. Spack is distributed under the
terms of both the MIT license and the Apache License (Version 2.0). Users
may choose either license, at their option.All new contributions must be made under both the MIT and Apache-2.0
licenses.SeeLICENSE-MIT,LICENSE-APACHE,COPYRIGHT, andNOTICEfor details.SPDX-License-Identifier: (Apache-2.0 OR MIT)LLNL-CODE-647188