Contributing
Welcome to BERT development! This guide helps systems scientists, engineers, and developers contribute effectively to the BERT system modeling platform while maintaining alignment with systems science principles and professional development standards.
Quick Start
Prerequisites
Install Rust: Follow rustup.rs for the latest stable toolchain
Install Tauri Prerequisites: Follow Tauri prerequisites guide
Clone the Repository:
git clone git@github.com:halcyonic-systems/bert.git cd bert
Development Setup
Install Dependencies:
cargo install cargo-watch npm install
Run Development Server:
cargo tauri dev
Verify Installation:
Application should open with the BERT interface
Try creating a simple system model
Verify save/load functionality
First Contribution
Read Architecture Documentation: Start with the Architecture section
Review Coding Standards: Check the development standards below
Choose Your First Issue: Look for "good first issue" labels on GitHub
Development Standards
Code Quality Requirements
All contributions must follow our professional development standards:
Documentation: 100% compliance with documentation templates
Code Style: Use
rustfmt
andclippy
- no warnings allowedTesting: Comprehensive test coverage for new functionality
Performance: Maintain 60+ FPS in visualization systems
Architecture: Follow established patterns and Layer 4 System Language implementation
Mandatory Tools and Checks
# Before submitting any PR
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test --all
cargo doc --no-deps --quiet
Documentation Requirements
All new code MUST include comprehensive documentation:
Modules: Complete module-level documentation with purpose and usage
Functions: Full documentation with Parameters, Returns, Errors, Panics sections
Types: Comprehensive struct/enum documentation with field descriptions
Systems: System function documentation with ECS context
Plugins: Plugin documentation with integration patterns
Architecture Guidelines
System Language Implementation
BERT implements a Layer 4 System Language architecture with clear separation of concerns:
Layer 1 - Foundation: Bevy ECS providing entity-component architecture
Layer 2 - System Elements: Core components representing system entities
Layer 3 - Knowledge Representation: Data model and serialization
Layer 4 - System Orchestration: Event-driven coordination and UI integration
Architectural Principles
1. Separation of Concerns
UI Logic: Leptos components (
src/leptos_app/
)Visualization Logic: Bevy systems (
src/bevy_app/systems/
)System Modeling: Components and data model (
src/bevy_app/components/
,src/bevy_app/data_model/
)Integration Logic: Bundles and spawn systems (
src/bevy_app/bundles/
)
2. Event-Driven Design
Use trigger events for system communication
Avoid tight coupling between components
Maintain clear data flow patterns
Implement proper event scheduling and dependencies
3. Conceptual Integrity
Changes must align with System Language theory
Maintain consistent terminology in code and documentation
Reference specific files and components when communicating
Include diagrams when explaining complex changes
Relate changes back to system language concepts
File Organization
src/
├── bevy_app/ # Core system implementation
│ ├── components/ # System element definitions
│ ├── bundles/ # Entity creation patterns
│ ├── systems/ # System orchestration (Layer 4)
│ ├── data_model/ # Knowledge representation (Layer 3)
│ ├── plugins/ # System integration
│ └── resources/ # Global state management
├── leptos_app/ # User interface
└── events.rs # Cross-system communication
Systems Science Integration
Theoretical Foundations
All contributions should understand and maintain alignment with:
General Systems Theory: BERT models systems as bounded entities with inputs, outputs, and internal processes
Hierarchical Systems: Support for system decomposition and emergence
System Boundaries: Clear interface definitions and permeability concepts
Flow Modeling: Energy, material, and information exchange patterns
Complexity Theory: Support for atomic, complex, and multiset system types
Implementation Guidelines
1. System Element Modeling
Atomic Systems: Indivisible entities with simple, predictable behaviors
Complex Systems: Decomposable entities with emergent properties and adaptability
Multiset Systems: Collections of identical components with capacity-based behavior
2. Boundary Management
Interfaces: Formal connection points for system interaction
Porosity: Controlled permeability for flow exchange
Protocol Definition: Structured interaction patterns
3. Flow Characterization
Substance Types: Energy, Material, Message classifications
Interaction Types: Flow vs. Force distinction
Usability Patterns: Directional and utility classifications
Parameter Systems: Extensible property modeling
Development Workflow
Branch Strategy
# Feature development
git checkout -b feature/descriptive-name
# Bug fixes
git checkout -b fix/issue-description
# Documentation updates
git checkout -b docs/area-being-documented
Commit Standards
Use conventional commit format:
type(scope): description
feat(data-model): add complexity parameter serialization
fix(mouse): resolve selection state persistence issue
docs(bundles): add comprehensive spawn system documentation
refactor(systems): optimize flow rendering performance
Pull Request Process
Create Feature Branch: From latest
main
Make Changes: Following all standards and guidelines
Run Tests: Ensure existing tests pass
Submit Pull Request: With comprehensive description and testing notes
Address Reviews: Respond to all feedback promptly
Merge: Only after approval and all checks passing
Common Development Tasks
Adding New System Elements
Process:
Component Definition: Add to
system_elements.rs
Visual Representation: Create spawn bundle
UI Integration: Add Leptos editing components
Serialization: Update data model
Documentation: Complete template compliance
Files to modify:
src/bevy_app/components/system_elements.rs
src/bevy_app/bundles/spawn/[element].rs
src/leptos_app/components/button.rs
src/leptos_app/details.rs
src/bevy_app/data_model/save.rs
andload.rs
Enhancing Visualization
Focus areas:
Rendering performance (maintain 60+ FPS)
Visual clarity and information density
Systems science pedagogical value
Integration with existing visual elements
Key files:
src/bevy_app/systems/ui/[system].rs
src/bevy_app/bundles/spawn/[element].rs
UI Improvements
Considerations:
User experience and workflow efficiency
Consistency with overall design language
Accessibility and usability
Integration with existing UI patterns
Key files:
src/leptos_app/components/[component].rs
src/leptos_app/details.rs
styles.css
Performance Optimization
Requirements:
Performance profiling and bottleneck identification
Measurable improvement targets
No functionality regression
Scalability with complex system models
Approach:
Profile before optimizing
Implement efficient algorithms and data structures
Comprehensive before/after testing
Document performance characteristics
Testing Requirements
Test Categories
Unit Tests: Individual component functionality
Integration Tests: System interaction patterns
Performance Tests: Rendering and interaction benchmarks
User Acceptance Tests: Workflow and usability validation
Testing Standards
Coverage: Comprehensive test coverage for new functionality
Performance: Maintain 60+ FPS benchmarks
Regression: Ensure existing functionality remains intact
Edge Cases: Handle malformed data and unusual inputs
Code Review Process
Review Criteria
Architectural Alignment: Follows established patterns
Systems Science Integration: Maintains theoretical consistency
Code Quality: Meets documentation and style standards
Performance Impact: No degradation of user experience
Testing Coverage: Adequate test coverage and validation
Review Process
Automated Checks: All CI checks must pass
Peer Review: At least one developer review required
Systems Science Review: Conceptual alignment verification
Performance Review: Impact assessment on visualization performance
Documentation Review: Template compliance and clarity
Getting Help
Resources
Architecture Documentation: Comprehensive technical specifications in
docs/architecture/
Contributing Guide: Detailed development standards in
docs/contributing/
GitHub Issues: Bug reports and feature requests
Discussions: Community questions and design discussions
Communication
GitHub Issues: For bug reports and feature requests
Pull Requests: For code contributions and reviews
Discussions: For design questions and community input
Documentation: For clarification and improvement suggestions
Common Questions
Q: How do I understand the codebase architecture? A: Start with the Architecture documentation, then explore the comprehensive architecture overview in the repository.
Q: What documentation standards should I follow? A: All code must follow the professional documentation templates with 100% compliance requirements.
Q: How do I ensure my changes align with systems science principles? A: Review the systems science integration guidelines and validate theoretical alignment before implementation.
Q: What performance standards must I maintain? A: Visualization systems must maintain 60+ FPS, and all changes should be performance-tested.
Ready to contribute? Start by exploring the codebase, understanding the architecture, and choosing an issue that matches your interests and expertise level. Remember: BERT is built on solid systems science foundations, so every contribution should enhance our ability to model and understand complex systems! 🚀
Last updated