Contributing

Thank you for your interest in contributing to Pulumi Any Terraform! This guide will help you get started with development, testing, and submitting contributions.

Development Setup#

Prerequisites#

• Node.js 22.18.0 or later
• pnpm 10.14.0 or later
• Git for version control
• A GitHub account

Setting Up Your Environment#

1. Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/pulumi-any-terraform.gitcd pulumi-any-terraform

2. Install dependencies:

pnpm install

3. Verify your setup:

pnpm run syncpack:check

Project Structure#

pulumi-any-terraform/├── packages/              # Provider packages│   ├── namecheap/        # Individual provider│   │   ├── bin/          # Compiled output (generated)│   │   ├── types/        # TypeScript types (generated)│   │   ├── package.json  # Package metadata│   │   └── README.md     # Provider docs│   └── ...├── tools/                 # Build system plugins│   ├── build.ts          # Build orchestration│   ├── linter.ts         # Code linting│   └── oxfmt.ts          # Code formatting├── docs/                  # Docs7 site (docs.json + MDX)├── .github/              # CI/CD workflows└── nx.json               # Nx configuration

Adding a New Provider#

1. Create Package Directory#

mkdir -p packages/my-providercd packages/my-provider

2. Create package.json#

{  "name": "pulumi-my-provider",  "description": "A Pulumi provider for [Service Name]",  "version": "0.1.0",  "homepage": "https://github.com/hckhanh/pulumi-any-terraform",  "repository": {    "type": "git",    "url": "git+https://github.com/hckhanh/pulumi-any-terraform.git",    "directory": "packages/my-provider"  },  "private": false,  "sideEffects": false,  "main": "./bin/index.js",  "module": "./bin/index.js",  "types": "./bin/index.d.ts",  "exports": {    ".": "./bin/index.js",    "./package.json": "./package.json"  },  "dependencies": {    "async-mutex": "0.5.0"  },  "devDependencies": {    "@pulumi/pulumi": "3.205.0",    "@types/node": "24.9.2",    "typescript": "5.9.3"  },  "peerDependencies": {    "@pulumi/pulumi": ">=3.190.0 <4"  },  "files": [    "bin",    "README.md"  ],  "keywords": [    "pulumi",    "terraform",    "provider",    "my-provider"  ],  "license": "MIT",  "publishConfig": {    "access": "public"  },  "pulumi": {    "resource": true,    "name": "terraform-provider",    "version": "0.14.0",    "parameterization": {      "name": "my-provider",      "version": "1.0.0",      "value": "BASE64_ENCODED_VALUE_HERE"    }  }}

3. Generate Parameterization Value#

The parameterization.value field must be a base64-encoded JSON:

# Create the JSONecho '{"remote":{"url":"registry.opentofu.org/org/provider","version":"1.0.0"}}' | base64# Add to package.json

4. Create README.md#

Create comprehensive documentation for your provider (see existing providers for examples).

5. Add TypeScript Configuration#

Create tsconfig.json:

{  "extends": "../../tsconfig.json",  "compilerOptions": {    "outDir": "./bin",    "rootDir": "."  },  "include": ["**/*.ts"],  "exclude": ["node_modules", "bin"]}

6. Test Your Provider#

# Build the providerpnpm nx run my-provider:build# Check for issuespnpm nx run my-provider:check

Development Workflow#

Making Changes#

1. Create a feature branch:

git checkout -b feature/your-feature-name

2. Make your changes following the coding standards

3. Format your code:

pnpm nx run root:oxfmt:write

4. Check for issues:

pnpm nx affected -t check

5. Build affected packages:

pnpm nx affected -t build

Running Quality Checks#

# Check all packagespnpm nx run-many -t check# Fix formatting issuespnpm nx run-many -t fix# Check dependency versionspnpm run syncpack:check# Fix dependency versionspnpm run syncpack:fix

Coding Standards#

TypeScript Best Practices#

• Use import type for type-only imports
• Avoid using any - prefer proper typing
• Use const for variables that are never reassigned
• Prefer arrow functions for consistency
• Use template literals over string concatenation

File Organization#

• Keep generated files in bin/ directory
• Store type definitions in types/ directory
• Place documentation in provider README.md

Naming Conventions#

• Use kebab-case for file names: my-component.ts
• Use PascalCase for classes: MyResource
• Use camelCase for variables and functions: myVariable

Testing#

Manual Testing#

Test your provider with a real Pulumi program:

// test-program.tsimport * as pulumi from "@pulumi/pulumi";import * as myprovider from "pulumi-my-provider";const resource = new myprovider.SomeResource("test", {    // Resource properties});export const resourceId = resource.id;

Run the test:

pulumi previewpulumi up

Integration Testing#

Test with actual provider APIs:

1. Set up required credentials
2. Deploy test resources
3. Verify resource creation
4. Clean up resources

Documentation#

Provider Documentation#

Each provider needs comprehensive documentation:

1. Installation instructions
2. Configuration guide
3. Quick start examples
4. Common use cases
5. Resource reference
6. Troubleshooting guide

Documentation Site#

Add provider documentation to the docs site:

# Create provider docsdocs/providers/my-provider/overview.mdx

Add the page to the Providers group in docs/docs.json.

Submitting Changes#

Creating a Pull Request#

1. Push your branch:

git push origin feature/your-feature-name

2. Open a Pull Request on GitHub

3. Fill out the PR template with:

   • Description of changes
   • Related issue number
   • Testing performed
   • Breaking changes (if any)

PR Review Process#

1. Automated checks run (linting, building, testing)
2. Maintainers review your code
3. Address any feedback
4. Once approved, your PR will be merged

After Merge#

• Your changes are automatically deployed
• Packages are published to npm
• Documentation is updated

Release Process#

Version Management#

We use Changesets for version management:

1. Create a changeset:

pnpm changeset

2. Select packages to version

3. Choose version bump (patch, minor, major)

4. Describe changes

5. Commit the changeset:

git add .changeset/git commit -m "chore: add changeset"

Publishing#

Publishing happens automatically when:

1. PR is merged to main
2. Changesets exist
3. GitHub Actions runs the publish workflow
4. Packages are published to npm

Getting Help#

Resources#

• GitHub Issues: Report bugs and request features
• Pull Requests: Browse existing contributions
• Documentation: Read the full documentation site
• Pulumi Slack: Join the community discussions

Common Questions#

Q: How do I find the right Terraform provider version? A: Check the Terraform Registry for the latest version.

Q: My build is failing. What should I do? A: Run pnpm nx reset to clear caches, then try again.

Q: How do I test provider changes locally? A: Use pnpm link to link your local package to a test Pulumi program.

Q: Can I add support for a private Terraform provider? A: Yes, but you'll need to host it in a private registry and update the parameterization URL.

Code of Conduct#

We follow a Code of Conduct to ensure a welcoming environment:

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what is best for the community
• Show empathy towards other community members

License#

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You!#

Your contributions make this project better for everyone. We appreciate your time and effort!