Simple markdown changelogs for GitHub repositories

executablebooks, updated 🕥 2023-03-06 17:42:32


Generate simple markdown changelogs for GitHub repositories written in Python.

This package does two things:

  1. 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.
  2. A CLI to render this activity as markdown, suitable for generating changelogs or community updates.

Note: This is a really young tool so it might change a bit over time.


The easiest way to install this package is via pip:

pip install github-activity


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>

See the github-activity documentation for more information.

To run the tests

The easiest way to run the test suite is using nox. This will install the local version of the package and run the test suite.

nox -s test


Overhaul documentation and add contributing guide

opened on 2023-03-01 15:37:27 by choldgraf

This makes major updates to our documentation to add more information for contributors, and to make it easier to parse.

  • Adds a GitHub action that is dedicated to publishing to PyPI rather than being nested in tests.yml
  • Documents how to make a release
  • Adds a dedicated contributing and usage guide: closes #85
  • Adds a changelog
  • Makes a few other quality of life improvements here and there

I'll get the tests passing, but wanted to get this up to confirm that @blink1073 and @minrk think this would be a useful addition to help others get started!

Improve the docs and add contributing guide

opened on 2023-03-01 13:35:17 by choldgraf

Our documentation is fairly sparse, mostly fitting on a single page. However, now more people are contributing to it, and I think it's worth fleshing out this information more so that it's easier for others to learn how to use and contribute to this package.

I'll try to give this a shot relatively soon as I think I have the most context for how everything is set up!

ability to exclude backported PRs

opened on 2023-02-27 09:59:37 by minrk


In several of our projects, we backport fixes to a previous release while working on a major release in main - it would be useful to be able to exclude the backported PR so the change doesn't appear twice or give the misleading indication that a feature or bugfix originally made on the development branch for 4.0 was not also released in e.g. 3.1.

For example, in making the changelog for JupyterHub 4.0, I get in the enhancements:

when none of these should be included as changes in 4.0.

so each backported change is present twice, when what I want is for none of these 4 entries. (-b main excludes the backports, but I currently like to include them because it helps with the manual deletions of the duplicates!)


A simple version would be to allow excluding on a specific label (or label pattern). Doing this by default might present problems, because the exclusions might be the opposite of what you want for the backport release. If you use backport-pr tools like mrmeeseeks (or manual backporting with a separate PR), though, this shouldn't be an issue because the change already appears twice as two separate PRs, and only the 'mainline' PR should be excluded, which would be the one with the label.

Tasks and updates

  • [ ] decide how to identify backport prs
  • [ ] decide what to do by default
  • [ ] implement exclusions (and options, if any)

Split into multiple requests when total number of items is > 1000

opened on 2023-01-02 12:37:02 by choldgraf


GitHub's GraphQL API will restrict any calls to 1000 total nodes. This means that a really large query (e.g. all of the history of a project) will be cut off at 1000 items.


To get around this, we could detect when a query has > 1000 nodes, and split up the call to fetch the data into multiple queries. This is similar to how our "pagination" works, but would be across queries rather than pages of the same query. We might be able to use dates for this as an easy first step.

Incorrect inclusion of a PR with a git tagged merge commit

opened on 2022-11-14 13:58:38 by consideRatio

I ended up observing a PR included in the changelog, even though it was part of the previous tagged release. To reproduce this, one can do...

github-activity --since v3.0.5 --target jupyterhub/action-k3s-helm

I would expect that PR 73 should not have been written out to the changelog.

* 76875ff - Merge pull request #74 from manics/ (3 months ago) <Erik Sundell> |\ | * c657404 - Add (3 months ago) <Simon Li> |/ * d3c165a - (tag: v3.0.5) Merge pull request #73 from manics/calico-3.24 (3 months ago) <Simon Li> |\ | * e74b367 - Changelog for v3.0.5 - 2022-08-21 (3 months ago) <Simon Li> | * 9b2415e - Update component versions in README (3 months ago) <Simon Li> | * 903f39c - Calico 3.24.0 (3 months ago) <Simon Li> |/


[email protected]{2022-11-14}

(full changelog)

Bugs fixed

  • Calico 3.24.0 (3.23 manifest URL is broken) #73 (@manics)

... ```

A motivation to think of this as a bug is that the comparison we link to, will not include the changes part of the commit that was most recently tagged.

Time for 1.0.0?

opened on 2022-10-17 10:27:43 by consideRatio

I see great value in the ability to communicate changes via the version numbers according to a semver2 practice, but that is very hard to do when stuck at 0.x.y as there is no clear practice for that situation.

What do you think about going for 1.0.0 as next release, or next non-patch release?


v0.3.0 2023-02-13 15:36:04

What's Changed

  • [ENH] Add a bootstrap function for all changelog entries by @blink1073 in
  • Add ability to use GH CLI Authentication by @choldgraf in
  • MAINT: Add check for installed gh cli by @choldgraf in
  • BUG: import dateutil.parser by @agoose77 in

New Contributors

  • @agoose77 made their first contribution in

Full Changelog:

v0.2.0 2021-12-01 19:05:32

(Full Changelog)

Enhancements made

Bugs fixed

  • Write status messages to sys.stderr #47 (@minrk)

Maintenance and upkeep improvements

Contributors to this release

(GitHub contributors page for this release)

@blink1073 | @choldgraf | @consideRatio | @manics | @minrk | @welcome

v0.1.3 2021-02-20 21:14:29


(full changelog)

New features added

  • ✨NEW: heading_level argument for increasing heading level #38 (@minrk)

Enhancements made

  • �IMPROVE: add blank lines below headings #36 (@minrk)
  • � IMPROVE: since/until: assume git reference, fallback to datetime #33 (@consideRatio)

Bugs fixed

Documentation improvements

Other merged PRs

Contributors to this release

(GitHub contributors page for this release)

@choldgraf | @consideRatio | @minrk | @welcome

v0.1.2 2020-08-31 16:43:12

Add MANIFEST, to include files in distribution

v0.1.1 2020-08-07 19:02:27

Executable Books

An open collaboration to create executable books with Jupyter

GitHub Repository Homepage