Contributing
Last updated
Last updated
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.
Install Rust: Follow for the latest stable toolchain
Install Tauri Prerequisites: Follow
Clone the Repository:
Install Dependencies:
Run Development Server:
Verify Installation:
Application should open with the BERT interface
Try creating a simple system model
Verify save/load functionality
Review Coding Standards: Check the development standards below
Choose Your First Issue: Look for "good first issue" labels on GitHub
All contributions must follow our professional development standards:
Documentation: 100% compliance with documentation templates
Code Style: Use rustfmt
and clippy
- no warnings allowed
Testing: Comprehensive test coverage for new functionality
Performance: Maintain 60+ FPS in visualization systems
Architecture: Follow established patterns and Layer 4 System Language implementation
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
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
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/
)
Use trigger events for system communication
Avoid tight coupling between components
Maintain clear data flow patterns
Implement proper event scheduling and dependencies
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
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
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
Interfaces: Formal connection points for system interaction
Porosity: Controlled permeability for flow exchange
Protocol Definition: Structured interaction patterns
Substance Types: Energy, Material, Message classifications
Interaction Types: Flow vs. Force distinction
Usability Patterns: Directional and utility classifications
Parameter Systems: Extensible property modeling
Use conventional commit format:
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
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
and load.rs
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
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
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
Unit Tests: Individual component functionality
Integration Tests: System interaction patterns
Performance Tests: Rendering and interaction benchmarks
User Acceptance Tests: Workflow and usability validation
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
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
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
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
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
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! 🚀
Read Architecture Documentation: Start with the section
Q: How do I understand the codebase architecture? A: Start with the documentation, then explore the comprehensive architecture overview in the repository.