diff --git a/frontend/docs/providers/adding.md b/frontend/docs/providers/adding.md index 44b6c88..fb060a5 100644 --- a/frontend/docs/providers/adding.md +++ b/frontend/docs/providers/adding.md @@ -1 +1,19 @@ # Adding your provider to the OpenTofu Registry + +Once you have [published your provider](/docs/providers/publishing), you are ready to add your provider to the OpenTofu Registry. You only need to perform these steps once, the OpenTofu Registry will automatically discover new versions you publish. + +## Adding the provider + +To add your provider, please go to the [OpenTofu Registry repository](https://github.com/opentofu/registry/issues/new/choose) and select `Submit new Provider`. In the `Provider Repository` field please enter `YOURNAME/terraform-provider-YOURPROVIDER` and submit the issue. An OpenTofu team member will review your submission and merge it into the Registry. Your provider should be live within an hour after merging. + +## Adding the GPG key + +After your provider is merged, you can proceed to add your GPG key. You will need to perform the following steps: + +1. Export your *public* GPG key into a text file with ASCII-armor. +2. If your provider is located in an organization, make sure you make [your membership in the organization public](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). This is required to validate you have the rights to publish a GPG key. +3. Go to the [OpenTofu Registry repository](https://github.com/opentofu/registry/issues/new/choose) and select `Submit new Provider Signing Key`. +4. In the `Provider Namespace` field enter your username or organization name. +5. In the `Provider GPG Key` field paste your GPG key. + +~> The GPG key applies to all providers in under your username or organization. Don't submit a GPG key if you have providers that are not signed or are signed with a key you don't have. \ No newline at end of file diff --git a/frontend/docs/providers/creating.md b/frontend/docs/providers/creating.md index d64b021..4855bd2 100644 --- a/frontend/docs/providers/creating.md +++ b/frontend/docs/providers/creating.md @@ -36,4 +36,4 @@ As of OpenTofu 1.8, OpenTofu does not yet implement using the `moved` block betw ## Next steps -Once you have written your provider code, you can proceed to [publishing your provider](/docs/providers/publishing). \ No newline at end of file +Once you have written your provider code, you can proceed to [write your documentation](/docs/providers/docs). \ No newline at end of file diff --git a/frontend/docs/providers/docs.md b/frontend/docs/providers/docs.md index 7c22bcb..9594f0e 100644 --- a/frontend/docs/providers/docs.md +++ b/frontend/docs/providers/docs.md @@ -1 +1,30 @@ # Writing documentation for your provider + +In order for your provider to show up in the OpenTofu Registry Search properly, you will need to write some documentation. Tools like [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs) can help you by auto-generating much of the documentation based on your provider schema. + +## Documentation structure + +You can place your documentation in the `docs` or `website/docs` folder in your repository. Please create the files in the following naming convention: + +- `/docs/guides/.md` for guides. +- `/docs/resources/.md` for resources. (Note: if your resource is called `yourprovider_yourresource`, you should only include `yourresource` here.) +- `/docs/data-sources/.md` for resources. (Note: same as for resources) +- `/docs/functions/.md` for functions. + +Additionally, if you would like to support CDKTF, you can create the following documents: + +- `/docs/cdktf/[python|typescript|csharp|java|go]/resources/.md` +- `/docs/cdktf/[python|typescript|csharp|java|go]/data-sources/.md` +- `/docs/cdktf/[python|typescript|csharp|java|go]/functions/.md` + +You can include the following header (front matter) in your markdown files: + +```yaml +--- +page_title: Title of the page +subcategory: Subcategory to place the page in on the sidebar (optional) +description: Description of the page +--- +``` + +Once you have written your documentation, you can [proceed to publish your provider](/docs/providers/publishing). \ No newline at end of file diff --git a/frontend/docs/providers/gpg.md b/frontend/docs/providers/gpg.md deleted file mode 100644 index debaab7..0000000 --- a/frontend/docs/providers/gpg.md +++ /dev/null @@ -1 +0,0 @@ -# Adding GPG signatures for your release diff --git a/frontend/docs/providers/publishing.md b/frontend/docs/providers/publishing.md index f3eb54a..b9c7b7f 100644 --- a/frontend/docs/providers/publishing.md +++ b/frontend/docs/providers/publishing.md @@ -1 +1,41 @@ # Publishing a provider version + +Once you have finished [creating your provider](/docs/providers/creating) and [wrote your documentation](/docs/providers/docs), you can proceed to publish your provider. First, create a GitHub repository named `terraform-provider-YOURNAME` and publish your source code in this repository. You can then proceed to [create a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). + +~> Note, that your release name **must** start with a `v` and must follow [semantic versioning](https://semver.org/). + +## Using the scaffolding (recommended) + +If you used the [terraform-provider-scaffolding-framework](https://github.com/hashicorp/terraform-provider-scaffolding-framework) as your starting point, it also includes the necessary GitHub Actions and [goreleaser file](https://github.com/hashicorp/terraform-provider-scaffolding-framework/blob/main/.goreleaser.yml) needed to create a release. + +You will need to create the secrets called `GPG_PRIVATE_KEY` and `PASSPHRASE` in order to sign your release. This is required for the Terraform Registry and recommended for the OpenTofu Registry. Please follow the [GitHub documentation on generating a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). (You do not need to add it to your GitHub account, but you will need to [submit the key to the OpenTofu Registry](/docs/providers/adding)). + +Once this is set up, proceed to create a release named `vYOURVERSION` on GitHub and wait for the GitHub Actions job to complete. + +## Manually (for the adventurous) + +If you are feeling adventurous, you can also create your release artifacts manually. You will need to produce the following artifacts: + +- `terraform-provider-YOURNAME_VERSION_PLATFORM_ARCH.zip` containing your provider binary named `terraform-provider-YOURNAME` or `terraform-provider-YOURNAME.exe` and any supplemental files. (e.g. `terraform-provider-aws_5.68.0_darwin_amd64.zip`) +- `terraform-provider-YOURNAME_SHA256SUMS` containing the SHA256 checksums and filenames for all files in your release, one in each line in the format of ` \n` (e.g. `0501ccb379b74832366860699ca6d5993b164ec44314a054453877d39c384869 terraform-provider-aws_5.68.0_darwin_amd64.zip`) +- `terraform-provider-YOURNAME_SHA256SUMS.sig` containing a detached GPG signature for the SHA256SUMS file (without ASCII-armor). This file is optional for OpenTofu. + +~> The versions in the filenames **must not** contain the `v` prefix. + +OpenTofu supports the following platform names: + +- `darwin` (MacOS) +- `linux` +- `windows` +- `freebsd` +- `openbsd` +- `solaris` + +You can use these in conjunction with the following platform names: + +- `amd64` +- `arm64` +- `386` +- `arm` + +Once you are done, you can [submit your provider to the OpenTofu Registry](/docs/providers/adding) and to the [Terrafom Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing). diff --git a/frontend/docs/sidebar.json b/frontend/docs/sidebar.json index aa2c0e5..462b8f3 100644 --- a/frontend/docs/sidebar.json +++ b/frontend/docs/sidebar.json @@ -21,11 +21,6 @@ "title": "Using a module", "path": "users/modules.md", "slug": "users/modules" - }, - { - "title": "Security", - "path": "users/security.md", - "slug": "users/security" } ] }, @@ -42,21 +37,16 @@ "path": "providers/creating.md", "slug": "providers/creating" }, - { - "title": "Publishing your provider", - "path": "providers/publishing.md", - "slug": "providers/publishing" - }, - { - "title": "Adding GPG signatures", - "path": "providers/gpg.md", - "slug": "providers/gpg" - }, { "title": "Writing docs for your provider", "path": "providers/docs.md", "slug": "providers/docs" }, + { + "title": "Publishing your provider", + "path": "providers/publishing.md", + "slug": "providers/publishing" + }, { "title": "Adding a provider to the registry", "path": "providers/adding.md", diff --git a/frontend/docs/users/security.md b/frontend/docs/users/security.md deleted file mode 100644 index 8215024..0000000 --- a/frontend/docs/users/security.md +++ /dev/null @@ -1 +0,0 @@ -# Security in the OpenTofu Registry