Docs: Add guidelines for contributors #609

mattdot · 2025-03-02T07:34:07Z

This pull request includes updates to the documentation and developer guidelines for the Terraform Provider for Power Platform. The changes aim to provide clearer instructions for contributors and improve the overall structure of the documentation. The most important changes include adding a dynamic configuration guide, enhancing the contribution guidelines, and reorganizing developer resources.

Documentation updates:

.changes/unreleased/documentation-20250303-071315.yaml: Added a dynamic configuration guide to the user documentation.
CONTRIBUTING.md: Reorganized and expanded the contribution guidelines, including a new section on examples and clarifying the process for contributing new resources and data sources.

Developer guidelines:

DEVELOPER.md: Reorganized the developer documentation, added a summary of developer resources, and detailed the developer workflow, including setting up development environments using GitHub Codespaces or local devcontainers.
DEVELOPER.md: Updated the section on testing guidelines to provide detailed instructions on writing unit and acceptance tests, and the importance of comprehensive test coverage.This pull request to the Terraform Provider for Power Platform repository includes significant updates to the CONTRIBUTING.md and DEVELOPER.md files, as well as the addition of new documentation files. The changes aim to improve the contribution guidelines, developer setup instructions, and testing practices. The most important changes include restructuring the contribution types, enhancing developer resource documentation, and adopting httpmock for unit testing.

Contribution Guidelines and Examples:

CONTRIBUTING.md: Restructured the contribution types section to clarify the difficulty levels of different contributions and added detailed examples for contributing to the Power Platform Terraform Provider.

Developer Setup and Resources:

DEVELOPER.md: Enhanced the documentation by adding a comprehensive summary of developer resources, including guidelines for testing, security, schema design, and community support. Introduced two recommended development environment options: GitHub Codespaces and Local Devcontainer.
DEVELOPER.md: Provided detailed instructions for setting up and configuring Git credentials in both GitHub Codespaces and Local Devcontainer environments.

Decision Logs and Testing:

decision-log/loosely_typed_resources.md: Removed the decision log for loosely typed resources, which outlined the rationale and comparison between strongly typed and loosely typed resources in the Terraform Provider for Power Platform.
devdocs/adr/httpmocks.md: Added a new ADR document detailing the adoption of httpmock for HTTP request mocking in unit tests, highlighting the benefits and implementation guidelines for improved test reliability and determinism.This pull request includes several documentation updates and additions to improve clarity and support for developers and users of the Terraform Provider for Power Platform. The most important changes are summarized below:

Documentation Updates:

Decision Log Removal:
- Removed the decision log outlining the rationale for implementing loosely typed Terraform resources in decision-log/loosely_typed_resources.md.
New ADR Document:
- Added a new ADR document summarizing the rationale and benefits of loosely typed Terraform resources, specifically powerplatform_data_record and powerplatform_data_records in devdocs/adr/loosely_typed_data_records.md.
Community Support Documentation:
- Added a comprehensive community support document including FAQs, developer support channels, and best practices for working with maintainers in devdocs/community_support.md.
Observability and Logging Guidelines:
- Introduced guidelines for observability and logging, emphasizing the use of HashiCorp’s tflog package for structured logging and the importance of not logging sensitive information in devdocs/observability_guidelines.md.

DEVELOPER.md

devdocs/adr/httpmocks.md

devdocs/testing_guidelines.md

…d streamline contribution process

ianjensenisme

Minor updates requested

CONTRIBUTING.md

devdocs/adr/httpmocks.md

devdocs/community_support.md

ianjensenisme · 2025-03-03T20:52:45Z

devdocs/schema_guidelines.md

+
+## Naming Attributes
+
+Attribute naming should closely mirror terminology used by the Power Platform API or the Power Platform Admin Center UI. When discrepancies exist due to feature renaming or updates, choose the modern, user-recognizable term. For instance, prefer Dataverse instead of older, deprecated terminology like CDS to ensure users familiar with current platform features easily understand the schema.


"modern" and "user-recognizable" are sometimes contradictory. Example: Our Managed Identity references should really be abbreviated "MI" (matching the modern name), but the "user-recognizable" naming could be "MSI". Do we have any guidance to tip the scale in a conflict? In the above example we went with user-recognizable, but I wonder if it's always that clear.

l think it's a judgement call at that point.

I guess what I'm getting at is that what we're really doing is going with what we see in other providers, even if it's antiquated terminology. Maybe add a note to that effect: "when in doubt, look at what other providers have done"

Co-authored-by: Ian Jensen <94021216+ianjensenisme@users.noreply.github.com>

mawasile · 2025-03-05T08:15:14Z

devdocs/community_support.md

+
+### Q: Can I develop on this provider without using the VS Code Dev Container?
+
+**A:** It's not recommended to develop this provider outside the provided Dev Container. GitHub Codespaces is the preferred environment due to consistency, controlled dependencies, and reproducibility. Using the Dev Container locally is acceptable, but manually setting up a local environment can introduce risks such as mismatched dependencies, version conflicts, and environmental inconsistencies that could complicate development and troubleshooting.


i disagree with that sentence, technically local container is the same thing. Its just ootb git integration are missing.

I try the local dev container and doesn't work, I will create one Issues to make it work.

the last part of the sentence is supposed to be about not using the devcontainer. It says devcontainer locally is fine.

devdocs/community_support.md

mawasile · 2025-03-05T08:22:12Z

devdocs/schema_guidelines.md

+- **SingleNested Blocks:** Used for singular configurations, such as Dataverse settings within the `powerplatform_environment` resource, grouping attributes like `language_code`, `currency_code`, and `security_group_id`.
+- **SetNested or ListNested Blocks:** Used for repeatable structures, such as multiple connector references or multiple similar configurations.
+
+Avoid overly deep nesting. Clearly represent resource or data source structure without unnecessary complexity.


I would add more info about judgment, how to structure a new resource. Right now if something has a complex structure like for example env settings, we try to follow the ppac UI in our schema.

eduardodfmex

Thank you for creating and extending the documentation..!
I add a couple of suggestions.

DEVELOPER.md

eduardodfmex · 2025-03-05T22:42:55Z

devdocs/community_support.md

+
+### Q: Can I develop on this provider without using the VS Code Dev Container?
+
+**A:** It's not recommended to develop this provider outside the provided Dev Container. GitHub Codespaces is the preferred environment due to consistency, controlled dependencies, and reproducibility. Using the Dev Container locally is acceptable, but manually setting up a local environment can introduce risks such as mismatched dependencies, version conflicts, and environmental inconsistencies that could complicate development and troubleshooting.


I try the local dev container and doesn't work, I will create one Issues to make it work.

devdocs/community_support.md

devdocs/testing_guidelines.md

CONTRIBUTING.md

…ules for resources and data sources

…nd streamlining instructions

Co-authored-by: mawasile <50197777+mawasile@users.noreply.github.com>

Co-authored-by: Eduardo Sanchez <eduardodfmex@hotmail.com>

…it reminders

…thub.com/microsoft/terraform-provider-power-platform into 608-developer-documentation-improvements

…e files

…rm Provider

…ta structures

Docs: Add guidelines for contributors

42b0f7b

mattdot linked an issue Mar 2, 2025 that may be closed by this pull request

Developer documentation improvements #608

Open

19 tasks

mattdot added skip-changelog documentation Improvements or additions to documentation developer experience labels Mar 2, 2025

mattdot self-assigned this Mar 2, 2025

github-actions[bot] added 4 commits March 2, 2025 21:44

adding adrs and user docs

e6a4f2e

Docs: Update contributing guidelines with examples and resource details

d3c650d

Docs: Add feature request guidelines for the Terraform Provider

e461a43

Docs: Add dynamic configuration guide to user documentation

3a06fd2

mattdot removed the skip-changelog label Mar 3, 2025

Merge branch 'main' into 608-developer-documentation-improvements

e0fbbe7

mattdot marked this pull request as ready for review March 3, 2025 07:56

mattdot requested review from mawasile, leighatami, ianjensenisme, polatengin and eduardodfmex as code owners March 3, 2025 07:56

mawasile reviewed Mar 3, 2025

View reviewed changes

Docs: Update developer documentation to reflect precommit commands an…

679efe2

…d streamline contribution process

ianjensenisme reviewed Mar 3, 2025

View reviewed changes

Update devdocs/community_support.md

369036c

Co-authored-by: Ian Jensen <94021216+ianjensenisme@users.noreply.github.com>

mawasile reviewed Mar 5, 2025

View reviewed changes

devdocs/community_support.md Outdated Show resolved Hide resolved

mawasile reviewed Mar 5, 2025

View reviewed changes

devdocs/community_support.md Show resolved Hide resolved

mawasile reviewed Mar 5, 2025

View reviewed changes

devdocs/community_support.md Outdated Show resolved Hide resolved

mawasile reviewed Mar 5, 2025

View reviewed changes

mawasile previously approved these changes Mar 5, 2025

View reviewed changes

eduardodfmex reviewed Mar 5, 2025

View reviewed changes

eduardodfmex reviewed Mar 6, 2025

View reviewed changes

devdocs/testing_guidelines.md Show resolved Hide resolved

CONTRIBUTING.md Show resolved Hide resolved

github-actions[bot] added 2 commits March 6, 2025 02:41

Docs: Update issue templates to include user stories and validation r…

4fa2b9a

…ules for resources and data sources

Docs: Simplify bug report template by removing unnecessary sections a…

72edb02

…nd streamlining instructions

mattdot dismissed mawasile’s stale review via 72edb02 March 6, 2025 02:44

mattdot and others added 10 commits March 5, 2025 23:45

Update devdocs/community_support.md

05b5c3d

Co-authored-by: mawasile <50197777+mawasile@users.noreply.github.com>

Update devdocs/community_support.md

fff0adf

Co-authored-by: mawasile <50197777+mawasile@users.noreply.github.com>

Update DEVELOPER.md

0f5f761

Co-authored-by: Eduardo Sanchez <eduardodfmex@hotmail.com>

Update DEVELOPER.md

cf82509

Co-authored-by: Eduardo Sanchez <eduardodfmex@hotmail.com>

Docs: Update issue templates to include changelog entries and precomm…

5234808

…it reminders

Merge branch '608-developer-documentation-improvements' of https://gi…

e672781

…thub.com/microsoft/terraform-provider-power-platform into 608-developer-documentation-improvements

Docs: Improve clarity and consistency in documentation across multipl…

f27449c

…e files

resource playbook

f44b008

Docs: Add Terraform resource implementation template for Power Platfo…

f0b6fa4

…rm Provider

Docs: Update resource prompt to prefer sets over lists for complex da…

5e9591b

…ta structures

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add guidelines for contributors #609

Docs: Add guidelines for contributors #609

mattdot commented Mar 2, 2025 •

edited

Loading

ianjensenisme left a comment

ianjensenisme Mar 3, 2025

mattdot Mar 4, 2025

ianjensenisme Mar 6, 2025

mawasile Mar 5, 2025

eduardodfmex Mar 5, 2025

mattdot Mar 6, 2025

mawasile Mar 5, 2025

eduardodfmex left a comment

eduardodfmex Mar 5, 2025


		## Naming Attributes

		Attribute naming should closely mirror terminology used by the Power Platform API or the Power Platform Admin Center UI. When discrepancies exist due to feature renaming or updates, choose the modern, user-recognizable term. For instance, prefer Dataverse instead of older, deprecated terminology like CDS to ensure users familiar with current platform features easily understand the schema.


		### Q: Can I develop on this provider without using the VS Code Dev Container?

		A: It's not recommended to develop this provider outside the provided Dev Container. GitHub Codespaces is the preferred environment due to consistency, controlled dependencies, and reproducibility. Using the Dev Container locally is acceptable, but manually setting up a local environment can introduce risks such as mismatched dependencies, version conflicts, and environmental inconsistencies that could complicate development and troubleshooting.

Docs: Add guidelines for contributors #609

Are you sure you want to change the base?

Docs: Add guidelines for contributors #609

Conversation

mattdot commented Mar 2, 2025 • edited Loading

Contribution Guidelines and Examples:

Developer Setup and Resources:

Decision Logs and Testing:

Documentation Updates:

ianjensenisme left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eduardodfmex left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mattdot commented Mar 2, 2025 •

edited

Loading