docs: *_invitation life cycle clarification

[morey-tech]

Description

Update the docs to clarify how the lifecycle of the org_invitation and project_invitation resources work. Indicating that once the invite is accepted the resource is deleted.

Link to any related issue(s):

#633 (comment)

Type of change:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Documentation fix/enhancement

Required Checklist:

• I have signed the MongoDB CLA
• I have read the Terraform contribution guidelines
• I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
• I have added any necessary documentation (if appropriate)
• I have run make fmt and formatted my code

Further comments

[themantissa]

@morey-tech thank you for the submission. We do have a statement in these docs pages about how invitations work:

NOTE: Possible provider behavior depending on the invitee's action:

• If the user has not yet accepted the invitation, the provider leaves the invitation as is.
• If the user has accepted the invitation and is now an organization member, the provider will remove the invitation from the Terraform state. The invitation must then be removed from the Terraform resource configuration.
• If the user accepts the invitation and then leaves the organization, the provider will re-add the invitation if the resource definition is not removed from the Terraform configuration.

What if we move this up and better clarify some of the points you are making this this PR do you think that will be a bit better? This obviously is an area that needs better clarification.

[morey-tech]

@morey-tech thank you for the submission. We do have a statement in these docs pages about how invitations work:

NOTE: Possible provider behavior depending on the invitee's action:

• If the user has not yet accepted the invitation, the provider leaves the invitation as is.
• If the user has accepted the invitation and is now an organization member, the provider will remove the invitation from the Terraform state. The invitation must then be removed from the Terraform resource configuration.
• If the user accepts the invitation and then leaves the organization, the provider will re-add the invitation if the resource definition is not removed from the Terraform configuration.

What if we move this up and better clarify some of the points you are making this PR do you think that will be a bit better? This obviously is an area that needs better clarification.

Thanks for pointing that out! I agree that moving it up is important to bring it to the user's attention earlier. This is also typical of resources that may behave differently than a user might assume (i.e., being removed from the state outside without the resource needing to be destroyed). I also think including these notes in the project_invite resource docs and not only the org_invite would be helpful.

I have updated the PR to integrate the existing note in the org_invitiation docs into the changes I am proposing. Please let me know what you think.

[themantissa]

Just a small adjustment to make this a bit more clear.

[themantissa]

Thanks again @morey-tech ! These changes will go out with our next release.