Adding or Changing Public APIs

We don’t want to thrash users, so we want to be careful about changing and adding public APIs.

What counts as a public API

  • Anything that’s importable via from dagster import
  • Anything that’s importable via from dagster-<subpackage> import
  • The Dagster command-line interface.

What to do before changing, deprecating, or adding a public API

  • Make an issue in Github describing the change. Some things that are helpful to include:
    • Usage examples, compared with previous state.
    • A rationale for the change.
    • A rollout timeline, including deprecation, if applicable.
  • Post a link to the issue in the #proposed-api-changes channel.
  • If adding an API, consider marking it “experimental”, which means it can change in point releases without warning.
  • If not experimental, get sign-off from Nick.

What to do after changing a public API

  • Update CHANGES.md
    • Make sure to include the rationale for the change.