Suggestion - Developer docs/changelog

[hbuckle]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

As the number of contributors to the provider grows I think it would be useful to have some provider specific documentation for development.
This could cover things like Azure specific validators and helpers, registering clients and common patterns for working with the Azure API (such as locking subnets and vnets before updating).

It could also be handy to have a developer specific changelog covering internal changes (like the upcoming requiring imports thing) detailing what's changing and why.

I'd be happy to help out with writing down some of the things I've picked up so far.

Thoughts?

[tombuildsstuff]

hey @hbuckle

Thanks for opening this issue :)

As the number of contributors to the provider grows I think it would be useful to have some provider specific documentation for development.
This could cover things like Azure specific validators and helpers, registering clients and common patterns for working with the Azure API (such as locking subnets and vnets before updating).
It could also be handy to have a developer specific changelog covering internal changes (like the upcoming requiring imports thing) detailing what's changing and why.

I general I think this is a good idea (and it's something we've been trying to do for a while) - for the moment we've been focused on trying to get the foundation for this done (which is applicable to all Terraform Providers) in the form of this documentation on the Terraform Website, rather than something specific to a Provider (e.g. Azure).

Whilst I believe we should look to add something for this, the question's more when we do that; from our side we're working through some larger internal changes at the moment both with regards to tooling (e.g. adding Linters to try and catch the common review points / switching to Go Modules) and with regards to the structure of the codebase (e.g. we've recently pulled the auth logic out into the github.com/hashicorp/go-azure-helpers package) such that there could be some churn here; as such I'm wondering if it'd make more sense to hold off documenting the low-level components until 2.0 has been released here (and things are a bit more settled).

That said - I think there's two distinct things here worth clarifying:

• Major feature changes (e.g. see the proposal for AzureAD in [Proposal] 2.0 - Azure Active Directory #2322) - which we want to start doing more of as GitHub Issues (which we can pin)

• Developer docs/guide/questions - where we want to document most of the things you've mentioned. Common patterns can be a little challenging to document given the API can vary depending on the API being consumed - but I'd suggest we include:

  • most, but not all Azure API's return the representation of the resource at the last time it was modified (rather than right now) meaning that fields defined in the API/Schema aren't necessarily present, which means we need to code defensively to handle this.
  • the Azure API documentation states that Resource Group names (and Resource ID's) should be handled in a case-insensitive manner - however there's enough API's that require the casing to match that this means we end up having to treat both as case sensitive

WDYT?

I'd be happy to help out with writing down some of the things I've picked up so far.

That'd be awesome if wouldn't mind - I'd suggest we place this in a README-Contributor-Docs.md (or something similar in the root of the repo?

---

@metacpp

Maybe GitHub Wiki is a good place for it. A good examle: https://github.com/golang/go/wiki

In my experience Wiki's almost always fall out of sync with reality - IMO this would be better as a file in the repo, this also has the additional benefit that it's on everybody's local machine when they clone the repo (among being able to PR changes etc), but should still be as visible

I would recommend that we provide clear information in each git commit message, and use tool to generate dev-specific changelog.

The "developer specific changelog" mentioned above is more for what's changing in development land (e.g. switching to Go modules) - rather than a commit-by-commit changelog (which we have the product/feature changelog in the form of changelog.md) - as such I don't believe this would help?

Thanks!

[tombuildsstuff]

Fixed by #16732 / these are now available in the contributing folder: https://github.com/hashicorp/terraform-provider-azurerm/tree/main/contributing

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.