mmv1/docs: move write-only arguments into arguments section

[BBBmau]

This updates the generation of docs to remove the ephemeral attributes section in favor of having it be part of the arguments section to prevent any more confusion in the future. It also includes overall improvements to the doc generation for write-only arguments such as:

• removing duplication in write-only field description generation
• use of appropriate naming for write-only fields (write-only arguments)
  • This isn't changed across the entire provider since write-only attributes exist within ephemeral resources
• consistent note used at top of resource documentation to better align with other providers

Ideally i would've liked to have the write-only field be grouped with its original field, though this would take much more work to do. I've included a Note that mentions the need to only set one field wo or non-wo to resolve this.

Fixes hashicorp/terraform-provider-google#24702

Release Note Template for Downstream PRs (will be copied)

See Write release notes for guidance.

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1339
Passed tests: 1251
Skipped tests: 88
Affected tests: 0

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

🟢 All tests passed!

View the build log

[github-actions]

@melinath This PR has been waiting for review for 3 weekdays. Please take a look! Use the label disable-review-reminders to disable these notifications.

[ramonvermeulen]

Couple of small typos, for the rest LGTM.

[ramonvermeulen]

• This isn't changed across the entire provider since write-only attributes exist within ephemeral resources

Could you elaborate a bit on this one, what is a write-only attribute within the context of an ephemeral resource?

[github-actions]

@GoogleCloudPlatform/terraform-team @melinath This PR has been waiting for review for 1 week. Please take a look! Use the label disable-review-reminders to disable these notifications.

[melinath]

won't we never reach this line, because if $.Required is true we'll always do the previous line?

I wonder if it's time for us to make a helper method on the Type that returns the list of things that go in parentheses (which we can format without knowing what each individual item means) instead of trying to build the string in the template like this.

Somewhat related: hashicorp/terraform-provider-google#18832 (Not saying that we need to fix that whole issue here or anything, but it could be relevant to consider when looking at potential solutions.)

[BBBmau]

latest commit refactors this to include the ,WriteOnly generation nested within if $.Required

I'll look into that as I agree with how we'll want to handle the documentation generation of the type of field (Required, Optional, Write-only, etc.)

[BBBmau]

read through your recent review, what i'll do is remove the code that involves the parantheses logic and just leave logic that involves moving it into the arguments section.

I'll follow up with a PR that introduces the helper function that you mention here

[melinath]

It looks like the idea here is that the terraform name is the write-only field's name, while the underscore $.ApiName will be the "original field's" name. However, that won't be the case if the original field's terraform name doesn't match underscore $.ApiName. We'd always match the original field's terraform name + _wo so how about just trimming off the last three characters here?

The longer fix here would be to document all exactlyOneOf / conflicts constraints automatically - which might actually be feasible if we had a central registry as described in hashicorp/terraform-provider-google#24327 (comment). But that's out of scope for this PR.

[melinath]

This list is out of date. We probably should delete it / restructure this... but that can happen separately.

[BBBmau]

agreed, noticed that we'd want to address how we handle this page from reviewing:

• Add ephemeral google_client_config resource #15099 (review)

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1251
Skipped tests: 88
Affected tests: 1

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

Action taken

Found 1 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update

Get to know how VCR tests work

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1251
Skipped tests: 88
Affected tests: 1

Click here to see the affected service packages

• secretmanager
• bigquerydatatransfer
• compute

Action taken

Found 1 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update

Get to know how VCR tests work

[modular-magician]

🟢 Tests passed during RECORDING mode:
TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update [Debug log]

🟢 No issues found for passed tests after REPLAYING rerun.

---

🟢 All tests passed!

View the build log or the debug log for each test

[modular-magician]

🟢 Tests passed during RECORDING mode:
TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update [Debug log]

🟢 No issues found for passed tests after REPLAYING rerun.

---

🟢 All tests passed!

View the build log or the debug log for each test

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1252
Skipped tests: 88
Affected tests: 0

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

🟢 All tests passed!

View the build log

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1251
Skipped tests: 88
Affected tests: 1

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

Action taken

Found 1 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update

Get to know how VCR tests work

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1252
Skipped tests: 88
Affected tests: 0

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

🟢 All tests passed!

View the build log

[modular-magician]

🟢 Tests passed during RECORDING mode:
TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update [Debug log]

🟢 No issues found for passed tests after REPLAYING rerun.

---

🟢 All tests passed!

View the build log or the debug log for each test

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))
google-beta provider: Diff ( 12 files changed, 52 insertions(+), 84 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1340
Passed tests: 1252
Skipped tests: 88
Affected tests: 0

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

🟢 All tests passed!

View the build log

[github-actions]

@BBBmau, this PR is waiting for action from you. If no action is taken, this PR will be closed in 28 days.

Please address any comments or change requests, or re-request review from a core reviewer if no action is required.

This notification can be disabled with the disable-automatic-closure label.

[ramonvermeulen]

@melinath @BBBmau

Let me know if there is anything I can do to move forward with this PR, or take it over in case you're busy. Currently I let #15393 depend on this change, so waiting for this documentation updates/standardizations to get merged first.

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 39 files changed, 48 insertions(+), 120 deletions(-))
google-beta provider: Diff ( 39 files changed, 48 insertions(+), 120 deletions(-))
terraform-google-conversion: Diff ( 1 file changed, 2 insertions(+), 2 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1348
Passed tests: 1259
Skipped tests: 87
Affected tests: 2

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

Action taken

Found 2 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeFutureReservation_sharedFutureReservationExample
• TestAccComputeReservation_reservationSharingPolicyExample

Get to know how VCR tests work

[modular-magician]

Tests analytics

Total tests: 1348
Passed tests: 1258
Skipped tests: 87
Affected tests: 3

Click here to see the affected service packages

• secretmanager
• bigquerydatatransfer
• compute

Action taken

Found 3 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeFutureReservation_sharedFutureReservationExample
• TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update
• TestAccComputeReservation_reservationSharingPolicyExample

Get to know how VCR tests work

[modular-magician]

🔴 Tests failed during RECORDING mode:
TestAccComputeFutureReservation_sharedFutureReservationExample [Error message] [Debug log]
TestAccComputeReservation_reservationSharingPolicyExample [Error message] [Debug log]

🔴 Errors occurred during RECORDING mode. Please fix them to complete your PR.

View the build log or the debug log for each test

[modular-magician]

🟢 Tests passed during RECORDING mode:
TestAccComputeRegionBackendService_regionBackendServiceHaPolicyManualLeader_update [Debug log]

🟢 No issues found for passed tests after REPLAYING rerun.

---

🔴 Tests failed during RECORDING mode:
TestAccComputeFutureReservation_sharedFutureReservationExample [Error message] [Debug log]
TestAccComputeReservation_reservationSharingPolicyExample [Error message] [Debug log]

🔴 Errors occurred during RECORDING mode. Please fix them to complete your PR.

View the build log or the debug log for each test

[modular-magician]

Tests analytics

Total tests: 1348
Passed tests: 1259
Skipped tests: 87
Affected tests: 2

Click here to see the affected service packages

• secretmanager
• bigquerydatatransfer
• compute

Action taken

Found 2 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeFutureReservation_sharedFutureReservationExample
• TestAccComputeReservation_reservationSharingPolicyExample

Get to know how VCR tests work

[modular-magician]

🔴 Tests failed during RECORDING mode:
TestAccComputeFutureReservation_sharedFutureReservationExample [Error message] [Debug log]
TestAccComputeReservation_reservationSharingPolicyExample [Error message] [Debug log]

🔴 Errors occurred during RECORDING mode. Please fix them to complete your PR.

View the build log or the debug log for each test

[melinath]

This should be based on name, not ApiName (because the terraform name of the field might be different). I think this is the right logic but could be worth double-checking locally. (This doesn't seem to impact any current fields, but we might as well make sure it's doing the right thing now.)

Suggested change

	* ~> **Note:** One of `{{ underscore $.ApiName }}` or `{{ underscore $.ApiName }}_wo` can only be set.
	* ~> **Note:** One of `{{ slice (underscore $.Name) (sub (len underscore $.Name) 3) }}` or `{{ underscore $.Name }}` can only be set.

[BBBmau]

ran this and didn't quite work, this is the updated logic:

  * ~> **Note:** One of `{{ slice (underscore $.Name) 0 (sub (len (underscore $.Name)) 3) }}` or `{{ underscore $.Name }}` can only be set.

[melinath]

💯 thanks!

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 48 insertions(+), 80 deletions(-))
google-beta provider: Diff ( 12 files changed, 48 insertions(+), 80 deletions(-))
terraform-google-conversion: Diff ( 1 file changed, 2 insertions(+), 2 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1348
Passed tests: 1260
Skipped tests: 87
Affected tests: 1

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

Action taken

Found 1 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeFutureReservation_sharedFutureReservationExample

Get to know how VCR tests work

[modular-magician]

🔴 Tests failed during RECORDING mode:
TestAccComputeFutureReservation_sharedFutureReservationExample [Error message] [Debug log]

🔴 Errors occurred during RECORDING mode. Please fix them to complete your PR.

View the build log or the debug log for each test

[melinath]

One more small formatting fix, sorry for not catching this last time! I think this is the last one though. Feel free to ignore the nit.

[melinath]

nit: It's a little weird to have these two notes right after each other. This isn't a blocker, especially since the second note will be a whole callout block.

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

google provider: Diff ( 12 files changed, 48 insertions(+), 80 deletions(-))
google-beta provider: Diff ( 12 files changed, 48 insertions(+), 80 deletions(-))
terraform-google-conversion: Diff ( 1 file changed, 2 insertions(+), 2 deletions(-))

Missing test report

Your PR includes resource fields which are not covered by any test.

Resource: google_bigquery_data_transfer_config (12 total tests)
Please add an acceptance test which includes these fields. The test should include the following:

resource "google_bigquery_data_transfer_config" "primary" {
  sensitive_params {
    secret_access_key_wo_version = # value needed
  }
}

[modular-magician]

Tests analytics

Total tests: 1349
Passed tests: 1260
Skipped tests: 87
Affected tests: 2

Click here to see the affected service packages

• bigquerydatatransfer
• compute
• secretmanager

Action taken

Found 2 affected test(s) by replaying old test recordings. Starting RECORDING based on the most recent commit. Click here to see the affected tests

• TestAccComputeFutureReservation_sharedFutureReservationExample
• TestAccComputeRegionBackendService_withNetworkPassThroughLbTrafficPolicy

Get to know how VCR tests work

[modular-magician]

🟢 Tests passed during RECORDING mode:
TestAccComputeRegionBackendService_withNetworkPassThroughLbTrafficPolicy [Debug log]

🔴 Tests failed when rerunning REPLAYING mode:
TestAccComputeRegionBackendService_withNetworkPassThroughLbTrafficPolicy [Error message] [Debug log]

Tests failed due to non-determinism or randomness when the VCR replayed the response after the HTTP request was made.

Please fix these to complete your PR. If you believe these test failures to be incorrect or unrelated to your change, or if you have any questions, please raise the concern with your reviewer.

---

🔴 Tests failed during RECORDING mode:
TestAccComputeFutureReservation_sharedFutureReservationExample [Error message] [Debug log]

🔴 Errors occurred during RECORDING mode. Please fix them to complete your PR.

View the build log or the debug log for each test