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 ../styleguide/jax-conversion.

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