Contributing to SuperNanno

Thank you for considering contributing to SuperNanno!

We welcome contributions that help maintain the project's core values: reliability, clean architecture, developer experience, and professional quality.

Code of Conduct

By participating in this project, you agree to uphold our Code of Conduct and treat all contributors with respect.

Getting Started

1. Fork & Clone the Repository

git clone https://github.com/hbisneto/SuperNanno.git
cd SuperNanno

2. Set Up Development Environment

bash dev.sh

This script will create a virtual environment, upgrade pip, and install all dependencies.

3. Run the Editor

python app.py

Development Workflow

1. Create a branch for your feature or fix:
   git checkout -b feature/my-awesome-feature
2. Make your changes following the guidelines below.
3. Test your changes.
4. Commit with clear, conventional messages.
5. Push and open a Pull Request.

Architecture Guidelines

SuperNanno follows a clean, modular, and resilient architecture. Please respect these principles:

• Centralized State: All logic should go through AppContext.
• Separation of Concerns:
  • core/ → Business logic independent of UI
  • services/ → High-level services
  • handlers/ → User actions
  • events/ → Textual event handlers
  • ui/ → UI components
  • search/ → Search subsystem (Strategy Pattern)
• Resilience: All operations should be "best-effort". Never let logging, config, or diagnostics crash the editor.
• Error Handling: Use ctx.errors.handle() instead of raw try/except.

Do not add new top-level modules without prior discussion.

Testing

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_issue_service.py -v

Pull Request Process

1. Ensure your code passes all tests.
2. Update documentation if needed.
3. Use conventional commit titles:
   • feat: add XYZ
   • fix: correct ABC
   • docs: update contributing guide
   • refactor: improve error handling
4. Request review from maintainers.

Reporting Bugs

The best way to report bugs is using the built-in Report Service:

• Press Ctrl + X while the error is visible in the status bar.
• This automatically generates a diagnostic bundle and opens a GitHub issue.

Style Guide

• Follow PEP 8 with a maximum line length of 100 characters.
• Use type hints where reasonable.
• Write clear docstrings for public functions and classes.
• Prefer small, focused functions and classes.
• Keep error handling defensive and user-friendly.

Questions?

Feel free to open a Discussion on GitHub if you have questions about the codebase, architecture, or how to implement a feature.

---

Thank you for helping make SuperNanno better!
— Heitor Bardemaker A. Bisneto