{"id":20099020,"url":"https://github.com/spack/contrib","last_synced_at":"2025-05-06T06:30:48.668Z","repository":{"id":62564640,"uuid":"210225582","full_name":"spack/contrib","owner":"spack","description":"A python package for making stacked area plots of contributions over time.","archived":false,"fork":false,"pushed_at":"2022-10-16T22:31:59.000Z","size":308,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-09-22T10:05:18.758Z","etag":null,"topics":["contributors","git","history","metrics","python","spack","statistics"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-22T23:03:49.000Z","updated_at":"2022-10-16T22:32:04.000Z","dependencies_parsed_at":"2022-11-03T16:00:55.993Z","dependency_job_id":null,"html_url":"https://github.com/spack/contrib","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spack%2Fcontrib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spack%2Fcontrib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spack%2Fcontrib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spack%2Fcontrib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spack","download_url":"https://codeload.github.com/spack/contrib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224490710,"owners_count":17319983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contributors","git","history","metrics","python","spack","statistics"],"created_at":"2024-11-13T17:07:48.746Z","updated_at":"2024-11-13T17:07:49.356Z","avatar_url":"https://github.com/spack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contrib\n\n[![PyPI version](https://badge.fury.io/py/contrib.svg)](https://badge.fury.io/py/contrib)\n[![Build Status](https://travis-ci.com/spack/contrib.svg?branch=master)](https://travis-ci.com/spack/contrib)\n[![codecov](https://codecov.io/gh/spack/contrib/branch/master/graph/badge.svg)](https://codecov.io/gh/spack/contrib)\n[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA python package for making stacked area plots of contributions to a git\nrepository over time.  Plots can show contributions by authors, or by\norganizations.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/spack/contrib/master/data/spack-pkgs-plot.png\" width=600\u003e\n\u003c/p\u003e\n\n - [Installation](#installation) using pip\n - [Usage](#usage) on your local machine\n - [Docker](#docker) container usage, locally or via GitHub Actions\n - [Related Projects](#related-projects) of interest\n - [License](#license) information.\n\n## Installation\n\n`contrib` is on PyPI, so you can just `pip install` it:\n\n```console\n$ pip install contrib\n```\n\nAlternately, you can clone this project, add its directory to your\n`PYTHONPATH`, and add the `bin` directory to your `PATH`.\n\n## Usage\n\nTo use `contrib`, you'll need to create a configuration file telling it\nwhere to find your code.  Below is an example for Spack; you can find a\ncomplete example in the\n[spack-contributions](https://github.com/spack/spack-contributions) repo.\n\n\nHere's an example `contrib.yaml`:\n\n```yaml\ncontrib:\n  # Path to your git repository. to run git blame on.\n  # Consider making this a git submodule.\n  repo:   ./spack\n\n  # JSON file mapping authors to organizations (optional)\n  orgmap: ./author-to-org.json\n\n  # Separate parts of the repository to process (optional).  For each\n  # commit, contrib will look for files that match the patterns in each\n  # part.  For a simple repo, you may only need one regular expression\n  # per part.  In Spack, the packages have moved around in the repo over\n  # time, so we provide multiple patterns.  Contrib will use the first\n  # pattern matched by any file in each commit.\n  parts:\n    packages:\n      - ^var/spack/repos/builtin/packages/.*\\.py$\n      - ^var/spack/packages/.*\\.py$\n      - ^lib/spack/spack/packages/.*\\.py$\n```\n\nThe `repo` needs to be in your local filesystem, preferably in the same\ndirectory as `contrib.yaml`.  `orgmap` is optional (see below for how to\ngenerate it).  `parts` is also optional; if you do not specify it, there\nwill be one part called `all` that matches everything:\n\n```yaml\n    parts:\n      all:\n        - ^.*$\n```\n\nYou can name your parts anything; see the example above for how to model\na repository where different logical parts have moved around in\nsubdirectories.\n\n\n### Mapping authors to organizations\n\n\nThe `orgmap` (`author-to-org.json` in the example above) is optional.  If\nyou choose to provide it, it should be simple `json` dictionary mapping\nauthors to organizations:\n\n```json\n{\n  \"Author 1\": \"UIUC\",\n  \"Author 2\": \"LBL\",\n  ...\n  \"Author N\": \"LLNL\"\n}\n```\n\nYou can run `contrib --update-org-map` to generate an `orgmap` to start\nwith.  `contrib` will look at your repository's history and generate the\nfile automatically:\n\n```console\n$ contrib --update-org-map\n==\u003e Added 503 new authors to 'author-to-org.json'\n==\u003e New orgmap file created in 'author-to-org.json'.\n==\u003e Add it to './contrib.yaml' like this:\n\n    contrib:\n        orgmap: author-to-org.json\n\n```\n\nIf you then add this file to your `contrib.yaml`, you can update it later\nas your repository evolves:\n\n```console\n$ contrib --update-org-map\n==\u003e Added 10 new authors to 'author-to-org.json'\n```\n\nNewly added authors will be labeled as `unknown \u003cemail from git\u003e` in the\n`json` file:\n\n```json\n  \"Author 1\": \"unknown \u003cfoo@bar.com\u003e\",\n  \"Author 2\": \"unknown \u003c444532+someusername@users.noreply.github.com\u003e\",\n  \"Author 3\": \"unknown \u003cuser@example.com\u003e\",\n```\n\nYou can replace these with valid organizations, or just leave them and\nthey'll show up as \"unknown\" in the `contrib`  plots.\n\n### Running\n\nOnce you've got all of that set up, you can run `contrib` in the\ndirectory where `contrib.yaml` lives:\n\n```console\n$ ls\nauthor-to-org.json  contrib.yaml\n$ contrib\n==\u003e Indexing 49 commits.\n\nSTARTED       0/49 53ab298e88f80454f7f7c20ef200a3dbd0870473\n    packages: processed 45/3487 blames (9.04/s)\n...\n```\n\nBy default, `contrib` will sample 50 commits from your repository and\nplot them.  If you want it to plot fewer samples, you can run `contrib\n--samples SAMPLES` where `SAMPLES` is a number of your choosing.\n`contrib` tries to use the available processors on the machine it is\nrun, and by default it will run parallel `git blame` jobs.  You can\ncontrol the parallelism with the `--jobs JOBS` argument.\n\n`contrib` has to run `git blame` for each sampled commit and for each\nfile matched by the `parts` section of your `contrib.yaml` file (or for\nall files if `parts` is not provided), so it can take a long time to run\nif your repo's history is long.  `contrib`'s output shows how many `git\nblame` calls remain and how fast blames are currently completing.\n\n### Cached data\n\n`contrib` caches results of `git blame` in a directory called\n`line-data`.  For large repositories, this can get to be quite large, so\nmake sure you have a decent amount of space available (gigabytes for\nlarge repositories).\n\n## Docker\n\nIf you don't want to worry about installing dependencies, you can\nbuild a local Docker container as follows:\n\n```bash\n$ docker build -t spack/contrib .\n```\n\nThe entrypoint to the container is intended to be run as a GitHub action,\nhowever you can provide the same input arguments via environment\nvariables to achieve the same functionality.\n\n### Entrypoint\n\nBy default, the entrypoint is the [entrypoint.sh](../entrypoint.sh) provided\nin the repository, so it expects environment variables defined with your\ninputs and GitHub token:\n\n```bash\ndocker run -it --env GITHUB_TOKEN=$GITHUB_TOKEN \\\n               --env INPUT_REPO=https://github.com/spack/spack \\\n               --env INPUT_SAMPLES=2 \\\n               --env INPUT_FILE=contrib.yaml \\\n               --env INPUT_FORMAT=pdf \\\n               --env INPUT_AUTHORS=true \\\n               --env INPUT_WORKDIR=examples spack/contrib\n```\n\nHowever you could easily change the entrypoint to interact with contrib\ndirectly:\n\n```bash\ndocker run -it --entrypoint /opt/conda/bin/contrib spack/contrib\n```\n\n### GitHub Actions\n\nIt might be the case that you instead want to run a GitHub action so\nthat the graphic is generated on pull requests, or even as a scheduled task.\nYou can see the [.github/workflows/generate-contrib-graphic.yml](.github/workflows/generate-contrib-graphic.yml)\nthat is set up to run with this repository and basically:\n\n 1. Defines the input files (authors and yaml) to be in the working directory [examples](examples)\n 2. Clones the spack repository\n 3. Runs contrib with all settings set to generate a pdf\n 4. Saves a graphic as output, and caches the line-data folder\n\nThe GitHub action is defined to exist for this repository, meaning that it's metadata\nis defined in [action.yml](action.yml) and built from the included [Dockerfile](Dockerfile)\nthat we've been using. When you want to generate the action for your repository, you\ncan reference it here. See the [examples](#examples) section below for the full example.\nA full table of variables that you can use is provided here:\n\n#### Inputs\n\n| variable name | variable type                                | variable description                                             |\n|---------------|----------------------------------------------|------------------------------------------------------------------|\n| `repo`        | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | A url to clone, if the repository isn't already in workdir       |\n| `samples`     | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Number of commits to sample (default is 2)                      |\n| `workdir`     | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Change to this working directory before clone or execution       |\n| `file`        | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Path to contrib.yaml (default) with configuration and settings   |\n| `format`      | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Format of output file (one of png, svg, jpg, gif, pdf)           |\n| `authors`     | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | If set, update from authors file referenced in config file       |\n| `topn`        | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Number of contributions before collapsing into 'other'           |\n| `verbose`     | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e  | Print verbose output for generation                              |\n\n\n#### Outputs\n\n| variable name | variable type                                       | variable description                                               |\n|---------------|-----------------------------------------------------|--------------------------------------------------------------------|\n| `plot`        | \u003cspan style=\"color:green\"\u003e optional \u003c/span\u003e to use  | the path to the generated output `${{ steps.\u003cstep\u003e.outputs.plot }}`|\n\n\nSee the example above, or the one provided with the repository in [.github/workflows](.github/workflows)\nfor another example. The action above will generate the plot, and it's up to you to decide what to do with it.\nYou might:\n\n - save as an artifact for manual download\n - open a pull request to another repository\n - push directly to a branch\n\n\n#### Example\n\nThe following example will reference just one commit from spack, and generate files called\n`loc-in-packages-by-*.pdf` that we upload as an artifact. We will also print verbose output,\nand using the files in the [examples](examples) folder, generate a graphic. This run takes\nabout 6 minutes for the graphic generation, and a few more for building the container and\nuploading the artifact. Here is an example step that uses the master branch.\n\n```yaml\n  contrib:\n    name: Generate Contribution Graphic\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout Repository\n        uses: actions/checkout@v2\n      - name: Run GitHub Action\n        uses: spack/contrib@master\n        env:\n          token: ${{ secrets.GITHUB_TOKEN }}\n        with:\n \n          # A url to clone, if contrib.yaml \"repo\" doesn't exist in the repository\n          repo: https://github.com/spack/spack\n\n          # number of commit samples, set to 0 for all commits\n          samples: 2\n\n          # Working directory to do the clone, and expect contrib and authors files\n          workdir: examples\n\n          # The contrib.yaml flie with configuration\n          file: contrib.yaml\n\n          # Authors should be set in the file (contrib.yaml)\n          authors: true\n\n          # number of contributions to show before collapse into \"other\"\n          topn: 10\n\n          # format of file to save (pdf, svg, png, jpg, gif)\n          format: pdf\n\n          # Print verbose output (remove for regular)\n          verbose: true\n```\n\nNote that (it's recommended to use a tagged or released version instead of a branch).\n\n\n### Interactive Generation\n\nYou can test, debug, or otherwise interact with contrib in the container\nby shelling inside:\n\n```bash\n$ docker run -it --entrypoint bash spack/contrib\n\n$ which contrib\n/opt/conda/bin/contrib\nroot@941ae1020363:/code# contrib --help\nusage: contrib [-h] [-i] [-v] [-f FILE] [-n TOPN] [-s SAMPLES] [-j JOBS] [-u]\n               [--format {pdf,svg,png,jpg,gif}]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -i, --index           build the commit index and display progress, but do\n                        not plot\n  -v, --verbose         print out each commit as it is processed\n  -f FILE, --file FILE  path to valid contrib.yaml (default './contrib.yaml')\n  -n TOPN, --topn TOPN  number of contributors to show before collapsing into\n                        'other'\n  -s SAMPLES, --samples SAMPLES\n                        number of commits to sample for the chart (0 for all\n                        commits)\n  -j JOBS, --jobs JOBS  number of concurrent blame jobs (default #cpus)\n  -u, --update-org-map  update or create an author-to-organization mapping\n  --format {pdf,svg,png,jpg,gif}\n                        format for images (default pdf)\n```\n\nLet's (starting at the /code working directory) define some environment variables.\nYou can generate a [personal access token](https://github.com/settings/tokens) for the GitHub\ntoken.\n\n```bash\nexport GITHUB_TOKEN=mysecrettoken\nexport INPUT_WORKDIR=examples\nexport INPUT_REPO=https://github.com/spack/spack\nexport INPUT_SAMPLES=2\nexport INPUT_FILE=contrib.yaml\nexport INPUT_FORMAT=png\nexport INPUT_TOPN=50\nexport INPUT_AUTHORS=true\n```\n\nWe can then run the entrypoint to show the verbose output:\n\n```bash\n./entrypoint.sh\n```\n\nAgain, this is what would be run if we ran the container from our host and provided\nthese environment variables.\n\n## Related projects\n\nIf you like `contrib`, you may be interested in the projects below.\n`contrib` does some very specific things we wanted for Spack; these\nsystems can provide much more sophisticated metrics:\n\n* Augur (https://github.com/chaoss/augur)\n* Labours (https://pypi.org/project/labours/), purportedly much faster\n  than `git-of-theseus`\n* `git-of-theseus` (https://github.com/erikbern/git-of-theseus)\n\n## License\n\nContrib is part of the Spack project. Spack is distributed under the\nterms of both the MIT license and the Apache License (Version 2.0). Users\nmay choose either license, at their option.\n\nAll new contributions must be made under both the MIT and Apache-2.0\nlicenses.\n\nSee [LICENSE-MIT](https://github.com/spack/contrib/blob/master/LICENSE-MIT),\n[LICENSE-APACHE](https://github.com/spack/contrib/blob/master/LICENSE-APACHE),\n[COPYRIGHT](https://github.com/spack/contrib/blob/master/COPYRIGHT), and\n[NOTICE](https://github.com/spack/contrib/blob/master/NOTICE) for details.\n\nSPDX-License-Identifier: (Apache-2.0 OR MIT)\n\nLLNL-CODE-647188\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspack%2Fcontrib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspack%2Fcontrib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspack%2Fcontrib/lists"}