|
1 | 1 | # Plausible source connector |
2 | 2 |
|
3 | | -This is the repository for the Plausible configuration based source connector. |
4 | | -For information about how to use this connector within Airbyte, see [the documentation](https://docs.airbyte.com/integrations/sources/plausible). |
| 3 | +This directory contains the manifest-only connector for `source-plausible`. |
| 4 | +This _manifest-only_ connector is not a Python package on its own, as it runs inside of the base `source-declarative-manifest` image. |
5 | 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 | | -### Installing the connector |
15 | | - |
16 | | -From this connector directory, run: |
17 | | -```bash |
18 | | -poetry install --with dev |
19 | | -``` |
20 | | - |
21 | | - |
22 | | -### Create credentials |
| 6 | +For information about how to configure and use this connector within Airbyte, see [the connector's full documentation](https://docs.airbyte.com/integrations/sources/plausible). |
23 | 7 |
|
24 | | -**If you are a community contributor**, follow the instructions in the [documentation](https://docs.airbyte.com/integrations/sources/plausible) |
25 | | -to generate the necessary credentials. Then create a file `secrets/config.json` conforming to the `src/source_plausible/spec.yaml` file. |
26 | | -Note that any directory named `secrets` is gitignored across the entire Airbyte repo, so there is no danger of accidentally checking in sensitive information. |
27 | | -See `sample_files/sample_config.json` for a sample config file. |
28 | | - |
29 | | - |
30 | | -### Locally running the connector |
31 | | - |
32 | | -``` |
33 | | -poetry run source-plausible spec |
34 | | -poetry run source-plausible check --config secrets/config.json |
35 | | -poetry run source-plausible discover --config secrets/config.json |
36 | | -poetry run source-plausible read --config secrets/config.json --catalog sample_files/configured_catalog.json |
37 | | -``` |
38 | | - |
39 | | -### Running tests |
| 8 | +## Local development |
40 | 9 |
|
41 | | -To run tests locally, from the connector directory run: |
| 10 | +We recommend using the Connector Builder to edit this connector. |
| 11 | +Using either Airbyte Cloud or your local Airbyte OSS instance, navigate to the **Builder** tab and select **Import a YAML**. |
| 12 | +Then select the connector's `manifest.yaml` file to load the connector into the Builder. You're now ready to make changes to the connector! |
42 | 13 |
|
43 | | -``` |
44 | | -poetry run pytest tests |
45 | | -``` |
| 14 | +If you prefer to develop locally, you can follow the instructions below. |
46 | 15 |
|
47 | 16 | ### Building the docker image |
48 | 17 |
|
| 18 | +You can build any manifest-only connector with `airbyte-ci`: |
| 19 | + |
49 | 20 | 1. Install [`airbyte-ci`](https://github.com/airbytehq/airbyte/blob/master/airbyte-ci/connectors/pipelines/README.md) |
50 | 21 | 2. Run the following command to build the docker image: |
| 22 | + |
51 | 23 | ```bash |
52 | 24 | airbyte-ci connectors --name=source-plausible build |
53 | 25 | ``` |
54 | 26 |
|
55 | 27 | An image will be available on your host with the tag `airbyte/source-plausible:dev`. |
56 | 28 |
|
| 29 | +### Creating credentials |
| 30 | + |
| 31 | +**If you are a community contributor**, follow the instructions in the [documentation](https://docs.airbyte.com/integrations/sources/plausible) |
| 32 | +to generate the necessary credentials. Then create a file `secrets/config.json` conforming to the `spec` object in the connector's `manifest.yaml` file. |
| 33 | +Note that any directory named `secrets` is gitignored across the entire Airbyte repo, so there is no danger of accidentally checking in sensitive information. |
57 | 34 |
|
58 | 35 | ### Running as a docker container |
59 | 36 |
|
60 | | -Then run any of the connector commands as follows: |
61 | | -``` |
| 37 | +Then run any of the standard source connector commands: |
| 38 | + |
| 39 | +```bash |
62 | 40 | docker run --rm airbyte/source-plausible:dev spec |
63 | 41 | docker run --rm -v $(pwd)/secrets:/secrets airbyte/source-plausible:dev check --config /secrets/config.json |
64 | 42 | docker run --rm -v $(pwd)/secrets:/secrets airbyte/source-plausible:dev discover --config /secrets/config.json |
65 | 43 | docker run --rm -v $(pwd)/secrets:/secrets -v $(pwd)/integration_tests:/integration_tests airbyte/source-plausible:dev read --config /secrets/config.json --catalog /integration_tests/configured_catalog.json |
66 | 44 | ``` |
67 | 45 |
|
68 | | -### Running our CI test suite |
| 46 | +### Running the CI test suite |
69 | 47 |
|
70 | 48 | You can run our full test suite locally using [`airbyte-ci`](https://github.com/airbytehq/airbyte/blob/master/airbyte-ci/connectors/pipelines/README.md): |
71 | | -```bash |
72 | | -airbyte-ci connectors --name=source-plausible 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 | 49 |
|
80 | | -### Dependency Management |
81 | | - |
82 | | -All of your dependencies should be managed via Poetry. |
83 | | -To add a new dependency, run: |
84 | 50 | ```bash |
85 | | -poetry add <package-name> |
| 51 | +airbyte-ci connectors --name=source-plausible test |
86 | 52 | ``` |
87 | 53 |
|
88 | | -Please commit the changes to `pyproject.toml` and `poetry.lock` files. |
89 | | - |
90 | 54 | ## Publishing a new version of the connector |
91 | | -You've checked out the repo, implemented a million dollar feature, and you're ready to share your changes with the world. Now what? |
92 | | -1. Make sure your changes are passing our test suite: `airbyte-ci connectors --name=source-plausible test` |
93 | | -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)): |
| 55 | + |
| 56 | +If you want to contribute changes to `source-plausible`, here's how you can do that: |
| 57 | +1. Make your changes locally, or load the connector's manifest into Connector Builder and make changes there. |
| 58 | +2. Make sure your changes are passing our test suite with `airbyte-ci connectors --name=source-plausible test` |
| 59 | +3. 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)): |
94 | 60 | - bump the `dockerImageTag` value in in `metadata.yaml` |
95 | | - - bump the `version` value in `pyproject.toml` |
96 | | -3. Make sure the `metadata.yaml` content is up to date. |
97 | 61 | 4. Make sure the connector documentation and its changelog is up to date (`docs/integrations/sources/plausible.md`). |
98 | 62 | 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). |
99 | 63 | 6. Pat yourself on the back for being an awesome contributor. |
|
0 commit comments