Integration changelog entries are automatically fetched from tap repositories to create draft files in the docs repository.

What is automated?

The changelog automation fetches some information about pull requests that appear in the changelog file in the singer-io tap repositories. The main goal of this automation is to sort through all the pull requests on all tap repositories and get only the ones that need to be mentioned in the changelog.

This only applies to tap repositories in the singer-io organization, so changelogs for other integrations, destinations, and other features need to be done manually.

How does it work?

Every Monday, the Get new changelog entries runs and an performs the following actions:

1. Creates a new branch on the docs repository.
2. Gets the list of PRs merged in the past week in all tap repositories.
3. Gets the list of PRs from the past week that are mentioned in the changelog of each tap repository.
4. Removes the PRs to ignore and already documented PRs from that list.
5. Creates a draft file for each PR and adds it to the _changelog-files/draft folder.
6. Commits and pushes the changes on the new branch.
7. Creates a new branch from the new branch to master.

What do I need to do after the job runs?

The automation sorts through the pull requests to exclude all pull requests that don’t need to be added to the changelog, but sometimes it can still create a file that is not needed. The first step when you get the changelog pull request is to check it everything actually belongs in the Stitch docs changelog.

The general rule is that it is only needed for users of the Stitch UI and APIs. If an update only impacts users that run taps outside of Stitch, it doesn’t need to be in the changelog. For example, if a Python module in a tap is updated, it will be transparent for Stitch users and doesn’t need to be documented.

If a pull request does not need to be added to the changelog, you need to:

• Add the PR link to the scripts/changelog/ignore.txt file to make sure it is ignored the next time the GitHub Action runs.
• Delete the changelog file from the draft folder.

Since the files created are only drafts, there is some work needed before the pull request can be merged.

• The title in the draft is the title of the tap repository pull request, so it needs to be changed to match the format used in the Stitch docs changelog, for example: Facebook Ads (v1) update: API upgrade.
• The following fields need to be filled out:
  • entry-type: the type of changelog entry, new-feature, improvement, or bug-fix for example.
  • connection-id: the ID of the integration. This is not the tap repository name or the integration display name. In many cases it is the repository name without tap-, but not always. When in doubt, this ID can be found in the id element for the integration in the _data/taps/integrations.yml file.
  • connection-version: the major version of the integration that this entry applies to (usually the latest version).
• A description of the change needs to be added at the end of the file.
• The files are generated with names following the pattern <date>-<tap_name>-<pr_number>.md, they need to be renamed to follow this pattern instead: <date>-<integration_id>-v<major_version>-<description>.md.
• The files need to be moved from the draft folder into the folder for the year of the update.

Once the changelog entries are completed, you can merge the pull request to publish.

Last updated: 14 March 2024