Skip to content
  • contributing
  • guidelines
  • process

Contributing to ConnectSoft

This document explains how to contribute to ConnectSoft: templates, libraries, documentation, and decisions. It is written for architects, engineers, and team members who want to contribute to ConnectSoft's codebase, templates, libraries, and documentation.

ConnectSoft welcomes contributions that improve our templates, libraries, documentation, and decision-making processes. This guide explains the contribution process, review requirements, and best practices.

Note

Contributions should align with ConnectSoft's architecture principles (Clean Architecture, DDD, event-driven, cloud-native) and follow established patterns and conventions.

Contribution Areas

Area Examples Primary Owners Review Process
Templates Microservice template, auth server template, library template Architect/Engineering teams Architecture review + code review
Libraries ConnectSoft.Extensions.* libraries (HTTP, Observability, Messaging, Compliance) Engineering teams Code review + testing
Documentation MkDocs pages, diagrams, playbooks, runbooks Everyone Documentation review
Decisions ADRs (Architecture Decision Records), BDRs (Business Decision Records) Architects + Product Decision review process

General Principles

Incremental Contributions

  • Prefer Small Changes - Small, incremental contributions are easier to review and merge
  • One Change Per PR - Focus each PR on a single change or feature
  • Iterative Improvement - Build on existing work rather than large rewrites

Follow Existing Patterns

  • Architecture Patterns - Follow Clean Architecture, DDD, event-driven patterns
  • Naming Conventions - Use established naming conventions
  • Code Style - Follow existing code style and formatting
  • Documentation Style - Follow ConnectSoft documentation style guide

Quality Standards

  • Testable - All code must be testable
  • Observable - All code must include observability (logging, tracing, metrics)
  • Documented - All changes must be documented
  • Reviewed - All changes must be reviewed

Important

No One-Off Hacks: Contributions must follow established patterns and conventions. One-off hacks, shortcuts, and deviations from standards are not acceptable. If you need to deviate, propose an ADR first.

Review and Approval Process

Step 1: Create Issue or Idea

  • GitHub Issues - Create an issue describing the contribution
  • Discussion - Discuss the idea with the team
  • Clarification - Clarify requirements and approach

Step 2: Draft ADR/BDR if Needed

  • Architecture Changes - Draft ADR for architecture changes
  • Business Decisions - Draft BDR for business decisions
  • Review - Review ADR/BDR before implementation

See: Decision Records Process for ADR/BDR process.

Step 3: Open Pull Request

  • Branch - Create feature branch from main
  • Changes - Implement changes following guidelines
  • Tests - Add tests for new functionality
  • Documentation - Update documentation as needed
  • PR Description - Provide clear PR description

Step 4: Review, Tests, Merge

  • Code Review - At least one reviewer must approve
  • Tests - All tests must pass
  • CI/CD - CI/CD pipeline must pass
  • Approval - Get approval from primary owner
  • Merge - Merge after approval

Tools and Repositories

Repositories

  • Templates - ConnectSoft.*Template repositories
  • Libraries - ConnectSoft.Extensions.* repositories
  • Documentation - ConnectSoft.CompanyDocumentation repository
  • Factory - ConnectSoft.AI.SoftwareFactory.* repositories

Tools

  • Azure DevOps - Source control, CI/CD, work items
  • MkDocs - Documentation site generation
  • NuGet - Package management for libraries
  • Git - Version control