Skip to main content
This guide provides detailed technical requirements and best practices for contributing to the Intent Architect .NET Modules project. Following these guidelines ensures your contributions can be smoothly integrated and maintained.

​
Quick Checklist

Before submitting your pull request, verify you have completed all items:
1

Module Version Updated

Update version in .imodspec file following Semantic Versioning
2

Module Compiles Successfully

Build and verify the module installs without errors
3

Test Cases Added

Add comprehensive tests to the Tests solution
4

Pre-commit Checks Pass

Run run-pre-commit-checks.ps1 successfully
5

Code Follows Principles

Ensure changes align with contribution principles

​
Semantic Versioning

All modules must follow Semantic Versioning 2.0.0 standards.

​
Version Format

MAJOR.MINOR.PATCH[-pre.BUILD]
Increment when you make incompatible API changes:
  • Removing or renaming public APIs
  • Changing method signatures
  • Breaking backward compatibility
  • Major architectural changes
Example: 1.5.3 → 2.0.0
Increment when you add backwards-compatible functionality:
  • Adding new features
  • Adding new templates or patterns
  • Extending existing functionality
  • Adding new optional parameters
Example: 1.5.3 → 1.6.0
Increment when you make backwards-compatible bug fixes:
  • Fixing bugs
  • Correcting generated code issues
  • Performance improvements
  • Documentation updates
Example: 1.5.3 → 1.5.4

​
Updating Module Version

Update the version in your module’s .imodspec file: 
<?xml version="1.0" encoding="utf-8"?>
<package>
  <id>Intent.YourModule</id>
  <version>1.2.3</version> <!-- Update this line -->
  <supportedClientVersions>[4.5.0,5.0.0)</supportedClientVersions>
  <summary>Your module summary</summary>
  <!-- ... rest of configuration -->
</package>
Always update the version number before submitting your PR. PRs without version updates will not be accepted.

​
Module Structure

​
Module Specification (.imodspec)

Every module requires a properly configured .imodspec file: 
<?xml version="1.0" encoding="utf-8"?>
<package>
  <id>Intent.YourModule</id>
  <version>1.0.0</version>
  <supportedClientVersions>[4.5.0,5.0.0)</supportedClientVersions>
  <summary>Brief description of your module</summary>
  <description>Detailed description of functionality</description>
  <authors>Intent Architect</authors>
  <tags>relevant tags here</tags>
  <projectUrl>https://docs.intentarchitect.com/...</projectUrl>
  <templates />
  <decorators></decorators>
  <factoryExtensions></factoryExtensions>
  <dependencies>
    <dependency id="Intent.Common" version="3.7.0" />
  </dependencies>
  <files>
    <file src="$outDir$/$id$.dll" />
    <file src="$outDir$/$id$.pdb" />
  </files>
  <releaseNotes>release-notes.md</releaseNotes>
</package>
Ensure all dependencies are listed with appropriate version ranges to avoid compatibility issues.

​
Testing Requirements

All contributions must include appropriate test cases in the Tests Intent Architect solution.

​
Test Solution Location

Tests/Intent.Modules.NET.Tests.isln

​
Types of Tests

Unit Tests

Test individual components and templates in isolation

Integration Tests

Test interaction with other modules and generated code

Generation Tests

Verify generated code matches expected output

Build Tests

Ensure generated code compiles successfully

​
Test Best Practices

Test all new functionality, including:
  • Happy path scenarios
  • Edge cases
  • Error conditions
  • Integration points
Create test cases that reflect real-world usage patterns developers will encounter.
Write clear, well-documented tests that others can understand and maintain.
Verify that generated code:
  • Compiles without warnings
  • Follows C# best practices
  • Is readable and maintainable
  • Includes appropriate comments and documentation

​
Pre-commit Validation

​
Running Pre-commit Checks

The run-pre-commit-checks.ps1 script validates your changes before submission: 
# Run all checks
.\run-pre-commit-checks.ps1

# Reset and run from the beginning
.\run-pre-commit-checks.ps1 -Reset

​
What the Script Validates

Pre-build ValidationsValidates:
  • Module metadata files (.imodspec)
  • Configuration correctness
  • File structure integrity

​
Troubleshooting Failed Checks

Common Issues:
  • Invalid XML in .imodspec files
  • Missing required metadata fields
  • Incorrect file paths in module specification
Solution: Review error messages and validate your .imodspec file against the schema.
Common Issues:
  • Uncommitted Software Factory changes
  • Module configuration mismatches
  • Cached module conflicts
Solution: Commit all changes and ensure Software Factory is in sync.
Common Issues:
  • Compilation errors in templates
  • Missing dependencies
  • Breaking changes in referenced modules
Solution: Review compilation errors, update dependencies, and ensure compatibility.
Common Issues:
  • Test project configuration errors
  • Missing test dependencies
  • Generated code doesn’t compile
Solution: Check test project setup and generated code for errors.
The script saves progress between phases. If a phase fails, fix the issue and re-run - it will automatically resume from the failed phase.

​
Code Quality Standards

​
Generated Code Quality

Your templates must generate code that:

Readable

Looks like hand-written code with proper formatting and naming

Maintainable

Easy to understand and modify for developers

Idiomatic

Follows C# and .NET conventions and best practices

Documented

Includes XML documentation comments where appropriate

​
Template Code Quality

  • Use clear, descriptive names for templates and classes
  • Organize templates logically by functionality
  • Keep templates focused on single responsibilities

​
Module Dependencies

​
Declaring Dependencies

Properly declare all module dependencies in your .imodspec: 
<dependencies>
  <dependency id="Intent.Common" version="3.7.0" />
  <dependency id="Intent.Common.Types" version="3.4.0" />
  <dependency id="Intent.Modelers.Services" version="3.8.0" />
</dependencies>

​
Dependency Guidelines

Use appropriate version ranges to balance compatibility and features:
  • Exact version: version="1.2.3" - Use for critical dependencies
  • Minimum version: version="1.2.3" - Most common approach
  • Consider the stability and update frequency of dependencies
Most modules will depend on:
  • Intent.Common - Core functionality
  • Intent.Common.Types - Common type definitions
  • Specific modeler modules for metadata
Only include necessary dependencies:
  • Each dependency increases installation complexity
  • Consider whether functionality can be self-contained
  • Document why each dependency is required

​
Documentation

​
Module Documentation

Include a docs/README.md file in your module folder: 
# Intent.YourModule

## Overview

Brief description of what the module does.

## Installation

How to install and configure the module.

## Usage

Examples of how to use the module.

## Configuration

Available settings and options.

## Generated Code

Examples of generated code.

​
Release Notes

Update release-notes.md with your changes: 
# Release Notes

## Version 1.2.3

- Fixed: Bug in template generation for nullable types
- Added: Support for record types
- Improved: Code generation performance

​
Best Practices Summary

Before You Start

  • Review existing modules for patterns
  • Understand the problem you’re solving
  • Check for similar existing functionality
  • Plan your changes thoroughly

During Development

  • Follow existing code patterns
  • Write tests as you develop
  • Keep changes focused and atomic
  • Test generated code thoroughly

Before Submitting

  • Update version number
  • Run pre-commit checks
  • Add test cases
  • Update documentation

After Submitting

  • Respond to review comments
  • Test pre-release versions
  • Help with integration testing
  • Update if issues are found

​
Additional Resources

Get Support

Have questions? Visit our GitHub support repository for help.
These guidelines are designed to help maintain the high quality and consistency of Intent Architect modules. If you have suggestions for improving these guidelines, please let us know!

Build docs developers (and LLMs) love

Get started for freeTalk to us