README: About pyOpenSci peer review metrics

Data flow (high level)

This Quarto site charts peer-review and contributor metrics. Collector scripts in scripts/ write checked-in CSVs under data/; .qmd pages read those CSVs. pyosMeta is the shared library for GitHub review parsing and for reading website YAML that pyosMeta itself publishes to pyopensci.github.io (contributors.yml, packages.yml, editorial board YAML).

flowchart LR
  subgraph sources [Sources]
    ghTeams[GitHub org teams]
    ghReviews[software-submission issues]
    ghApi[GitHub API activity]
  end

  subgraph pyosMetaPkg [pyosMeta]
    updateBoard[update-editorial-board]
    parseReviews[ProcessIssues and GitHubAPI]
  end

  subgraph website [pyopensci.github.io data]
    boardYml[editorial-board.yml]
    emeritusYml[emeritus-editors.yml]
    manualYml[manual-editorial-roster.yml]
    contribYml[contributors.yml]
    pkgYml[packages.yml]
  end

  subgraph metricsRepo [metrics repo]
    scripts[collector scripts]
    csvs[data CSVs]
    qmd[Quarto dashboards]
  end

  ghTeams --> updateBoard --> boardYml
  updateBoard --> emeritusYml
  updateBoard --> contribYml
  manualYml --> updateBoard
  ghReviews --> parseReviews
  parseReviews --> contribYml
  parseReviews --> pkgYml

  boardYml --> scripts
  emeritusYml --> scripts
  manualYml --> scripts
  contribYml --> scripts
  pkgYml --> scripts
  ghReviews --> scripts
  ghApi --> scripts
  parseReviews --> scripts

  scripts --> csvs --> qmd

Editorial membership — website board YAML plus manual-editorial-roster.yml; metrics merges those usernames with local domain columns in get-editors.py.
Reviews / packages / contributors — pyosMeta helpers and/or website YAML via open_yml_file.
Sprint / PR activity — GitHub API (and Projects for sprint data) from metrics scripts, sometimes via pyosMeta GitHubAPI.

How to Contribute

1. Fork and Clone the Repo:

To begin, fork this repository to your GitHub account. Then, clone it locally to work on a branch from your computer.

2. Create your GitHub token

The code in this repository uses the GitHub REST API. To ensure that you can access and make requests to the API, you will need to create a token in your GitHUb account.

Through the pyOpenSci pyosMeta package. This package was created to parse through pyOpenSci software review issues, and obtain both contributor and package metadata. To use this package, you need to supply a GitHub access token. This token can be created from your personal GitHub account.

NOTE: You do not need special access to the pyOpenSci organization for this workflow because all of our repositories are public!

Create your token

In GitHub, click on your profile image and navigate to "Settings", and then "Developer Settings".

Create a new fine-grained personal access token, adding a name, expiration, description, and ensure the "Repository Access" is set to "Public Repositories (read-only)". No other configuration needed. At the bottom of the page, click "Generate token".

3. Store token information in an `.env` file

Copy the .env-default file in this repository and rename it to .env. You will paste your GitHub token value that you created above into this file.

Copy the token string and paste it into the .env file next to GITHUB_TOKEN=. It should look something like this

GITHUB_TOKEN=yourtokenvaluehere

You are now setup to process pyOpenSci peer review and contributor metadata using pyosMeta.

Set up the Python environment with uv

This repo uses uv and pyproject.toml for dependencies (see also uv.lock).

Install uv once, then from the repo root:

uv sync

That creates .venv/ and installs project deps plus the dev group (nox, quarto-cli).

Run data scripts

uv run python scripts/get-review-contributors.py
uv run python scripts/get-prs.py
# …same pattern for other scripts in scripts/

Permissions

Please note that the scripts/get-sprint-data.py requires your GitHub token to have elevated permissions, specifically with project access.

When running on GitHub Actions, the elevated permissions are handled by the PROJECTS_READ secret which is a GitHub Token with project access that is available across the pyopensci GitHub organization. We only need these elevated permissions for the scripts/get-sprint-data.py script (at this time), and the rest of the scripts use the default GITHUB_TOKEN so that they can execute as a part of the CI checks for any pull requests coming from forks.

Build the website using Nox

With the uv env in place (or with uv on your PATH), you can use nox to build the site. Nox sessions call uv sync and uv run quarto ….

Install nox if you want to invoke it directly (it is also installed via uv sync in the dev group):

pipx install nox
# or:
uv run nox -s html

Build a static html website

nox -s html

Build a live local server dashboard

nox -s serve

On a Mac you can use ctrl + d to stop a live server.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_kaiyamag 💻 👀	_{Elise Hinman} 💻 👀	_{Santiago Soler} 💻 👀	_{Franklin Koch} 💻 👀	_{Angus Hollands} 💻 👀	_{Alex Batisse} 💻 👀	_{Carol Willing} 💻 👀
_{Bane Sullivan} 💻 👀	_{Leah Wasser} 💻 👀	_{Camille Latapie} 👀 💻	_rogerb121 💻 👀	_steven 💻 👀	_{Carter Lee Rhea} 💻 👀	_{Abby Mitchell} 💻 👀