Skip to main content

​
Overview

Pull requests are the primary way to contribute code to Intent Architect Modules. This guide walks you through the entire process from preparing your changes to getting them merged.

​
Before You Start

Ensure you’ve completed the following before submitting a pull request:

Development Setup

Your environment is properly configured with all required tools and dependencies.

Coding Standards

Your code follows the established conventions and best practices.

Tests Written

You’ve added appropriate test coverage for your changes.

Tests Passing

All tests pass locally including pre-commit validation checks.

​
Contribution Checklist

Before submitting your pull request, verify all items:
1

Module version updated

Update the module version in .imodspec file according to semantic versioning:
  • Patch (1.0.x): Bug fixes
  • Minor (1.x.0): New features (backward compatible)
  • Major (x.0.0): Breaking changes
2

Release notes updated

Add an entry to your module’s release notes file:
### Version 1.2.3

- Fixed template generation issue with nullable types
- Added support for record types in C# 10+
- Improved error messages for invalid configurations
3

Tests added

Test cases have been added to the Tests/ Intent Architect solution:
  • Integration tests validate module behavior
  • Unit tests cover specific functionality
  • Edge cases are tested
4

Module compiles

The module builds successfully:
dotnet build
5

Validations pass

Pre-build validations complete without errors:
./PipelineScripts/pre-build-validations.ps1 -ModulesFolder "Modules" -TestsFolder "Tests"
6

All tests pass

Complete pre-commit checks succeed:
./run-pre-commit-checks.ps1 -ModulesIsln "Modules/Intent.Modules.isln" -TestsIsln "Tests/Intent.Modules.Tests.isln"

​
Preparing Your Branch

​
Branch Naming

Use descriptive branch names that indicate the purpose: 
# Feature branches
git checkout -b feature/add-nullable-reference-support
git checkout -b feature/blazor-component-templates

# Bug fix branches
git checkout -b fix/template-null-reference
git checkout -b fix/dependency-version-mismatch

# Documentation branches
git checkout -b docs/update-contribution-guide

​
Commit Messages

Write clear, descriptive commit messages: 
# Good: Descriptive and specific
git commit -m "Add support for nullable reference types in C# templates"
git commit -m "Fix null reference exception in template builder"
git commit -m "Update dependency versions to latest stable releases"

# Bad: Vague and uninformative
git commit -m "Fix bug"
git commit -m "Update"
git commit -m "WIP"
Follow the conventional commits format when appropriate: type(scope): descriptionExamples:
  • feat(templates): add support for record types
  • fix(builder): resolve null reference in template generation
  • docs(readme): update installation instructions

​
Preparing Commits

1

Stage your changes

git add Modules/YourModule/
git add Tests/Intent.Modules.Tests/
2

Review changes

git status
git diff --staged
3

Commit with descriptive message

git commit -m "Add support for nullable reference types"
4

Push to your fork

git push origin feature/add-nullable-reference-support

​
Creating the Pull Request

​
PR Title

Use a clear, concise title that describes the change: 
# Good titles
Add nullable reference type support to C# templates
Fix null reference exception in template builder
Update module dependencies to latest stable versions

# Bad titles
Update
Bug fix
Changes

​
PR Description

Provide a comprehensive description using this template: 
## Summary

Brief overview of what this PR does and why.

## Changes

- List of specific changes made
- Key modifications to existing functionality
- New features or capabilities added

## Testing

- Description of how changes were tested
- New test cases added
- Manual testing performed

## Related Issues

Fixes #123
Relates to #456

## Breaking Changes

- List any breaking changes (if applicable)
- Migration steps for existing users

## Checklist

- [x] Module version updated
- [x] Release notes updated
- [x] Tests added/updated
- [x] All tests passing
- [x] Pre-commit validations passing
- [x] Documentation updated (if applicable)

​
Example Pull Request

## Summary

Adds support for nullable reference types (NRTs) in C# template generation. This allows templates to properly handle nullable annotations introduced in C# 8.0+.

## Changes

- Modified `CSharpTypeResolver` to recognize nullable reference syntax
- Updated `CSharpTemplateBase` to include nullable context directives
- Added configuration option to enable/disable nullable reference types
- Updated type resolution logic to preserve nullability annotations

## Testing

- Added unit tests for `CSharpTypeResolver.ResolveNullableType()`
- Added integration tests in `Tests/Intent.Modules.Tests.isln`
- Created test scenarios with nullable and non-nullable types
- Verified generated code compiles with nullable reference types enabled
- All existing tests continue to pass

## Related Issues

Fixes #789 - Template generation doesn't handle nullable reference types
Relates to #456 - C# 8.0 feature support

## Breaking Changes

None. This is a backward-compatible addition. Existing templates will continue to work unchanged.

## Checklist

- [x] Module version updated to 4.1.0 (minor version bump)
- [x] Release notes updated with feature description
- [x] Unit tests added for new functionality
- [x] Integration tests added to test solution
- [x] All tests passing locally
- [x] Pre-commit validations passing
- [x] Documentation updated in module README

​
Review Process

​
What Happens After Submission

1

Automated checks run

The Azure DevOps pipeline automatically:
  • Runs pre-build validations
  • Compiles all modules
  • Executes all tests
  • Validates Intent Architect solution changes
  • Checks for no outstanding Software Factory changes
2

Code review

Maintainers review your PR for:
  • Code quality and adherence to standards
  • Test coverage and quality
  • Module version and release notes
  • Breaking changes and impact
  • Documentation completeness
3

Feedback and iteration

Reviewers may request changes:
  • Address feedback in new commits
  • Push updates to the same branch
  • Respond to comments and questions
  • Mark conversations as resolved
4

Approval and merge

Once approved:
  • PR is merged to the target branch
  • CI/CD pipeline builds and tests again
  • Module is published (if on master/hotfix branch)
  • Your contribution is complete!

​
Responding to Review Comments

# Make the requested changes
# Edit files as needed

# Stage and commit
git add .
git commit -m "Address review feedback: improve error handling"

# Push to update the PR
git push origin feature/your-feature-branch
  • Be open to suggestions and alternative approaches
  • Ask clarifying questions if feedback is unclear
  • Explain your reasoning when you disagree
  • Be respectful and professional in all communications
If your branch conflicts with the target branch:
# Update your local master
git checkout master
git pull origin master

# Rebase your feature branch
git checkout feature/your-feature-branch
git rebase master

# Resolve conflicts in your editor
# Then continue the rebase
git add .
git rebase --continue

# Force push (required after rebase)
git push --force-with-lease origin feature/your-feature-branch

​
Common Review Feedback

​
Code Quality Issues

Common issues that delay PR approval:
  • Missing tests: All new functionality must have tests
  • Outdated version: Module version not updated
  • No release notes: Changes not documented
  • Failing tests: Pre-commit checks must pass
  • Breaking changes: Not clearly documented
  • Poor naming: Variables, methods, classes not clearly named
  • Missing documentation: XML comments not added for public APIs

​
How to Avoid Common Issues

1

Run pre-commit checks

Always run full validation before submitting:
./run-pre-commit-checks.ps1 `
  -ModulesIsln "Modules/Intent.Modules.isln" `
  -TestsIsln "Tests/Intent.Modules.Tests.isln"
2

Self-review your changes

Review your own PR before submitting:
  • Read through the diff on GitHub
  • Check for debugging code, console logs
  • Verify all files should be included
  • Ensure commit messages are clear
3

Update documentation

Keep documentation in sync:
  • Update module README if applicable
  • Add XML documentation comments
  • Update release notes
  • Include examples for new features

​
Branch and Release Strategy

​
Target Branches

  • master: Production-ready code, stable releases
  • development: Integration branch for next release
  • development-X.X: Version-specific development branches
  • hotfix/*: Critical bug fixes for production

​
Version Publishing

Modules are automatically published based on branch:
Stable releases published to production module server:
  • Final release versions (e.g., 4.1.0)
  • No pre-release identifiers
  • Published to main module server
  • Available to all Intent Architect users

​
After Your PR is Merged

1

Clean up local branches

git checkout master
git pull origin master
git branch -d feature/your-feature-branch
2

Monitor the build

Watch the build pipeline to ensure:
  • Merge build succeeds
  • Tests continue to pass
  • Module publishes successfully
3

Verify publication

For master branch merges:
  • Check module server for new version
  • Test installation in Intent Architect
  • Verify functionality in a test application

​
Getting Help

If you need assistance with the PR process:

Support Repository

Ask questions at IntentSoftware/Support

PR Comments

Ask specific questions directly in your PR comments

Code Review

Request clarification from reviewers during the review process

Community

Connect with other contributors in community discussions

​
Best Practices Summary

Key takeaways for successful pull requests:
  • Update module version according to semantic versioning
  • Add comprehensive test coverage
  • Run pre-commit checks before submitting
  • Write clear PR descriptions with context
  • Respond promptly to review feedback
  • Keep PRs focused on a single concern
  • Be patient and professional throughout the process
Smaller, focused PRs are easier to review and more likely to be merged quickly. Consider breaking large changes into multiple PRs.

​
Thank You!

Thank you for contributing to Intent Architect Modules! Your contributions help improve the platform for the entire community. We look forward to reviewing your pull request!

Build docs developers (and LLMs) love

Get started for freeTalk to us