Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add guidelines for contributors #609

Merged
merged 21 commits into from
Mar 6, 2025

Conversation

mattdot
Copy link
Member

@mattdot mattdot commented Mar 2, 2025

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:

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.

@mattdot mattdot linked an issue Mar 2, 2025 that may be closed by this pull request
19 tasks
@mattdot mattdot added skip-changelog documentation Improvements or additions to documentation developer experience labels Mar 2, 2025
@mattdot mattdot self-assigned this Mar 2, 2025
@mattdot mattdot marked this pull request as ready for review March 3, 2025 07:56
Copy link
Contributor

@ianjensenisme ianjensenisme left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor updates requested

Co-authored-by: Ian Jensen <94021216+ianjensenisme@users.noreply.github.com>
mawasile
mawasile previously approved these changes Mar 5, 2025
Copy link
Contributor

@eduardodfmex eduardodfmex left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

github-actions[bot] added 2 commits March 6, 2025 02:41
@mattdot mattdot merged commit e28d336 into main Mar 6, 2025
10 checks passed
@mattdot mattdot deleted the 608-developer-documentation-improvements branch March 6, 2025 21:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
developer experience documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Developer documentation improvements
5 participants