diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..bb99402 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,237 @@ +# Release Process and Guidelines + +This document outlines the release methodology, cadence, and criteria for the APIS (Autonomous Power Interchange System) project. + +## Release Philosophy + +APIS follows a **stability-focused release model** that prioritizes: + +* System reliability for microgrid deployments +* Backward compatibility for existing installations +* Thorough testing of energy management functionality +* Clear communication of changes that affect safety or performance + +## Release Types + +### Major Releases (x.0.0) + +* **Frequency**: Annually or when significant architectural changes are made +* **Scope**: Breaking changes, major new features, architectural improvements +* **Backward Compatibility**: May include breaking changes (documented in migration guides) +* **Examples**: New energy trading algorithms, protocol changes, major UI overhauls + +### Minor Releases (x.y.0) + +* **Frequency**: Quarterly or bi-annually +* **Scope**: New features, enhancements, significant improvements +* **Backward Compatibility**: Maintained within the same major version +* **Examples**: New hardware support, additional monitoring features, performance improvements + +### Patch Releases (x.y.z) + +* **Frequency**: As needed for critical fixes +* **Scope**: Bug fixes, security patches, minor improvements +* **Backward Compatibility**: Fully maintained +* **Examples**: Critical energy management bugs, security vulnerabilities, installation fixes + +## Release Criteria + +### Feature Completeness + +* All planned features are implemented and tested +* Documentation is updated for new features +* Breaking changes are documented with migration paths + +### Quality Gates + +* **All tests pass**: Unit, integration, and system tests +* **No critical bugs**: All severity 1 and 2 issues resolved +* **Performance benchmarks**: Meet or exceed previous release performance +* **Hardware compatibility**: Tested on supported platforms (Ubuntu, CentOS, macOS) + +### Documentation Requirements + +* **Release Notes**: Detailed changelog with features, fixes, and breaking changes +* **Installation Guide**: Updated for any installation changes +* **Migration Guide**: For major releases with breaking changes +* **API Documentation**: Updated for any API changes + +### Security Review + +* Security scan completed with no high-severity vulnerabilities +* All dependencies updated to secure versions +* Any security issues from previous releases addressed + +## Release Process + +### 1. Release Planning (T-8 weeks) + +* Release goals and scope defined +* Feature freeze date established +* Release candidate timeline created +* Testing strategy finalized + +### 2. Feature Development (T-8 to T-4 weeks) + +* Active development of planned features +* Regular integration testing +* Documentation updates alongside development +* Weekly progress reviews + +### 3. Feature Freeze (T-4 weeks) + +* No new features accepted for the release +* Focus shifts to testing, bug fixes, and documentation +* Release candidate preparation begins +* Performance and compatibility testing intensifies + +### 4. Release Candidate Phase (T-4 to T-2 weeks) + +* **RC1**: First release candidate created and announced +* Community testing period begins +* Critical bug fixes only +* **RC2/RC3**: Additional candidates if significant issues found + +### 5. Release Preparation (T-2 weeks to T-0) + +* Final testing and validation +* Release notes finalization +* Package preparation for distribution +* Communication materials prepared + +### 6. Release Day (T-0) + +* Final release tagged and built +* Packages published to distribution channels +* Release announcement published +* Documentation sites updated + +### 7. Post-Release (T+1 week) + +* Monitor for immediate issues +* Respond to community feedback +* Plan any necessary patch releases + +## Release Artifacts + +### Source Code + +* Tagged release in Git repository +* Source archive (tar.gz) for download +* Checksums and digital signatures + +### Binary Packages + +* Installation packages for supported platforms +* Docker images (if applicable) +* Pre-built binaries for common architectures + +### Documentation + +* Release notes and changelog +* Updated installation and user guides +* API documentation updates +* Migration guides (for breaking changes) + +## Version Numbering + +APIS follows Semantic Versioning (SemVer) 2.0.0: + +* **MAJOR** (x): Incompatible API changes or breaking changes +* **MINOR** (y): New functionality in a backward-compatible manner +* **PATCH** (z): Backward-compatible bug fixes + +### Pre-release Versions + +* **Alpha** (x.y.z-alpha.n): Early development, feature incomplete +* **Beta** (x.y.z-beta.n): Feature complete, undergoing testing +* **Release Candidate** (x.y.z-rc.n): Final testing before release + +## Branch Management + +### Main Branch (`main`) + +* Always in a releasable state +* All features merged via pull requests +* Automated CI/CD validation required + +### Release Branches (`release/x.y`) + +* Created for each minor/major release +* Used for release candidate preparation +* Cherry-pick critical fixes from main +* Maintained for patch releases + +### Feature Branches (`feature/description`) + +* Used for individual feature development +* Merged to main via pull requests +* Deleted after successful merge + +## Communication + +### Release Announcements + +* **GitHub Releases**: Detailed release notes with download links +* **Mailing Lists**: Announcements to relevant LF Energy lists +* **Community Channels**: Updates via project communication channels +* **Website**: Updates to project website and documentation + +### Release Notes Format + +```text +## [Version] - YYYY-MM-DD + +### Added +- New features and enhancements + +### Changed +- Changes in existing functionality + +### Deprecated +- Soon-to-be removed features + +### Removed +- Features removed in this release + +### Fixed +- Bug fixes + +### Security +- Security improvements and fixes +``` + +## Long-Term Support (LTS) + +* **LTS Releases**: Selected major releases receive extended support +* **Support Duration**: 18 months of security updates and critical bug fixes +* **LTS Cadence**: Every 2-3 major releases +* **Selection Criteria**: Stability, adoption, and strategic importance + +## Emergency Releases + +For critical security vulnerabilities or system-breaking bugs: + +* Expedited release process (24-48 hours) +* Minimal feature scope (fix only) +* Immediate community notification +* Coordinated disclosure for security issues + +## Release Metrics and Retrospectives + +After each release: + +* **Quality Metrics**: Track bugs found post-release, test coverage, performance +* **Process Metrics**: Time to release, community feedback, adoption rate +* **Retrospectives**: Team review of what worked well and areas for improvement +* **Continuous Improvement**: Process updates based on lessons learned + +## Contact and Questions + +For questions about the release process: + +* **GitHub Issues**: Technical questions about specific releases +* **Maintainer Team**: Direct contact for release planning discussions +* **LF Energy TAC**: Escalation for release policy questions + +This release process is owned by the APIS project maintainers and approved by the Technical Steering Committee. Updates to this process require community discussion and maintainer approval. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..23e6546 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,147 @@ +# Support + +Thank you for your interest in the APIS (Autonomous Power Interchange System) project! This document explains how to get help and support when working with APIS. + +## Getting Help + +### Community Support Channels + +#### GitHub Issues + +- For bug reports, feature requests, and technical questions: +- Search existing issues before creating new ones to avoid duplicates +- Use appropriate issue templates when available + +#### GitHub Discussions (if available) + +- For general questions, ideas, and community discussions +- Share your APIS use cases and implementations +- Get help from the community + +#### LF Energy Community + +- Join the broader LF Energy community for microgrid and energy-related discussions +- Access additional resources and networking opportunities +- Visit: + +### Commercial Support + +For enterprise support, consulting, or custom development services related to APIS, you may contact: + +- **Energy IoT Open Source**: The organization that maintains the LF Hyphae roadmap +- Check the LF Energy website for member companies offering commercial support + +## Reporting Issues + +When reporting issues, please include: + +### For Bug Reports + +- **Clear description**: What you expected to happen vs. what actually happened + +- **Environment details**: OS, Python version, Java version, hardware setup +- **Reproduction steps**: Detailed steps to reproduce the issue +- **Error logs**: Include relevant error messages and stack traces +- **Configuration**: Share relevant configuration files (with sensitive data removed) + +### For Feature Requests + +- **Use case description**: Why you need this feature +- **Proposed solution**: Your ideas for implementation +- **Alternatives considered**: Other approaches you've evaluated +- **Impact assessment**: How this would benefit the community + +## Documentation and Resources + +### Official Documentation\ + +- **README.md**: Getting started guide and basic setup instructions +- **CONTRIBUTING.md**: How to contribute code and documentation +- **Individual component docs**: Each APIS component has its own documentation: + - apis-main + - apis-emulator + - apis-web + - apis-main_controller + - And other components listed in the main repository + +## Installation Support + +### System Requirements + +- Ubuntu 18.04, 20.04 +- CentOS 7, 8 +- macOS Catalina, Big Sur +- **Note**: Virtual environments are not supported + +### Prerequisites + +- JDK +- Python 3.6.9 or later +- SQLite 3.8.3 or later (CentOS 7) +- MongoDB +- Git, Make, Maven, Groovy + +For installation issues: + +- Check the Installation section in README.md +- Ensure all prerequisites are installed +- Try running `make build` in a fresh terminal session +- Check existing GitHub issues for similar problems + +## Security Issues + +**Security Policy**: Please check if a SECURITY.md file exists in the repository for specific security reporting guidelines. + +For security-related issues: + +- **DO NOT** create public GitHub issues for security vulnerabilities +- Contact the project maintainers privately first +- If no security contact is provided, email: + +## Contributing Help + +If you want to contribute but need guidance: + +- **Read CONTRIBUTING.md**: Start with the contribution guidelines +- **Look for "good first issue" labels**: These are beginner-friendly tasks +- **Join community discussions**: Engage with maintainers and contributors +- **Start small**: Begin with documentation improvements or bug fixes + +## Response Times and Expectations + +### Community Support + +- **GitHub issues**: Response times vary based on community availability +- **Complex technical questions** may take longer to address +- The project is maintained by volunteers, so please be patient + +### Maintainer Response + +- **Critical security issues**: Addressed as soon as possible +- **Bug reports**: Typically acknowledged within a few days +- **Feature requests**: May take longer to evaluate and respond + +## Code of Conduct + +All interactions in APIS community spaces are governed by the Code of Conduct. Please: + +- Be respectful and constructive in all communications +- Follow the Linux Foundation Code of Conduct guidelines +- Report any violations to + +## Getting Involved + +Beyond getting support, consider: + +- **Contributing code**: Fix bugs or add features +- **Improving documentation**: Help others by enhancing docs +- **Testing**: Try APIS in different environments and report findings +- **Community building**: Help answer questions from other users + +## Contact Information + +- **Project Repository**: +- **LF Energy Foundation**: +- **General LF Energy Contact**: + +Thank you for being part of the APIS community!