GitHub Pull Requests

This page documents the QuantEcon conventions when submitting a pull request via GitHub

Before you open one

It’s worth a quick look for work already in flight on the same files.

gh pr list --state open                   # scan the open list
gh pr diff <number> --name-only           # what files does that PR touch?

If something is already open, prefer building on it — review it, push a commit to the branch, or comment with what you’d change. Opening a parallel PR means two people solving the same problem and someone’s work being discarded at merge time.

Sometimes a fresh branch really is simpler — when the changes have grown well beyond the original, for instance. That’s fine. In that case, say so on the original PR, credit the author with a Co-Authored-By trailer, and close it with a pointer to the replacement.

Tip

The same applies in reverse. If a PR of yours is superseded, the work still counted — it usually shaped whatever replaced it.

Sweeping changes

A related case: you notice a convention that’s now documented in this manual — a naming rule, an updated API — and could apply it across many files at once.

See also

The style guide is where these conventions land — see Writing conventions, Code and JAX.

Before opening that PR, consider whether the fix will simply arrive on its own. Lectures under active revision will pick up the convention as they’re rewritten, so a sweep across them mostly creates merge conflicts for work already underway.

A reasonable middle path:

• Apply the sweep to files nobody is currently working on, where the convention would otherwise take a long time to arrive.

• Leave the rest to the PRs already in flight, and mention in your description which files you skipped and why.

Note

This is a preference, not a rule. A cross-cutting cleanup is sometimes exactly what’s needed — just check the open PRs first so the decision is a deliberate one.

Setup

When setting up a pull request always fill in the top level comment box with a detailed description of what the pull request does.

If the PR requires multiple tasks, please use checkboxes.

Tip

These checkboxes provides a progress indicator and clearly identifies the PR as in-work if all checkboxes haven’t been addressed.

If relevant, always link a pull request with any related issues.

Important

If you are confident the PR addresses all aspects of an Issue then please use fixes #{number} in the top level comment box.

This will close the Issue when the PR is merged.

Use GitHub features

When opening a Pull Request, unless the PR is ready for review, please mark it as DRAFT.

To mark a PR as DRAFT you need to use the drop down option when opening the PR.

this clearly identifies a PR as in-work and not ready for review.

and this is clearly shown in the title of the PR

Once a PR is ready, then please use the “Ready for review” button.

Note

There is a tag ready, this tag will be used to identify PRs that have been reviewed, approved, and are ready for final review and/or will be merged