|
| 1 | +# {{capitalCase name}} Destination |
| 2 | + |
| 3 | +This is the repository for the {{capitalCase name}} destination connector, written in Python. |
| 4 | +For information about how to use this connector within Airbyte, see [the documentation](https://docs.airbyte.com/integrations/destinations/{{dashCase name}}). |
| 5 | + |
| 6 | +## Local development |
| 7 | + |
| 8 | +### Prerequisites |
| 9 | + |
| 10 | +* Python (`^3.9`) |
| 11 | +* Poetry (`^1.7`) - installation instructions [here](https://python-poetry.org/docs/#installation) |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +### Installing the connector |
| 16 | + |
| 17 | +From this connector directory, run: |
| 18 | +```bash |
| 19 | +poetry install --with dev |
| 20 | +``` |
| 21 | + |
| 22 | + |
| 23 | +#### Create credentials |
| 24 | + |
| 25 | +**If you are a community contributor**, follow the instructions in the [documentation](https://docs.airbyte.com/integrations/destinations/{{dashCase name}}) |
| 26 | +to generate the necessary credentials. Then create a file `secrets/config.json` conforming to the `destination_{{snakeCase name}}/spec.json` file. |
| 27 | +Note that the `secrets` directory is gitignored by default, so there is no danger of accidentally checking in sensitive information. |
| 28 | +See `integration_tests/sample_config.json` for a sample config file. |
| 29 | + |
| 30 | +**If you are an Airbyte core member**, copy the credentials in Lastpass under the secret name `destination {{dashCase name}} test creds` |
| 31 | +and place them into `secrets/config.json`. |
| 32 | + |
| 33 | +### Locally running the connector |
| 34 | +``` |
| 35 | +poetry run destination-{{dashCase name}} spec |
| 36 | +poetry run destination-{{dashCase name}} check --config secrets/config.json |
| 37 | +poetry run destination-{{dashCase name}} write --config secrets/config.json --catalog sample_files/configured_catalog.json |
| 38 | +``` |
| 39 | + |
| 40 | +### Running tests |
| 41 | + |
| 42 | +To run tests locally, from the connector directory run: |
| 43 | + |
| 44 | +``` |
| 45 | +poetry run pytest tests |
| 46 | +``` |
| 47 | + |
| 48 | +### Building the docker image |
| 49 | + |
| 50 | +1. Install [`airbyte-ci`](https://github.com/airbytehq/airbyte/blob/master/airbyte-ci/connectors/pipelines/README.md) |
| 51 | +2. Run the following command to build the docker image: |
| 52 | +```bash |
| 53 | +airbyte-ci connectors --name=destination-{{dashCase name}} build |
| 54 | +``` |
| 55 | + |
| 56 | +An image will be available on your host with the tag `airbyte/destination-{{dashCase name}}:dev`. |
| 57 | + |
| 58 | +### Running as a docker container |
| 59 | + |
| 60 | +Then run any of the connector commands as follows: |
| 61 | +``` |
| 62 | +docker run --rm airbyte/destination-{{dashCase name}}:dev spec |
| 63 | +docker run --rm -v $(pwd)/secrets:/secrets airbyte/destination-{{dashCase name}}:dev check --config /secrets/config.json |
| 64 | +docker run --rm -v $(pwd)/secrets:/secrets -v $(pwd)/integration_tests:/integration_tests airbyte/destination-{{dashCase name}}:dev write --config /secrets/config.json --catalog /integration_tests/configured_catalog.json |
| 65 | +``` |
| 66 | + |
| 67 | +### Running our CI test suite |
| 68 | + |
| 69 | +You can run our full test suite locally using [`airbyte-ci`](https://github.com/airbytehq/airbyte/blob/master/airbyte-ci/connectors/pipelines/README.md): |
| 70 | + |
| 71 | +```bash |
| 72 | +airbyte-ci connectors --name=destination-{{dashCase name}} test |
| 73 | +``` |
| 74 | + |
| 75 | +### Customizing acceptance Tests |
| 76 | + |
| 77 | +Customize `acceptance-test-config.yml` file to configure acceptance tests. See [Connector Acceptance Tests](https://docs.airbyte.com/connector-development/testing-connectors/connector-acceptance-tests-reference) for more information. |
| 78 | +If your connector requires to create or destroy resources for use during acceptance tests create fixtures for it and place them inside integration_tests/acceptance.py. |
| 79 | + |
| 80 | +### Dependency Management |
| 81 | + |
| 82 | +All of your dependencies should be managed via Poetry. |
| 83 | +To add a new dependency, run: |
| 84 | + |
| 85 | +```bash |
| 86 | +poetry add <package-name> |
| 87 | +``` |
| 88 | + |
| 89 | +Please commit the changes to `pyproject.toml` and `poetry.lock` files. |
| 90 | + |
| 91 | +## Publishing a new version of the connector |
| 92 | + |
| 93 | +You've checked out the repo, implemented a million dollar feature, and you're ready to share your changes with the world. Now what? |
| 94 | +1. Make sure your changes are passing our test suite: `airbyte-ci connectors --name=destination-{{dashCase name}} test` |
| 95 | +2. Bump the connector version (please follow [semantic versioning for connectors](https://docs.airbyte.com/contributing-to-airbyte/resources/pull-requests-handbook/#semantic-versioning-for-connectors)): |
| 96 | + - bump the `dockerImageTag` value in in `metadata.yaml` |
| 97 | + - bump the `version` value in `pyproject.toml` |
| 98 | +3. Make sure the `metadata.yaml` content is up to date. |
| 99 | +4. Make sure the connector documentation and its changelog is up to date (`docs/integrations/destinations/{{dashCase name}}.md`). |
| 100 | +5. Create a Pull Request: use [our PR naming conventions](https://docs.airbyte.com/contributing-to-airbyte/resources/pull-requests-handbook/#pull-request-title-convention). |
| 101 | +6. Pat yourself on the back for being an awesome contributor. |
| 102 | +7. Someone from Airbyte will take a look at your PR and iterate with you to merge it into master. |
| 103 | +8. Once your PR is merged, the new version of the connector will be automatically published to Docker Hub and our connector registry. |
0 commit comments