From 0a4162f14a322ffb36c4b1793314900e06089584 Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Mon, 23 Jun 2025 21:48:00 +0200 Subject: [PATCH] DOCS: How to add a requested provider (#3636) --- documentation/SUMMARY.md | 1 + documentation/advanced-features/bug-triage.md | 31 -------- .../developer-info/provider-request.md | 76 +++++++++++++++++++ documentation/provider/index.md | 2 +- 4 files changed, 78 insertions(+), 32 deletions(-) create mode 100644 documentation/developer-info/provider-request.md diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 44131d2b5..6834ca989 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -194,6 +194,7 @@ * [ALIAS Records](advanced-features/alias.md) * [TXT record testing](advanced-features/testing-txt-records.md) * [DNS records ordering](advanced-features/ordering.md) +* [How to add a requested provider](developer-info/provider-request.md) ## Release diff --git a/documentation/advanced-features/bug-triage.md b/documentation/advanced-features/bug-triage.md index 9355259d9..f152dddfd 100644 --- a/documentation/advanced-features/bug-triage.md +++ b/documentation/advanced-features/bug-triage.md @@ -18,34 +18,3 @@ labels: priority: * maybe someday: Low priority - -# How to handle a provider request - -1. Change the subject to be "Provider request: name of the provider" -1. Set the label `provider-request` -1. Respond to the issue with the message below -1. Close the issue - -The [Providers](../provider/index.md) page is generated -automatically from all the issues tagged `provider-request`: - -1. "Requested providers: state=closed, tagged `provider-request` -1. "In progress providers": state=open, tagged `provider-request`, NOT tagged `has-pr` -1. "Providers with open PRs": state=open, tagged `provider-request` AND `has-pr` - -Message to requester: - -```text -Thank you for requesting this provider! - -I've tagged this issue as a provider-request. It will (soon) be listed as a "requested provider" on the provider list web page: -https://docs.dnscontrol.org/provider - -I will now close the issue. I know that's a bit confusing, but it will remain on the "requested provider" list. - -If someone would like to volunteer to implement this, please re-open this issue and add the tag `has-pr`. - -We encourage you to try adding this provider yourself. We've tried to make the process as friendly as possible. Many people have reported that adding a provider was their first experience writing Go. The process is documented here: -https://docs.dnscontrol.org/developer-info/writing-providers -If you need assistance, please speak up in this issue and someone will get back to you ASAP. -``` diff --git a/documentation/developer-info/provider-request.md b/documentation/developer-info/provider-request.md new file mode 100644 index 000000000..934bca938 --- /dev/null +++ b/documentation/developer-info/provider-request.md @@ -0,0 +1,76 @@ +# How to add a requested provider + +Follow the steps below to document a newly requested provider in the `documentation/provider/index.md` file. + +## 1. Start from an up-to-date `main` branch + +Make sure your local `main` branch is up to date, then create a new branch for your changes: + +```shell +git switch main +git pull +git checkout -B docs/provider-request +``` + +## 2. Define variables + +Set the following environment variables to use in the steps below: + +```shell +export PROVIDER_NAME="Sav.com" +export GITHUB_ISSUE_NUMBER=3633 +export GITHUB_FORK_REPO="yourusername/dnscontrol" +``` + +Replace `yourusername` with your actual GitHub username or organization name. + +## 3. Edit the provider index file + +Open the file in your preferred editor: + +```shell +nano documentation/provider/index.md +``` + +Or, using PhpStorm: + +```shell +phpstorm documentation/provider/index.md +``` + +Scroll to the **Requested providers** section and append the following line: + +```markdown +* [Sav.com](https://github.com/StackExchange/dnscontrol/issues/3633) (#3633) +``` + +To generate this automatically, run: + +```shell +echo "* [${PROVIDER_NAME}](https://github.com/StackExchange/dnscontrol/issues/${GITHUB_ISSUE_NUMBER}) (#${GITHUB_ISSUE_NUMBER})" +``` + +Make sure to insert the new line in alphabetical order if applicable. + +## 4. Commit your changes + +Add and commit the modified file: + +```shell +git add documentation/provider/index.md +git commit -m "DOCS: Added requested provider ${PROVIDER_NAME} (#${GITHUB_ISSUE_NUMBER})" +``` + +## 5. Push and open a pull request + +Push your changes to your fork and open a new pull request: + +```shell +git push --no-verify +open "https://github.com/${GITHUB_FORK_REPO}/pull/new/docs/provider-request" +echo "Added ${PROVIDER_NAME} #${GITHUB_ISSUE_NUMBER} to the list of requested providers." +``` + +{% hint style="info" %} +**NOTE**: GitHub does not support pre-filling pull request titles or descriptions via URL parameters. The title will be auto-filled using your commit message. You can adjust it manually after opening the PR. +{% endhint %} diff --git a/documentation/provider/index.md b/documentation/provider/index.md index e0132b101..b88d364b3 100644 --- a/documentation/provider/index.md +++ b/documentation/provider/index.md @@ -448,7 +448,7 @@ code to support this provider, we'd be glad to help in any way. #### Q: Why are the above GitHub issues marked "closed"? -A: Following [the bug triage process](../advanced-features/bug-triage.md), the request +A: Following [provider requests](../developer-info/provider-request.md), the request is closed once it is added to this list. If someone chooses to implement the provider, they re-open the issue.