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.

What to do after changing a public API#

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