dinghy 1.2.0

Dinghy daily digest tool

Dinghy, a GitHub activity digest tool.

Dinghy uses the GitHub GraphQL API to find recent activity on releases, issues and pull requests, and writes a compact HTML digest like this.

Getting Started

1. Install dinghy:

   $ python -m pip install dinghy

2. To run dinghy you will need a GitHub personal access token. The scopes you need to assign to it depend on what repos you’ll be accessing. If you are only accessing public repos, then you don’t need any scopes. If you will be accessing any private repos, then you need the “repo” scope. Create a token and define the GITHUB_TOKEN environment variable with the value:

   $ export GITHUB_TOKEN=ghp_Y2oxDn9gHJ3W2NcQeyJsrMOez

3. Then run dinghy with a GitHub URL:

   $ dinghy https://github.com/Me/MyProject
   Wrote digest: digest.html

   You will have a digest of the repo’s last week of activity in digest.html. It will look something like this.

   You can also write a YAML configuration file to digest multiple sources, or with different time periods:

   $ dinghy my-dinghy-config.yaml
   Wrote digest: proj1.html
   Wrote digest: proj2-daily.html
   Wrote digest: proj2-weekly.html

   Extra arguments specify which digests to write:

   $ dinghy my-dinghy-config.yaml proj1.html
   Wrote digest: proj1.html

Configuration

Dinghy configuration is read from a YAML file (dinghy.yaml by default). Here’s an example:

digests:
  - digest: lastweek.html
    title: My projects last week
    since: 1 week
    items:
      - https://github.com/orgs/myorg/projects/17
      - https://github.com/orgs/anotherorg/projects/8
      - https://github.com/myorg/myrepo/pulls

  - digest: hotnews.html
    title: Today's news
    since: 1 day
    items:
      - url: https://github.com/orgs/anotherorg/projects/8
        home_repo: anotherorg/wg
      - https://github.com/myorg/churnchurn/issues

  - digest: all_prs.html
    since: 1 day
    items:
      - search: org:myorg is:pr
        title: MyOrg pull requests

defaults:
  ignore_users:
    - app-user
    - fake-bot

The digests clause is a list of digests to produce. The defaults clause sets defaults for the digest options in the rest of the file. Each digests clause specifies what to digest:

• The digest setting is the HTML digest file to write.

• The since setting indicates how far back to look for activity. It can use units of weeks, days, hours, minutes and seconds, and can also be abbreviated, like 1d6h. Using since: forever will include all activity regardless of when it happened. If since is omitted, it defaults to one week.

• The items setting is a list of things to report on, specified in a few different ways:

  • The url setting is a GitHub URL, in a number of forms:

    • An organization project URL will report on the issues and pull requests in the project. Your GitHub token will need the “read:project” scope.

    • A URL to a repo will report on the issues, pull requests and releases in the repo.

    • A URL to a repo’s issues will report on the issues in the repo.

    • A URL to a repo’s pull requests will report on the pull requests in the repo.

    • A URL to a repo’s releases will report on the releases in the repo.

    • Any of these URLs can point to a GitHub Enterprise installation instead of https://github.com.

  • The search setting can specify a GitHub search query to find issues or pull requests. The query will have an updated: term added to it to account for the since: setting.

  • If an item only needs to specify a GitHub URL, then it can simply be the URL string.

• The optional title setting will be used to construct the title and main header of the HTML page.

• The template setting is the name of a Jinja2 template file to use to produce the digest. It defaults to “digest.html.j2”, which is packaged with dinghy. The data passed to the template is under-specified; if you want to write a template of your own, model it on the built-in digest.html.j2.

• For GitHub Enterprise, you can specify api_root, which is the URL to build on for GraphQL API requests. It defaults to “https://api.github.com/graphql”.

Items can have additional options:

• By default, no activity is reported for bot users. If you want to include them, use include_bots: true.

• Some applications perform actions using real user accounts, but you’d like to ignore them anyway. You can list those user names that should be ignored in the ignore_users setting.

• Digests can have an explicit title set with the title setting.

• Options for organization projects include:

  • home_repo is the owner/repo of the repo in which most issues will be created. Issues in other repos will have the repo indicated in the digest.

Daily Publishing

The sample digest is published daily using a GitHub Action from its own repo: nedbat/dinghy_sample. You can use it as a starting point for your own publishing.

Changelog

Unreleased

See the fragment files in the scriv.d directory.

1.2.0 — 2023-01-27

Added

• Now you can additionally specify digests on the command line to write, which will choose just those digests from the configuration file.

Fixed

• If the config file has no digests: clause, it could be because it’s not a dinghy config file at all, so print an error message about it.

1.1.0 — 2023-01-25

Added

• A digest can specify template, a Jinja2 template file to produce the digest. This opens the possibility for other output formats than HTML.

1.0.0 — 2022-12-03

• Nothing has changed, just decided Dinghy was stable enough to call 1.0.0.

0.15.0 — 2022-11-09

Added

• Show releases in the digest. Thanks, Simon de Vlieger.

• A new setting include_bots: true will include pull requests, issues, or comments created by bot users. The default remains False, to exclude them. Closes issue 25.

0.14.0 — 2022-10-25

Added

• Now a CLI command is registered so you can use dinghy as a command instead of python -m dinghy (though that still works).

• You can now specify since: forever to include all activity regardless of when it happened.

Changed

• Search results now always show the repo containing the item.

Fixed

• Comments by deleted GitHub users would cause a crash. This is now fixed (issue 23).

0.13.4 — 2022-10-06

Fixed

• Comments on pull requests were only filtered by their age, not their authors, so bot comments, and comments by “ignored users” were still included. This is now fixed.

0.13.3 — 2022-09-29

Fixed

• The hover tip for icons on pull requests and issues has text in the same order as the icons, making them easier to understand.

0.13.2 — 2022-08-13

Fixed

• Add an HTML <meta> tag to ensure content is properly decoded as UTF-8. Fixes issue 12. Thanks, Bill Mill.

0.13.1 — 2022-08-03

Fixed

• On Windows, an alarming but harmless error would appear when finishing. This is now fixed, closing issue 9. Thanks, Carlton Gibson.

0.13.0 — 2022-07-29

Removed

• Removed the deprecated “pull_requests” setting.

Added

• The api_root setting lets GitHub Enterprise users control the GraphQL endpoint to use.

Changed

• Adapt to the 2022-06-23 GitHub issues update, using the ProjectsV2 API instead of the ProjectsNext API.

0.12.0 — 2022-06-12

Added

• The title option can be used on individual digests to add text to the title of the report. Thanks, Doug Hellmann.

0.11.5 — 2022-06-07

Fixed

• Closed issues now distinguish between “completed” and “not planned”.

0.11.4 — 2022-05-10

Added

• HTML escaping is applied to the text pulled from GitHub (oops!)

• Emojis are displayed as emojis rather than as text.

0.11.3 — 2022-05-06

Fixed

• GitHub sometimes responds with “502 Bad Gateway”. Pause and retry if that happens.

0.11.2 — 2022-04-12

Added

• Added a --version option.

Fixed

• Pull requests with many reviews would skip some reviews. Now all pull request data is fully retrieved.

• On large digests, GitHub sometimes returns 403 as a rate limit. Retry when this happens to finish the queries.

0.11.1 — 2022-03-29

Fixed

• Corrected a packaging mistake (missing Changelog entry).

0.11.0 — 2022-03-29

Added

• Resolved comments are now indicated with a checkbox icon, and hover text of “resolved comment”.

Fixed

• Fixed a crash trying to get the repository for an issue in a project.

0.10.0 — 2022-03-28

Changed

• Pull request data was not properly displayed: comments weren’t included in the digest that should have been.

• Pull request comments older than the cutoff date will be included if they are needed to show the discussion threads of newer comments. The old comments are shown in gray to help stay focused on recent activity.

• Parsing of time durations was made stricter, so that “1 month” isn’t mistaken for “1 minute”. Fixes issue 7

Removed

• Oops, it turns out there’s no such thing as a repo project for “Projects (beta)”. That thing that wouldn’t have worked has been removed.

0.9.0 — 2022-03-17

Added

• GitHub enterprise support: you can use URLs pointing to your own GitHub Enterprise installation. Only a single host can be used. Thanks, Henry Gessau.

• A “search:” entry in the configuration file will find issues or pull requests matching the query.

• Items in the configuration file can have title: to set an explicit title.

Deprecated

• The pull_requests: configuration setting is deprecated in favor of search:. pull_requests: org:my_org becomes search: org:my_org is:pr.

0.8.0 — 2022-03-16

Added

• Repo projects are supported.

Fixed

• Error handling failed on certain errors. This is now fixed, closing issue 4.

0.7.1 — 2022-03-13

Fixed

• Better handling of authorization problems, with error message presented so that the user can fix them.

0.7.0 — 2022-03-12

Added

• The command line now accepts a GitHub URL to quickly get a week’s digest of activity from a repo (or issues, pull requests, etc).

• The logging level can now be specified with the -v/--verbosity command-line option.

Fixed

• Dependencies now have minimum pins, fixing issue 1.

0.6.0 — 2022-03-10

Added

• GitHub’s @ghost user shows up in GraphQL results as an “author” of None. Properly handle that case.

Fixed

• Fixes to the color of labels.

• Correct handling of HTML in bodies.

0.5.2 — 2022-03-08

Changed

• More HTML tweaks to indentation and information.

0.5.1 — 2022-03-07

Changed

• Indentation tweaks to make thread structure clearer.

0.5.0 — 2022-03-03

Changed

• Pull request reviews are displayed more compactly.

0.4.0 — 2022-02-28

Added

• A repo URL will report on both pull requests and issues in the repo.

0.3.0 — 2022-02-27

Added

• The configuration file can be specified as the argument on the command line.

• GitHub icons decorate pull requests, issues, and comments to distinguish them and indicate their status.

Changed

• The configuration file syntax changed. Now there is a top-level digests clause and an optional defaults clause.

• The bots setting is now called ignore_users.

• Pull request review threads are presented hierarchically.

0.2.0 — 2022-02-21

Added

• Items can have options. Organization projects have a home_repo option so that issues from other repos will get an indication of the other repo.

• Organizatons can be searched for pull requests.

• If dinghy hits a GraphQL API rate limit, it will sleep until the limit is reset.

• Don’t report on activity by bot users. The bot setting can be used to list user accounts that should be considered bots.

0.1.0 — 2022-02-19

• First release.