whatsup_github

This tool helps updating data for What's New section on the public Adobe Commerce technical documentation resources. It filters GitHub pull requests and generates a data file. One pull request sources one data entity. All filtering parameters are set in a configuration file, except dates. Since date is set as a CLI argument and the till date is always the moment when the command is run.

CLI

Commands:
  whatsup_github help [COMMAND]  # Describe available commands or one specific command
  whatsup_github since DATE      # Filters pull requests since the specified date till now. Default: last 7 days.
  whatsup_github version         # Current version of the gem

Usage:
  whatsup_github since DATE

Options:
  [--config=CONFIG]  # Relative path to the configuration file.
                     # Default: .whatsup.yml

What's generated

Output is controlled by output_format in .whatsup.yml, which accepts one or more of:

yaml — writes tmp/whats-new.yml.
markdown — writes headerless Markdown table rows to tmp/whats-new-on-devdocs.md with description, versions, type, and date (YYYY-MM-DD). With no matching pull requests, the file is empty.
custom — renders rows through a project-supplied Mustache template.

output_format:
  - yaml
  - custom
templates:
  custom: path/to/your-template.mustache
custom_output: tmp/whats-new-custom.txt

For custom, templates.custom must point to a file inside the project directory (relative to where whatsup_github is run), and custom_output sets the destination path. The template receives {{#rows}}, each with description, versions, type, date, link, merge_commit, contributor, and labels.

The fields below describe each row, as produced for the yaml and custom formats.

`description`

Text for description is taken from individual pull request's description (same as body). The text must follow the whatsnew keyword and be located at the end.

Example:

This pull request adds ...

Some other details about this pull request.

whatsnew
Added documentation about [New Magento feature](https://devdocs.magento.com/new-magento-feature.html).

`type`

Set as a list of labels in .whatsup.yml. There are two types of labels in configuration:

required are labels that must include whatsnew. Otherwise, resulting output will warn about missing whatsnew.
optional are labels that may include whatsnew. If whatsnew is missing, you won't get any notification about this.

`versions`

Generated from pull request labels that begin with one or more digits followed by a period, matching \A\d+\.. Examples: 2.3.x, 1.0.3-msi, 2.x, 12.4.

Matching labels are kept unchanged and joined with a comma and a space in their original order. For example, labels whatsnew, 2.4, and 12.4 produce 2.4, 12.4. If no labels match, versions is an empty string.

`date`

Date when the pull request was merged.

`link`

URL of the pull request. For repos with the enterprise: prefix, the link is formatted as enterprise:<org>/<repo>/pull/<number> to avoid exposing the internal hostname.

`contributor`

An author of a pull request.

`merge_commit`

Merge commit SHA of the pull request.

`labels`

All labels added to the pull request.

Installation

This gem can be installed as a system command-line tool or as a command-line tool available in a project.

System installation

gem install whatsup_github

Project installation

Add to your Gemfile:

gem 'whatsup_github'

And install:

bundle

Configuration

The default configuration file .whatsup.yml will be created automatically after first run unless it's already there.

To use non-default location or name of the file, use the --config option. Example:

whatsup_github since 'apr 9' --config 'configs/whatsup_bp.yml'

Authentication

Authentication is checked in this order: environment variables → .env file → ~/.netrc → guest (rate-limited).

With a .env file

Create a .env file in the directory where you run whatsup_github. See .env.example for the format.

WHATSUP_GITHUB_ACCESS_TOKEN=<public-github-token>
WHATSUP_GITHUB_ENTERPRISE_HOSTNAME=<enterprise-hostname>
WHATSUP_ENTERPRISE_ACCESS_TOKEN=<enterprise-github-token>

With environment variables

WHATSUP_GITHUB_ACCESS_TOKEN=askk494nmfodic68mk whatsup_github since 'apr 2'

WHATSUP_GITHUB_ENTERPRISE_HOSTNAME sets the hostname for GitHub Enterprise Server (e.g. git.example.com). Optional for GHEC — defaults to github.com.

WHATSUP_ENTERPRISE_ACCESS_TOKEN is used for repos prefixed with enterprise: in .whatsup.yml. Useful when you need two separate accounts — for example, a public GitHub account and a GHEC org account.

With the .netrc file

Use ~/.netrc for authentication. See .netrc.example for the format.

machine api.github.com
  login <github-username>
  password <personal-access-token>

For GitHub Enterprise Server (self-hosted), add a second entry using the server hostname:

machine git.enterprise.example.com
  login <enterprise-username>
  password <enterprise-personal-access-token>

Note: .netrc only supports one entry per host. If you need two different accounts on api.github.com (e.g., public GitHub + GHEC), use .env or environment variables instead.

Usage

whatsup_github since 'apr 2'

To use the default date range of the past 7 days, omit the date:

whatsup_github since

You can use different date formats like 'April 2', '2 April', 'apr 2', '2 Apr', 2018-04-02.

Development

To install dependencies:

bin/setup

To install the package:

rake install

You can also run bin/console for an interactive prompt that will allow you to experiment.

Testing

The project contains RSpec unit and CLI integration tests in spec.

To run all tests, including offline replay of recorded GitHub API interactions:

bundle exec rake

In-process specs disable real network access (WebMock) and generate a SimpleCov coverage report at coverage/index.html. Subprocess tests exercise executable startup and configuration rejection without making API requests.

To run only CLI integration tests:

bundle exec rspec spec/whatsup_github/cli_integration_spec.rb

Integration tests create their own configuration and output files in temporary directories. The recorded API test uses VCR with a cassette under spec/fixtures/cassettes/. Recording is disabled by default, so it runs without live network access. The existing cassette contains an empty search result; it verifies API replay and empty YAML output, not rendering of non-empty pull request data. Run it separately with:

bundle exec rspec spec/whatsup_github/cli_integration_spec.rb --example 'recorded GitHub API interactions'

To re-record a cassette, delete the corresponding file under spec/fixtures/cassettes/, export a valid WHATSUP_GITHUB_ACCESS_TOKEN before starting RSpec, and temporarily switch the record mode from :none to :once in spec/whatsup_github/cli_integration_spec.rb. Run the command above, then restore :none and review the cassette for sensitive data before committing it.

Individual files

Individual files can have tests at the end of a file in a format like:

if $PROGRAM_NAME == __FILE__
  # test code here
end

To run such test, run the corresponding file:

ruby lib/whatsup_github/config_reader.rb

The tests use the root .whatsup.yml file to read configuration.

Local testing against live GitHub data

The tool makes live GitHub API calls, so end-to-end local testing requires real credentials and a real repository.

Set up credentials

Copy .env.example to .env and fill in your tokens:

cp .env.example .env

Use a narrow date range

A short window keeps the result set small and avoids burning API rate limits:

bundle exec whatsup_github since 'yesterday'

Check the output

Results are written to tmp/whats-new.yml. The tmp/ directory is gitignored, so test output won't be accidentally committed.

Debug search queries

To inspect the exact GitHub search queries being sent, run with DEBUG=1:

DEBUG=1 bundle exec whatsup_github since 'yesterday'

Contributing

Bug reports and pull requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
exe		exe
lib		lib
spec		spec
.env.example		.env.example
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.netrc.example		.netrc.example
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
.simplecov		.simplecov
CHANGELOG.md		CHANGELOG.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE.txt		LICENSE.txt
README.md		README.md
Rakefile		Rakefile
whatsup_github.gemspec		whatsup_github.gemspec

Navigation Menu

Repository files navigation

whatsup_github

CLI

What's generated

`description`

`type`

`versions`

`date`

`link`

`contributor`

`merge_commit`

`labels`

Installation

System installation

Project installation

Configuration

Authentication

With a .env file

With environment variables

With the .netrc file

Usage

Development

Testing

Individual files

Local testing against live GitHub data

Set up credentials

Use a narrow date range

Check the output

Debug search queries

Contributing

License

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

whatsup_github

CLI

What's generated

description

type

versions

date

link

contributor

merge_commit

labels

Installation

System installation

Project installation

Configuration

Authentication

With a .env file

With environment variables

With the .netrc file

Usage

Development

Testing

Individual files

Local testing against live GitHub data

Set up credentials

Use a narrow date range

Check the output

Debug search queries

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

`description`

`type`

`versions`

`date`

`link`

`contributor`

`merge_commit`

`labels`