|
| 1 | +# Copyright (c) 2023 Airbyte, Inc., all rights reserved. |
| 2 | + |
| 3 | +import textwrap |
| 4 | +from typing import List |
| 5 | + |
| 6 | +from connector_ops.utils import Connector # type: ignore |
| 7 | +from connectors_qa import consts |
| 8 | +from connectors_qa.models import Check, CheckCategory, CheckResult |
| 9 | +from pydash.objects import get # type: ignore |
| 10 | + |
| 11 | + |
| 12 | +class DocumentationCheck(Check): |
| 13 | + category = CheckCategory.DOCUMENTATION |
| 14 | + |
| 15 | + |
| 16 | +class CheckMigrationGuide(DocumentationCheck): |
| 17 | + name = "Breaking changes must be accompanied by a migration guide" |
| 18 | + description = "When a breaking change is introduced we check that a migration guide is available. It should be stored under `./docs/integrations/<connector-type>s/<connector-name>-migrations.md`.\nThis document should contain a section for each breaking change, in order of the version descending. It must explain users which action to take to migrate to the new version." |
| 19 | + |
| 20 | + def _run(self, connector: Connector) -> CheckResult: |
| 21 | + breaking_changes = get(connector.metadata, "releases.breakingChanges") |
| 22 | + if not breaking_changes: |
| 23 | + return self.create_check_result( |
| 24 | + connector=connector, |
| 25 | + passed=True, |
| 26 | + message="No breaking changes found. A migration guide is not required", |
| 27 | + ) |
| 28 | + migration_guide_file_path = connector.migration_guide_file_path |
| 29 | + migration_guide_exists = migration_guide_file_path is not None and migration_guide_file_path.exists() |
| 30 | + if not migration_guide_exists: |
| 31 | + return self.create_check_result( |
| 32 | + connector=connector, |
| 33 | + passed=False, |
| 34 | + message=f"Migration guide file is missing for {connector.technical_name}. Please create a migration guide in ./docs/integrations/<connector-type>s/<connector-name>-migrations.md`", |
| 35 | + ) |
| 36 | + |
| 37 | + expected_title = f"# {connector.name_from_metadata} Migration Guide" |
| 38 | + expected_version_header_start = "## Upgrading to " |
| 39 | + migration_guide_content = migration_guide_file_path.read_text() |
| 40 | + try: |
| 41 | + first_line = migration_guide_content.splitlines()[0] |
| 42 | + except IndexError: |
| 43 | + first_line = migration_guide_content |
| 44 | + if not first_line == expected_title: |
| 45 | + return self.create_check_result( |
| 46 | + connector=connector, |
| 47 | + passed=False, |
| 48 | + message=f"Migration guide file for {connector.technical_name} does not start with the correct header. Expected '{expected_title}', got '{first_line}'", |
| 49 | + ) |
| 50 | + |
| 51 | + # Check that the migration guide contains a section for each breaking change key ## Upgrading to {version} |
| 52 | + # Note that breaking change is a dict where the version is the key |
| 53 | + # Note that the migration guide must have the sections in order of the version descending |
| 54 | + # 3.0.0, 2.0.0, 1.0.0, etc |
| 55 | + # This means we have to record the headings in the migration guide and then check that they are in order |
| 56 | + # We also have to check that the headings are in the breaking changes dict |
| 57 | + ordered_breaking_changes = sorted(breaking_changes.keys(), reverse=True) |
| 58 | + ordered_expected_headings = [f"{expected_version_header_start}{version}" for version in ordered_breaking_changes] |
| 59 | + |
| 60 | + ordered_heading_versions = [] |
| 61 | + for line in migration_guide_content.splitlines(): |
| 62 | + stripped_line = line.strip() |
| 63 | + if stripped_line.startswith(expected_version_header_start): |
| 64 | + version = stripped_line.replace(expected_version_header_start, "") |
| 65 | + ordered_heading_versions.append(version) |
| 66 | + |
| 67 | + if ordered_breaking_changes != ordered_heading_versions: |
| 68 | + return self.create_check_result( |
| 69 | + connector=connector, |
| 70 | + passed=False, |
| 71 | + message=textwrap.dedent( |
| 72 | + f""" |
| 73 | + Migration guide file for {connector.name_from_metadata} has incorrect version headings. |
| 74 | + Check for missing, extra, or misordered headings, or headers with typos. |
| 75 | + Expected headings: {ordered_expected_headings} |
| 76 | + """ |
| 77 | + ), |
| 78 | + ) |
| 79 | + return self.create_check_result( |
| 80 | + connector=connector, |
| 81 | + passed=True, |
| 82 | + message="The migration guide is correctly templated", |
| 83 | + ) |
| 84 | + |
| 85 | + |
| 86 | +class CheckDocumentationExists(DocumentationCheck): |
| 87 | + name = "Connectors must have user facing documentation" |
| 88 | + description = ( |
| 89 | + "The user facing connector documentation should be stored under `./docs/integrations/<connector-type>s/<connector-name>.md`." |
| 90 | + ) |
| 91 | + |
| 92 | + def _run(self, connector: Connector) -> CheckResult: |
| 93 | + if not connector.documentation_file_path or not connector.documentation_file_path.exists(): |
| 94 | + return self.fail( |
| 95 | + connector=connector, |
| 96 | + message="User facing documentation file is missing. Please create it under ./docs/integrations/<connector-type>s/<connector-name>.md", |
| 97 | + ) |
| 98 | + return self.pass_( |
| 99 | + connector=connector, |
| 100 | + message=f"User facing documentation file {connector.documentation_file_path} exists", |
| 101 | + ) |
| 102 | + |
| 103 | + |
| 104 | +class CheckDocumentationStructure(DocumentationCheck): |
| 105 | + name = "Connectors documentation follows our guidelines" |
| 106 | + description = f"The user facing connector documentation should follow the guidelines defined in the [documentation standards]({consts.DOCUMENTATION_STANDARDS_URL})." |
| 107 | + |
| 108 | + expected_sections = [ |
| 109 | + "## Prerequisites", |
| 110 | + "## Setup guide", |
| 111 | + "## Supported sync modes", |
| 112 | + "## Supported streams", |
| 113 | + "## Changelog", |
| 114 | + ] |
| 115 | + |
| 116 | + def check_main_header(self, connector: Connector, doc_lines: List[str]) -> List[str]: |
| 117 | + errors = [] |
| 118 | + if not doc_lines[0].lower().startswith(f"# {connector.metadata['name']}".lower()): |
| 119 | + errors.append( |
| 120 | + f"The connector name is not used as the main header in the documentation. Expected: '# {connector.metadata['name']}'" |
| 121 | + ) |
| 122 | + return errors |
| 123 | + |
| 124 | + def check_sections(self, doc_lines: List[str]) -> List[str]: |
| 125 | + errors = [] |
| 126 | + for expected_section in self.expected_sections: |
| 127 | + if expected_section.lower() not in doc_lines: |
| 128 | + errors.append(f"Connector documentation is missing a '{expected_section.replace('#', '').strip()}' section") |
| 129 | + return errors |
| 130 | + |
| 131 | + def _run(self, connector: Connector) -> CheckResult: |
| 132 | + if not connector.documentation_file_path or not connector.documentation_file_path.exists(): |
| 133 | + return self.fail( |
| 134 | + connector=connector, |
| 135 | + message="Could not check documentation structure as the documentation file is missing.", |
| 136 | + ) |
| 137 | + |
| 138 | + doc_lines = [line.lower() for line in connector.documentation_file_path.read_text().splitlines()] |
| 139 | + |
| 140 | + if not doc_lines: |
| 141 | + return self.fail( |
| 142 | + connector=connector, |
| 143 | + message="Documentation file is empty", |
| 144 | + ) |
| 145 | + |
| 146 | + errors = [] |
| 147 | + errors.extend(self.check_main_header(connector, doc_lines)) |
| 148 | + errors.extend(self.check_sections(doc_lines)) |
| 149 | + |
| 150 | + if errors: |
| 151 | + return self.fail( |
| 152 | + connector=connector, |
| 153 | + message=f"Connector documentation does not follow the guidelines: {'. '.join(errors)}", |
| 154 | + ) |
| 155 | + return self.pass_( |
| 156 | + connector=connector, |
| 157 | + message="Documentation guidelines are followed", |
| 158 | + ) |
| 159 | + |
| 160 | + |
| 161 | +class CheckChangelogEntry(DocumentationCheck): |
| 162 | + name = "Connectors must have a changelog entry for each version" |
| 163 | + description = "Each new version of a connector must have a changelog entry defined in the user facing documentation in `./docs/integrations/<connector-type>s/<connector-name>.md`." |
| 164 | + |
| 165 | + def _run(self, connector: Connector) -> CheckResult: |
| 166 | + if connector.documentation_file_path is None or not connector.documentation_file_path.exists(): |
| 167 | + return self.fail( |
| 168 | + connector=connector, |
| 169 | + message="Could not check changelog entry as the documentation file is missing. Please create it.", |
| 170 | + ) |
| 171 | + |
| 172 | + doc_lines = connector.documentation_file_path.read_text().splitlines() |
| 173 | + if not doc_lines: |
| 174 | + return self.fail( |
| 175 | + connector=connector, |
| 176 | + message="Documentation file is empty", |
| 177 | + ) |
| 178 | + |
| 179 | + after_changelog = False |
| 180 | + entry_found = False |
| 181 | + for line in doc_lines: |
| 182 | + if "# changelog" in line.lower(): |
| 183 | + after_changelog = True |
| 184 | + if after_changelog and connector.version in line: |
| 185 | + entry_found = True |
| 186 | + |
| 187 | + if not after_changelog: |
| 188 | + return self.fail( |
| 189 | + connector=connector, |
| 190 | + message="Connector documentation is missing a 'Changelog' section", |
| 191 | + ) |
| 192 | + if not entry_found: |
| 193 | + return self.fail( |
| 194 | + connector=connector, |
| 195 | + message=f"Connectors must have a changelog entry for each version: changelog entry for version {connector.version} is missing in the documentation", |
| 196 | + ) |
| 197 | + |
| 198 | + return self.pass_(connector=connector, message=f"Changelog entry found for version {connector.version}") |
| 199 | + |
| 200 | + |
| 201 | +ENABLED_CHECKS = [ |
| 202 | + CheckMigrationGuide(), |
| 203 | + CheckDocumentationExists(), |
| 204 | + CheckDocumentationStructure(), |
| 205 | + CheckChangelogEntry(), |
| 206 | +] |
0 commit comments