airbyte/docusaurus/platform_versioned_docs/version-1.8/contributing-to-airbyte/resources/pull-requests-handbook.md

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 Type	Emoji	Examples
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 your code change is doing more than one change type at once, we strongly recommend to break it 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
  • Note that a category of "user intervention" is a schema change in the destination, as users will be required to update downstream reports and tools. A change that leads to a different final table in the destination is a breaking change
• 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:

Change	Impact	Version Change
Adding a required parameter to a connector's spec	Users will have to add the new parameter to their config	Major
Changing a format of a parameter in a connector's spec from a single parameter to a oneOf	Users will have to edit their config to define their old parameter value in the oneOf format	Major
Removing a stream from a connector's catalog	Data that was being synced will no longer be synced	Major
Renaming a stream in a connector's catalog	Users will have to update the name of the stream in their catalog	Major
Removing a column from a stream in a connector's catalog	Users will have to remove that column from their catalog, data that was being synced will no longer be synced	Major
Renaming a column from a stream in a connector's catalog	Users will have to update the name of the column in their catalog	Major
Changing the datatype for a column of a stream in a connector's catalog	Users will have to update that data type in their catalog, data that was being synced will have changed format	Major
Adding a non-required parameter to a connector's spec	Users will have the option to use the required parameter in the future	Minor
Adding a stream in a connector's catalog	Additional data will be synced	Minor
Adding a column to a stream's schema in a connector's catalog	Additional data will be synced	Minor
Updating the format of the connector's STATE	Incremental streams will automatically run a full refresh only for the next sync	Patch
Optimizing a connector's performance	Syncs will be faster	Patch
Fixing a bug in a connector	Some syncs that would have failed will now succeed	Patch

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!