Skip to main content

Pull Request Handbook

Pull Request Title Convention

When creating a pull request follow the naming conventions depending on the change being made. In general the pull request title starts with an emoji with the connector you're doing the changes, eg (✨ Source E-Commerce: add new stream Users). Airbyte uses this pattern to automatically assign team reviews and build the product release notes.

Pull Request TypeEmojiExamples
New Connector (Source or Destination)🎉🎉 New Destination: Database
Add a feature to an existing connector✨ Source E-Commerce: add new stream Users
Fix a bug🐛🐛 Source E-Commerce: fix start date parameter in spec
Documentation (updates or new entries)📝📝 Fix Database connector changelog
It's a breaking change🚨🚨🚨🐛 Source Kafka: fix a complex bug

For more information about breaking changes. A maintainer will help and instruct about possible breaking changes.

Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis.

If you're code change is doing more than one change type at once we strongly recommend to break into multiple pull requests. It helps us to review and merge your contribution.

Descriptions

Context: Provide enough information (or a link to enough information) in the description so team members with no context can understand what the issue or PR is trying to accomplish. This usually means you should include two things:

  1. Some background information motivating the problem

  2. A description of the problem itself

  3. Good places to start reading and file changes that can be skipped

    Some examples:

insufficient context: Create an OpenAPI to JSON schema generator. Unclear what the value or problem being solved here is.

good context:

When creating or updating connectors, we spend a lot of time manually transcribing JSON Schema files based on OpenAPI docs. This is ncessary because OpenAPI and JSON schema are very similar but not perfectly compatible. This process is automatable. Therefore we should create a program which converts from OpenAPI to JSONSchema format.

Semantic Versioning for Connectors

Changes to connector behavior should always be accompanied by a version bump and a changelog entry. We use semantic versioning to version changes to connectors. Since connectors are a bit different from APIs, we have our own take on semantic versioning, focusing on maintaining the best user experience of using a connector.

  • Major: a version in which a change is made which requires manual intervention (update to config or configured catalog) for an existing connection to continue to succeed, or one in which data that was previously being synced will no longer be synced
  • Minor: a version that introduces user-facing functionality in a backwards compatible manner
  • Patch: a version that introduces backwards compatible bug fixes or performance improvements

Examples

Here are some examples of code changes and their respective version changes:

ChangeImpactVersion Change
Adding a required parameter to a connector's specUsers will have to add the new parameter to their configMajor
Changing a format of a parameter in a connector's spec from a single parameter to a oneOfUsers will have to edit their config to define their old parameter value in the oneOf formatMajor
Removing a stream from a connector's catalogData that was being synced will no longer be syncedMajor
Renaming a stream in a connector's catalogUsers will have to update the name of the stream in their catalogMajor
Removing a column from a stream in a connector's catalogUsers will have to remove that column from their catalog, data that was being synced will no longer be syncedMajor
Renaming a column from a stream in a connector's catalogUsers will have to update the name of the column in their catalogMajor
Changing the datatype for a column of a stream in a connector's catalogUsers will have to update that data type in their catalog, data that was being synced will have changed formatMajor
Adding a non-required parameter to a connector's specUsers will have the option to use the required parameter in the futureMinor
Adding a stream in a connector's catalogAdditional data will be syncedMinor
Adding a column to a stream's schema in a connector's catalogAdditional data will be syncedMinor
Updating the format of the connector's STATEIncremental streams will automatically run a full refresh only for the next syncPatch
Optimizing a connector's performanceSyncs will be fasterPatch
Fixing a bug in a connectorSome syncs that would have failed will now succeedPatch

Trying to contribute, and don't see the change you want to make in this list? Call it out in your PR and your reviewer will help you pick the correct type of version change. Feel free to contribute the results back to this list!