Generate simple markdown changelogs for GitHub repositories written in Python.
This package does two things:
Given a GitHub org, repository, an initial git reference or date, use the GitHub GraphQL API to return a DataFrame of all issue and PR activity for this time period.
A CLI to render this activity as markdown, suitable for generating changelogs or community updates.
This is a really young tool so it might change a bit over time.
The easiest way to install this package is to do so directly from GitHub with
pip install github-activity
Generate a markdown changelog#
The easiest way to use
github-activity to generate activity markdown is to use
the command-line interface. It takes the following form:
github-activity [<org>/<repo>] --since <date or ref> --until <date or ref>
[<org>/<repo>] argument is optional.
If you do not give it, then
github-activity will attempt to infer this value by running
git remote -v and using either
upstream if both are available).
The (optional) arguments in
-u) can either be
a date, or a ref (such as a commit hash or tag).
github-activity will pull the activity
between the dates corresponding to these values.
Here’s an example on the jupyter notebook repository, grabbing all activity since the latest major release and outputting it to a markdown file.
github-activity jupyter/notebook -s 6.0.0 -u 6.0.1 -o sample_notebook_activity.md
You can find the resulting markdown here.
For repositories that use multiple branches, it may be necessary to filter PRs by a branch name. This can be done using the
--branch parameter in the CLI. Other git references can be used as well in place of a branch name.
Using a GitHub API token#
github-activity uses the GitHub API to pull information about a repository’s activity.
You will quickly hit your API limit unless you use a personal access token. Here are
instructions to generate and use a GitHub access token for use with
Create your own access token. Go to the new GitHub access token page and follow the instructions. Note that while working with a public repository, you don’t need to set any scopes on the token you create.
github-activityfrom the command line, use the
--authparameter and pass in your access token. This is easiest if you set it as an environment variable, such as
MY_ACCESS_TOKEN. You can then add it to your call like so:
github-activity jupyter/notebook --since v2019-09-01 --auth $MY_ACCESS_TOKEN
If you do not explicitly pass an access token to
github-activity, it will search for an environment variable called
GITHUB_ACCESS_TOKEN. If it finds this variable, it will use this in the API calls to GitHub.
How does this tool define contributions in the reports?#
GitHub Activity tries to automatically determine the unique list of contributors within a given window of time. There are many ways to define this, and there isn’t necessarily a “correct” method out there.
We try to balance the two extremes of “anybody who shows up is recognized as contributing” and “nobody is recognized as contributing”. We’ve chosen a few rules that try to reflect sustained engagement in issues/PRs, or contributions in the form of help in others’ issues or contributing code.
Here are the rules we follow for finding a list of contributors within a time window. A contributor is anyone who has:
Had their PR merged in that window
Commented on >= 2 issues that weren’t theirs
Commented >= 6 times on any one issue
We’d love feedback on whether this is a good set of rules to use.