docs: Update repository collaborators resource docs

.rumdl.toml

@@ -3,7 +3,7 @@ disable = ["MD013", "MD028"]
 
 [per-file-ignores]
 ".github/pull_request_template.md" = ["MD041"]
-"docs/**/*.md" = ["MD059"]
+"docs/**/*.md" = ["MD012", "MD022", "MD059"]
 
 [MD004]
 style = "dash"

docs/resources/repository_collaborators.md

@@ -1,24 +1,41 @@
 ---
 page_title: "github_repository_collaborators (Resource) - GitHub"
+subcategory: ""
 description: |-
-  Provides a GitHub repository collaborators resource.
+  Manage the complete set of collaborators (users and teams) for a GitHub repository.
 ---
 
 # github_repository_collaborators (Resource)
 
-Provides a GitHub repository collaborators resource.
+Manage the complete set of collaborators (users and teams) for a GitHub repository.
 
-~> Note: github_repository_collaborators cannot be used in conjunction with github_repository_collaborator and github_team_repository or they will fight over what your policy should be.
+~> This resource (`github_repository_collaborators`) cannot be used in conjunction with [`github_repository_collaborator`](repository_collaborator) or [`github_team_repository`](team_repository) as they will conflict over the management of collaborators.
 
-This resource allows you to manage all collaborators for repositories in your organization or personal account. For organization repositories, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership. For personal repositories, collaborators can only be granted write (implicitly includes read) permission.
+This resource manages the complete set of collaborators for a repository, which includes both users and teams, in an authoritative manner. When applied, the provider will ensure that the set of collaborators for the repository matches the set defined in Terraform configuration. This means that if a collaborator is removed from the configuration, it will be removed from the repository, and if a collaborator is added to the configuration, it will be added to the repository.
 
-When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository.
+~> **Archived Repositories** When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository.
+
+## Organization Repositories
+
+For repositories owned by an organization, collaborators can have explicit (and differing levels of) read, write, or administrator access to specific repositories, without giving the user full organization membership.
+
+### Teams
+
+Teams will be added to the repository on apply, and removed if removed from the configuration or on destroy. Teams added to the repository outside of Terraform can be managed by adding them to the configuration, or ignored by using the `ignore_team` argument. This is particularly important for organization/enterprise teams, which either need to be added to the configuration or ignored, as otherwise they will cause perpetual drift.
+
+## Personal Repositories
+
+For personal repositories, collaborators can only be granted [write](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) permission.
+
+!> If the repository owner is not added as a collaborator with admin access, the provider will churn this resource on every plan/apply. To prevent this, ensure that the repository owner is included in the set of user collaborators.
+
+## Users
 
-~> **Note on Archived Repositories**: When a repository is archived, GitHub makes it read-only, preventing collaborator modifications. If you attempt to destroy resources associated with archived repositories, the provider will gracefully handle the operation by logging an informational message and removing the resource from Terraform state without attempting to modify the archived repository.
+When applied, an invitation will be sent to the user to become a collaborators on a repository. When destroyed, either the invitation will be cancelled or the collaborators will be removed from the repository.
 
-This resource is authoritative. For adding a collaborator to a repo in a non-authoritative manner, use github_repository_collaborator instead.
+## Documentation
 
-Further documentation on GitHub collaborators:
+Further documentation on GitHub collaborators.
 
 - [Adding outside collaborators to your personal repositories](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories)
 - [Adding outside collaborators to repositories in your organization](https://help.github.com/articles/adding-outside-collaborators-to-repositories-in-your-organization/)
@@ -52,39 +69,52 @@ resource "github_repository_collaborators" "some_repo_collaborators" {
 }
 ```
 
-## Argument Reference
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-The following arguments are supported:
+### Required
 
-- `repository` - (Required) The GitHub repository.
-- `user` - (Optional) List of users to grant access to the repository.
-- `team` - (Optional) List of teams to grant access to the repository.
-- `ignore_team` - (Optional) List of teams to ignore when checking for repository access. This supports ignoring teams granted access at an organizational level.
+- `repository` (String) Name of the repository.
 
-The `user` block supports:
+### Optional
 
-- `username` - (Required) The user to add to the repository as a collaborator.
-- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `push`, `maintain`, `triage` or `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization for organization-owned repositories. Must be `push` for personal repositories. Defaults to `push`.
+- `ignore_team` (Block Set) Teams to ignore when managing repository collaborators. (see [below for nested schema](#nestedblock--ignore_team))
+- `team` (Block Set) Teams to grant access to the repository. (see [below for nested schema](#nestedblock--team))
+- `user` (Block Set) Users to grant access to the repository. (see [below for nested schema](#nestedblock--user))
 
-The `team` block supports:
+### Read-Only
 
-- `team_id` - (Required) The GitHub team id or the GitHub team slug.
-- `permission` - (Optional) The permission of the outside collaborators for the repository. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organisation. Defaults to `pull`. Must be `push` for personal repositories. Defaults to `push`.
+- `id` (String) The ID of this resource.
+- `invitation_ids` (Map of String) Map of usernames to invitation ID for users that haven't yet accepted their invitation to become a collaborator. This is only set on read, and is used internally to track pending invitations for users that aren't yet collaborators.
+- `repository_id` (Number) ID of the repository.
 
-The `ignore_team` block supports:
+<a id="nestedblock--ignore_team"></a>
+### Nested Schema for `ignore_team`
 
-- `team_id` - (Required) The GitHub team id or the GitHub team slug.
+Required:
 
-## Attribute Reference
+- `team_id` (String) ID or slug of the team to ignore.
 
-In addition to the above arguments, the following attributes are exported:
 
-- `invitation_ids` - Map of usernames to invitation ID for any users added as part of creation of this resource to be used in `github_user_invitation_accepter`.
+<a id="nestedblock--team"></a>
+### Nested Schema for `team`
 
-## Import
+Required:
 
-GitHub Repository Collaborators can be imported using the name `name`, e.g.
+- `team_id` (String) ID or slug of the team to add to the repository as a collaborator.
 
-```shell
-terraform import github_repository_collaborators.collaborators terraform
-```
+Optional:
+
+- `permission` (String) Permission to grant to the team. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Defaults to `push`.
+
+
+<a id="nestedblock--user"></a>
+### Nested Schema for `user`
+
+Required:
+
+- `username` (String) Login for the user to add to the repository as a collaborator.
+
+Optional:
+
+- `permission` (String) Permission to grant to the user. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Must be `push` for personal repositories. Defaults to `push`.

github/resource_github_repository_collaborators.go

@@ -27,6 +27,8 @@ func resourceGithubRepositoryCollaborators() *schema.Resource {
 			},
 		},
 
+		Description: "Manage the complete set of collaborators (users and teams) for a GitHub repository.",
+
 		CreateContext: resourceGithubRepositoryCollaboratorsCreate,
 		ReadContext:   resourceGithubRepositoryCollaboratorsRead,
 		UpdateContext: resourceGithubRepositoryCollaboratorsUpdate,
@@ -49,45 +51,47 @@ func resourceGithubRepositoryCollaborators() *schema.Resource {
 			"user": {
 				Type:        schema.TypeSet,
 				Optional:    true,
-				Description: "List of users.",
+				Description: "Users to grant access to the repository.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"username": {
 							Type:             schema.TypeString,
-							Description:      "(Required) The user to add to the repository as a collaborator.",
+							Description:      "Login for the user to add to the repository as a collaborator.",
 							Required:         true,
 							DiffSuppressFunc: caseInsensitive(),
 						},
 						"permission": {
-							Type:     schema.TypeString,
-							Optional: true,
-							Default:  "push",
+							Type:        schema.TypeString,
+							Description: "Permission to grant to the user. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Must be `push` for personal repositories. Defaults to `push`.",
+							Optional:    true,
+							Default:     "push",
 						},
 					},
 				},
 			},
 			"team": {
 				Type:        schema.TypeSet,
 				Optional:    true,
-				Description: "List of teams.",
+				Description: "Teams to grant access to the repository.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"team_id": {
 							Type:        schema.TypeString,
-							Description: "Team ID or slug to add to the repository as a collaborator.",
+							Description: "ID or slug of the team to add to the repository as a collaborator.",
 							Required:    true,
 						},
 						"permission": {
-							Type:     schema.TypeString,
-							Optional: true,
-							Default:  "push",
+							Type:        schema.TypeString,
+							Description: "Permission to grant to the team. Must be one of `pull`, `triage`, `push`, `maintain`, `admin` or the name of an existing [custom repository role](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) within the organization. Defaults to `push`.",
+							Optional:    true,
+							Default:     "push",
 						},
 					},
 				},
 			},
 			"invitation_ids": {
 				Type:        schema.TypeMap,
-				Description: "Map of usernames to invitation ID for any users added",
+				Description: "Map of usernames to invitation ID for users that haven't yet accepted their invitation to become a collaborator. This is only set on read, and is used internally to track pending invitations for users that aren't yet collaborators.",
 				Elem: &schema.Schema{
 					Type: schema.TypeString,
 				},
@@ -96,7 +100,7 @@ func resourceGithubRepositoryCollaborators() *schema.Resource {
 			"ignore_team": {
 				Type:        schema.TypeSet,
 				Optional:    true,
-				Description: "List of teams to ignore.",
+				Description: "Teams to ignore when managing repository collaborators.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"team_id": {