Skip to main content
Thanks for considering contributing to this project! We are glad you are reading this, because we need volunteer developers to help this project reach its full potential.
Please note we have a code of conduct. Please follow it in all your interactions with the project.

​
Ways to Contribute

There are many ways to contribute to the project:

Report Bugs

File issues for bugs, errors, or unexpected behavior

Request Features

Suggest new resources, data sources, or improvements

Improve Documentation

Fix typos, add examples, or clarify existing docs

Contribute Code

Implement new resources, fix bugs, or improve performance

Write Tests

Add unit tests, acceptance tests, or improve test coverage

Answer Questions

Help other users in GitHub issues or Discord

​
Getting Started

​
Prerequisites

Before you start contributing, ensure you have:
  • Go 1.21+ installed
  • Terraform 1.5+ installed
  • Git for version control
  • A Microsoft 365 tenant with appropriate permissions for testing
  • Familiarity with Terraform and Go programming

​
Setting Up Your Development Environment

1

Fork the Repository

Fork the terraform-provider-microsoft365 repository to your GitHub account.
2

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/terraform-provider-microsoft365.git
cd terraform-provider-microsoft365
3

Add Upstream Remote

git remote add upstream https://github.com/deploymenttheory/terraform-provider-microsoft365.git
4

Install Dependencies

go mod download
go mod tidy
5

Build the Provider

go build -o terraform-provider-microsoft365

​
Contributing Code

​
Development Workflow

1

Create a Feature Branch

git checkout -b feature/your-feature-name
Branch naming conventions:
  • feature/ - New features or resources
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • test/ - Test improvements
2

Make Your Changes

Follow the Development Guide for implementing new resources or features.Key principles:
  • Follow existing code patterns and structure
  • Write clear, self-documenting code
  • Add appropriate comments for complex logic
  • Include error handling and validation
3

Write Tests

All code contributions must include tests:
  • Unit tests for helper functions and logic
  • Acceptance tests for resource CRUD operations
Run tests locally:
# Run unit tests
go test ./...

# Run acceptance tests (requires M365 tenant)
TF_ACC=1 go test -v ./internal/resources/...
4

Run Linters

Ensure code quality with linters:
# Run golangci-lint
golangci-lint run

# Format code
go fmt ./...
5

Update Documentation

If adding new resources:
  • Create example .tf files in examples/resources/
  • Add Terraform Registry template in templates/resources/
  • Update relevant documentation files
6

Commit Your Changes

Write clear, descriptive commit messages:
git add .
git commit -m "feat: add support for windows autopilot policy resource"
Commit message format:
  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • test: - Test changes
  • refactor: - Code refactoring
  • chore: - Maintenance tasks
7

Push and Create Pull Request

git push origin feature/your-feature-name
Then create a pull request on GitHub with:
  • Clear description of changes
  • Link to related issues
  • Testing evidence (screenshots, test output)
  • Breaking changes (if any)

​
Pull Request Guidelines

When creating a pull request:
  • Code follows existing style and patterns
  • All tests pass locally
  • New tests added for new functionality
  • Documentation updated (if applicable)
  • Examples provided for new resources
  • Commit messages follow conventional format
  • PR description clearly explains changes
  • No breaking changes (or clearly documented)
  • Linters pass without errors
  1. Automated Checks: CI/CD pipelines run tests and linters
  2. Maintainer Review: Project maintainers review code quality and design
  3. Feedback Iteration: Address feedback and make requested changes
  4. Approval: Once approved, maintainers merge the PR
  5. Release: Changes included in next provider release

​
Reporting Issues

If you find a bug or want to suggest an enhancement:

​
Bug Reports

1

Search Existing Issues

Check if the issue already exists in GitHub Issues
2

Use Bug Report Template

Create a new issue using the bug report template and provide:
  • Clear, descriptive title
  • Provider version
  • Terraform version
  • Operating system
  • Resource name (if applicable)
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Error messages and logs
  • Terraform configuration (sanitized)
3

Add Labels

Tag the issue appropriately:
  • bug - For bugs
  • documentation - For docs issues
  • question - For questions

​
Feature Requests

1

Check Roadmap

Review the Provider Roadmap to see if the feature is already planned
2

Create Feature Request

Use the feature request template and include:
  • Clear description of the feature
  • Use case and business justification
  • Microsoft Graph API resource/endpoint
  • Priority (critical/high/medium/low)
  • Examples of desired Terraform configuration
  • Dependencies or related features
3

Engage in Discussion

Participate in discussions about:
  • Implementation approach
  • API compatibility
  • Schema design
  • Breaking changes

​
Code Style and Standards

​
Go Code Style

  • Follow Effective Go guidelines
  • Use gofmt for code formatting
  • Follow existing patterns in the codebase
  • Write idiomatic Go code
  • Use meaningful variable and function names
  • Keep functions focused and concise

​
Terraform Configuration Style

  • Use consistent indentation (2 spaces)
  • Follow Terraform style conventions
  • Provide meaningful resource names and descriptions
  • Include comments for complex configurations

​
Documentation Style

  • Use clear, concise language
  • Provide practical examples
  • Link to relevant Microsoft documentation
  • Include API permissions required
  • Document known limitations
  • Keep examples up-to-date

​
Testing Requirements

​
Unit Tests

Required for:
  • Helper functions
  • Data transformation logic
  • Validation functions
  • State mapping functions
func TestConstructResource(t *testing.T) {
    // Test implementation
}

​
Acceptance Tests

Required for:
  • All new resources
  • All resource CRUD operations
  • Resource import functionality
func TestAccResourceTemplate_basic(t *testing.T) {
    resource.Test(t, resource.TestCase{
        // Test implementation
    })
}
Acceptance tests require a valid Microsoft 365 tenant and may create/modify real resources. Use a dedicated test tenant.

​
Community Guidelines

​
Code of Conduct

We are committed to providing a welcoming and inclusive environment. All contributors must:
  • Be respectful and considerate
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members
  • Avoid harassment, discrimination, or inappropriate behavior

​
Getting Help

If you need help:

Discord Community

Join our Discord for real-time discussions and help

GitHub Discussions

Ask questions and discuss ideas

GitHub Issues

Report bugs and request features

Development Guide

Read the comprehensive development guide

​
License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

​
Recognition

Contributors will be:
  • Listed in release notes for their contributions
  • Recognized in the project README
  • Part of a growing community of M365 automation enthusiasts
Even small contributions make a big difference! Don’t hesitate to contribute documentation improvements, bug reports, or small fixes.

Build docs developers (and LLMs) love

Get started for freeTalk to us