From 5cb7ceea071db148735199e822ddf83bc164587f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lovro=20Ma=C5=BEgon?= Date: Mon, 6 May 2024 14:54:58 +0200 Subject: [PATCH] Update README.md --- README.md | 115 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 25209b3..a57d459 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,65 @@ # Conduit Connector Template + This is a template project for building [Conduit](https://conduit.io) connectors in Go. It makes it possible to start working on a Conduit connector in a matter of seconds. -This template includes the following: -* Skeleton code for the connector's configuration, source and destination -* Example unit tests -* A [Makefile](/Makefile) with commonly used targets -* A GitHub workflow to [build the code and run the tests](/.github/workflows/build.yml) -* A GitHub workflow to [run a pre-configured set of linters](/.github/workflows/lint.yml) -* A GitHub workflow which [automatically creates a release](/.github/workflows/release.yml) once a tag is pushed -* A [dependabot setup](/.github/dependabot.yml) which checks your dependencies for available updates and -[merges minor version upgrades](/.github/workflows/dependabot-auto-merge-go.yml) automatically -* [Issue](/.github/ISSUE_TEMPLATE) and [PR templates](/.github/pull_request_template.md) -* A [README template](/README_TEMPLATE.md) - -### How to use -* On this repository's main page, click "Use this template" -* Enter the information about your repository -* Once your repository has been generated, clone it -* After cloning, run `./setup.sh ` (for example: -`./setup.sh github.com/awesome-org/conduit-connector-file`) -* (Optional) Set the code owners (in the `CODEOWNERS` file) +## Quick start + +1. Click [_Use this template_](https://github.com/new?template_name=conduit-connector-template&template_owner=ConduitIO) and clone your new repository. +2. Initialize the repository using [`setup.sh`](https://github.com/ConduitIO/conduit-connector-template/blob/main/setup.sh) and commit your changes. + ```sh + ./setup.sh github.com/myusername/conduit-connector-myconnector + git add -A + git commit -m "initialize repository" + ``` +3. Set up automatic dependabot PR merges. With that, you're all set up and ready to start working on your connector! As a next step, we recommend that you -check out the [Conduit Connector SDK](https://github.com/ConduitIO/conduit-connector-sdk), which is the Go software -development kit for implementing a connector for Conduit. - - -### Repository settings -Following is a list of repository settings we recommend having. - -#### General/Pull Requests -1. Allow squash merging only. -2. Always suggest updating pull request branches. -3. Allow auto-merge. -4. Automatically delete head branches. - -#### Branch protection rules -Protect the default branch using the following rules: -1. Require a pull request before merging. Require approvals. -2. Require status checks to pass before merging. Require branches to be up to date before merging. -3. Specify status checks that are required. -4. Require conversation resolution before merging. -5. Do not allow bypassing the above settings. - -#### Actions/General -1. Allow all actions and reusable workflows. -2. Allow GitHub Actions to create and approve pull requests (if dependabot is used and it's configured to automatically -merge pull requests). - -### Specification -The `spec.go` file provides a programmatic representation of the configuration options. - -### Configuration -This template provides two types of "configs": -* general configuration (that applies to both, sources and destinations) -* and source/destination specific configs. - -All are defined in `config.go` and are represented by separate types. General configs should be added to `connectorname.Config`, -whereas any source or destination specific configs should be added to `connectorname.SourceConfig` and -`connectorname.DestinationConfig` respectively. +check out the [Conduit Connector SDK](https://github.com/ConduitIO/conduit-connector-sdk). + +## What's included? + +* Skeleton code for the connector's configuration, source and destination. +* Example unit tests. +* A [Makefile](/Makefile) with commonly used targets. +* A [GitHub workflow](/.github/workflows/build.yml) to build the code and run the tests. +* A [GitHub workflow](/.github/workflows/lint.yml) to run a pre-configured set of linters. +* A [GitHub workflow](/.github/workflows/release.yml) which automatically creates a release when a tag is pushed. +* A [dependabot setup](/.github/dependabot.yml) which checks your dependencies for available updates and +[merges minor version upgrades](/.github/workflows/dependabot-auto-merge-go.yml) automatically. +* [Issue](/.github/ISSUE_TEMPLATE) and [PR templates](/.github/pull_request_template.md). +* A [README template](/README_TEMPLATE.md). + +## Automatically merging dependabot PRs + +> [!NOTE] +> This applies only to public connector repositories, as branch protection rules are not enforced in private repositories. + +The template makes it simple to keep your connector up-to-date using automatic merging of +[Dependabot](https://github.com/dependabot) PRs. To make use of this setup, you need to adjust +some repository settings. + +1. Navigate to Settings -> General and allow auto-merge of PRs. + + ![Allow auto-merge](https://github.com/ConduitIO/conduit-connector-template/assets/8320753/695b15f0-85b4-49cb-966d-649e9bf03455) + +2. Navigate to Settings -> Branch and add a branch protection rule. + + ![Add branch protection rule](https://github.com/ConduitIO/conduit-connector-template/assets/8320753/9f5a07bc-d141-42b9-9918-e8d9cc648482) + +3. Create a rule for branch `main` that requires status checks `build` and `golangci-lint`. + + ![Status checks](https://github.com/ConduitIO/conduit-connector-template/assets/8320753/96219185-c329-432a-8623-9b4462015f32) + +## Recommended repository settings + +- Allow squash merging only. +- Always suggest updating pull request branches. +- Automatically delete head branches. +- Branch protection rules on branch `main` (only in public repositories): + - Require a pull request before merging. + - Require approvals. + - Require status checks `build` and `golangci-lint`. + - Require branches to be up to date before merging. + - Require conversation resolution before merging. + - Do not allow bypassing the above settings.