Governance and Contribution
Relevant source files
The following files were used as context for generating this wiki page:
The Governance and Contribution system in FLEXT-Core defines the engineering laws, quality standards, and workflow protocols required for maintaining an enterprise-grade foundation framework. It operates through a combination of strict architectural enforcement rules, automated quality gates, and standardized contribution workflows to ensure "zero-debt" development.
This system is anchored by the "Engineering Law" documented in AGENTS.md and enforced through a series of local checks and CI/CD gates. Contributors must adhere to Clean Architecture principles, explicit typing rules, and specific repository layering constraints to ensure the framework remains stable and scalable.
Contribution Workflow
The contribution process follows a "fast entrypoint" workflow designed for focus and quality. Contributors are expected to work from specific development branches (e.g., 0.12.0-dev) and maintain a scoped commit history using conventional commit messages.
Standard Workflow Steps
- Branching: Create a focused branch from the current development target.
- Scoping: Keep changes restricted to one concern per commit.
- Testing: Update or add tests in the same change when behavior is modified.
- Verification: Run all required local quality gates before opening a Pull Request (PR).
- Documentation: Update relevant docs for any API, architecture, or behavioral changes.
Sources: CONTRIBUTING.md:16-22
Pull Request Expectations
PRs are evaluated based on their size, clarity, and validation evidence. A successful PR must include:
- Conventional Commits: Use prefixes like
feat:,fix:,docs:, orrefactor:. - Problem Statement: A clear explanation of the issue being addressed.
- Validation Evidence: Proof of commands run and their successful results.
Sources: CONTRIBUTING.md:36-41
Quality Gates and Enforcement
FLEXT-Core utilizes automated "Quality Gates" and architectural "Smell" detection to maintain code integrity. These rules are codified into the system and must be satisfied before any merge.
Automated Checks
The project provides a Makefile with canonical verbs for local validation.
| Command | Purpose |
|---|---|
make lint | Runs static analysis and style checks. |
make type-check | Enforces explicit typing using mypy/pyright. |
make test-fast | Runs the core suite of unit tests. |
make validate | The full pre-merge gate encompassing all checks. |
Sources: CONTRIBUTING.md:24-32, README.md:46-48
Architectural Enforcement Rules
The system enforces specific architectural patterns through automated rules. These prevent "leaky abstractions" and maintain the Clean Architecture layers.
The diagram shows how specific architectural violations (R1-R4) are monitored and mapped to required actions to prevent merge blockages.
Sources: src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_09.py:16-63
Code Smell Detection
FLEXT-Core defines specific thresholds for cyclomatic complexity and code structures to prevent technical debt.
Complexity Thresholds
The framework monitors various metrics to ensure functions and files remain maintainable.
| Metric | Max Threshold | Description |
|---|---|---|
| Parameters | 5 | Max number of function parameters. |
| Returns | 5 | Max return statements in a function. |
| Nesting | 4 | Max nested control-flow levels. |
| Function Complexity | 14 | Max cyclomatic complexity for a function. |
| File Complexity | 49 | Max cyclomatic complexity for a module. |
Sources: src/flext_core/_constants/_enforcement_data/smells.json:2-8
Fix Strategies
The system provides recommended strategies for resolving detected smells:
- Boolean Logic: Simplified using named predicates or
any()/all(). - Function Parameters: Resolved by decomposing functions or introducing a domain context object.
- Identical Code: Resolved by extracting shared helpers or canonical constants.
Sources: src/flext_core/_constants/_enforcement_data/smells.json:11-45
Architecture and Typing Rules
Governance extends to the internal structure of the code. Contributors must follow repository layering and import rules strictly.
Facade and Alias Patterns
FLEXT-Core relies on explicit project aliases for imports:
r: Result/Railway patternst: Typingsp: Protocolsu: Utilitiesm: Modelsc: Constants
The sequence diagram illustrates the mandatory use of public facades and the prohibition of direct private tree imports.
Sources: CONTRIBUTING.md:31-33, src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_09.py:108-111
Testing Standards
Test coverage is a primary pillar of governance. The project targets a baseline of ≥79% coverage, with a goal of 85%.
- Unit Tests: Module-level guarantees (located in
tests/unit/). - Integration Tests: Cross-module flows (located in
tests/integration/). - Modernization Rules: New tests must exercise
FlextDispatcherandFlextContextinteractions where applicable.
Sources: tests/README.md:18-35, tests/README.md:46-49
Conclusion
Governance in FLEXT-Core is not merely a set of guidelines but a strictly enforced technical system. By combining standardized workflows, architectural enforcement rules, and automated code smell detection, the project ensures that contributions maintain the high standards required for an enterprise foundation framework. Following these rules is essential for any developer looking to modify or extend the core system.