Thank you for your interest in contributing to LogLama! This document provides comprehensive guidelines for contributors to help maintain code quality and consistency across the project.
- Getting Started
- Development Environment Setup
- Project Structure
- Development Workflow
- Code Style and Standards
- Testing Guidelines
- Documentation
- Submitting Changes
- Publishing and Releases
- Community Guidelines
- Getting Help
- Python 3.10 or higher
- Git
- Make (for using Makefile commands)
- Poetry (will be installed during setup)
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/loglama.git cd loglama - Set up the development environment:
make setup
- Verify the installation:
make test
LogLama uses Python virtual environments to manage dependencies. The setup is automated through the Makefile:
# Create virtual environment and install dependencies
make setup
# Activate the virtual environment manually (if needed)
source venv/bin/activate # On Linux/macOS
# or
venv\Scripts\activate # On WindowsLogLama uses Poetry for dependency management. Dependencies are defined in pyproject.toml:
- Runtime dependencies: Required for LogLama to function
- Development dependencies: Required for development, testing, and publishing
Create a .env file for local development:
cp env.example .envKey configuration options:
# Logging Configuration
LOGLAMA_LOG_LEVEL=DEBUG
LOGLAMA_LOG_DIR=./logs
LOGLAMA_CONSOLE_ENABLED=true
LOGLAMA_FILE_ENABLED=true
LOGLAMA_JSON_LOGS=false
LOGLAMA_STRUCTURED_LOGGING=false
# Database Configuration
LOGLAMA_DB_LOGGING=true
LOGLAMA_DB_PATH=./logs/loglama.db
# Web Interface Configuration
LOGLAMA_WEB_PORT=8081
LOGLAMA_WEB_HOST=127.0.0.1
LOGLAMA_WEB_DEBUG=true- Look for issues labeled
good first issuefor beginners - Check the issue tracker for bugs and feature requests
- If working on something new, create an issue first to discuss it
# Create and switch to a new branch
git checkout -b feature/your-feature-name
# For bug fixes
git checkout -b fix/issue-description
# For documentation
git checkout -b docs/improvement-description- Follow the Code Style and Standards
- Write tests for new functionality
- Update documentation as needed
- Keep commits small and focused
# Run all tests
make test
# Run specific test types
make test-unit
make test-integration
# Run code quality checks
make lint# Format code automatically
make formatLogLama follows PEP 8 with some specific conventions:
- Line length: Maximum 88 characters (Black default)
- Import organization: Organized with
isort - Type hints: Required for all public functions and methods
- Docstrings: Required for all public classes, functions, and methods
- Black: Automatic code formatting
- isort: Import sorting
- flake8: Linting and style checking
- mypy: Static type checking
-
Ensure your branch is up to date:
git checkout main git pull upstream main git checkout your-branch git rebase main
-
Run the full test suite:
make test make lint -
Push your changes:
git push origin your-branch
-
Create a Pull Request on GitHub with:
- Clear title and description
- Reference to related issues
- Description of changes made
- Any breaking changes noted
## Description
Brief description of the changes made.
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
## Related Issues
Fixes #(issue number)
## Testing
- [ ] Tests pass locally (`make test`)
- [ ] Linting passes (`make lint`)
- [ ] New tests added for new functionality
- [ ] Manual testing completed
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No unnecessary files included- Automated Checks: CI/CD pipeline runs tests and quality checks
- Code Review: Maintainers review code for quality and correctness
- Feedback: Address any requested changes
- Approval: Once approved, maintainers will merge the PR
LogLama uses semantic versioning (SemVer):
- MAJOR.MINOR.PATCH (e.g., 1.2.3)
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)
# Bump patch version (0.1.0 -> 0.1.1)
make version-patch
# Bump minor version (0.1.0 -> 0.2.0)
make version-minor
# Bump major version (0.1.0 -> 1.0.0)
make version-majorOnly maintainers can publish to PyPI. The process is automated:
# Configure PyPI credentials (one-time setup)
make configure-pypi
# Full publishing workflow with all checks
make publish-full
# Quick publish (for hotfixes)
make publish-quick
# Dry run to test the process
make publish-dry-run- All tests pass
- Documentation is up to date
- CHANGELOG.md is updated
- Version number is bumped appropriately
- Release notes are prepared
- Breaking changes are documented
We are committed to providing a welcoming and inclusive environment for all contributors. Please:
- Be respectful in all interactions
- Be constructive when providing feedback
- Be patient with new contributors
- Be inclusive and welcoming to people of all backgrounds
- GitHub Issues: Bug reports, feature requests, and general discussion
- Pull Requests: Code reviews and technical discussions
- GitHub Discussions: Community questions and broader topics
When reporting bugs:
- Search existing issues first
- Use the issue template provided
- Include reproduction steps
- Provide system information
- Include relevant logs
Example bug report:
## Bug Description
Brief description of the bug.
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Expected Behavior
What should happen.
## Actual Behavior
What actually happens.
## Environment
- OS: [e.g., Ubuntu 20.04]
- Python version: [e.g., 3.10.5]
- LogLama version: [e.g., 0.1.0]
## Additional Context
Any other relevant information.When requesting features:
- Describe the problem the feature would solve
- Explain the proposed solution
- Consider alternative solutions
- Assess the impact on existing functionality
Use the example application to test changes:
# Generate sample logs
make run-example
# View logs in web interface
make view-logs
# Use CLI to inspect logs
make run-cli- Minimize I/O operations in hot paths
- Use appropriate data structures for the task
- Consider memory usage for large log files
- Profile code when optimizing performance
- Validate all inputs from external sources
- Sanitize log messages to prevent injection attacks
- Use parameterized queries for database operations
- Be careful with file paths to prevent directory traversal
# In webtask/cli/commands/new_command.py
import click
from loglama.core.logger import get_logger
@click.command()
@click.option('--param', help='Parameter description')
def new_command(param: str) -> None:
"""Description of the new command."""
logger = get_logger("cli.new_command")
logger.info(f"Executing new command with param: {param}")
# Command implementation# In webtask/api/routes/new_route.py
from flask import Blueprint, request, jsonify
from loglama.core.logger import get_logger
new_bp = Blueprint('new', __name__)
logger = get_logger("api.new")
@new_bp.route('/api/new', methods=['GET'])
def get_new_data():
"""Get new data endpoint."""
logger.info("New endpoint accessed")
# Implementation
return jsonify({"status": "success", "data": []})- README.md: Project overview and quick start
- API Documentation: Available at
/api/docswhen running the API server - Code Examples: Check the
examples/directory
- GitHub Issues: For bug reports and feature requests
- GitHub Discussions: For questions and community support
- Code Comments: Inline documentation in the codebase
Common issues and solutions:
# Ensure dependencies are up to date
make clean
make setup
make test# Ensure LogLama is installed in development mode
pip install -e .# Clear the database and regenerate
rm -f logs/loglama.db
make run-example# Check if the database exists and has data
ls -la logs/
make run-example # Generate sample data
make view-logs # Start web interface- Start small: Begin with small, focused changes
- Test thoroughly: Write tests and run the full suite
- Document changes: Update documentation and add examples
- Follow conventions: Use established patterns and styles
- Ask questions: Don't hesitate to ask for help or clarification
- Be patient: Code review and feedback are part of the process
# Add to webtask/core/filters.py
class DateRangeFilter:
"""Filter logs by date range."""
def __init__(self, start_date: str, end_date: str):
self.start_date = start_date
self.end_date = end_date
def apply(self, logs: List[LogEntry]) -> List[LogEntry]:
"""Apply date range filter to logs."""
# Implementation here
return filtered_logs# Add to webtop/core/formatters.py
class XMLFormatter:
"""Format logs as XML."""
def format(self, record: LogRecord) -> str:
"""Format a log record as XML."""
# Implementation here
return xml_string# Add to environment configuration
LOGLAMA_XML_OUTPUT = os.getenv("LOGLAMA_XML_OUTPUT", "false").lower() == "true"
# Use in logger configuration
if config.xml_output:
handler.setFormatter(XMLFormatter())Thank you for contributing to LogLama! Your contributions help make logging better for everyone in the PyLama ecosystem. The logger name level: The logging level config: Optional configuration dictionary """
def __init__(
self,
name: str,
level: str = "INFO",
config: Optional[Dict[str, Any]] = None
) -> None:
self.name = name
self.level = level
self.config = config or {}
self._logger = logging.getLogger(name)
def log_with_context(self, message: str, **context: Any) -> None:
"""Log a message with context.
Args:
message: The log message
**context: Additional context fields
"""
with LogContext(**context):
self._logger.info(message)
### Commit Message Convention
Use conventional commit messages:
type(scope): description
[optional body]
[optional footer]
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
Examples:
feat(cli): add log filtering by date range fix(web): resolve pagination issue in log viewer docs(api): update API endpoint documentation test(core): add tests for context management
## Testing Guidelines
### Test Structure
Tests are organized in three categories:
1. **Unit Tests** (`tests/unit/`): Test individual components in isolation
2. **Integration Tests** (`tests/integration/`): Test components working together
3. **Ansible Tests** (`tests/ansible/`): Test shell scripts and system integration
### Writing Tests
Use pytest for all tests:
```python
import pytest
from loglama.core.logger import get_logger
from loglama.core.context import LogContext
class TestLogger:
"""Test suite for logger functionality."""
def test_basic_logging(self):
"""Test basic logging functionality."""
logger = get_logger("test")
# Test implementation here
assert logger is not None
def test_context_logging(self):
"""Test context-aware logging."""
logger = get_logger("test")
with LogContext(user_id="123"):
logger.info("Test message")
# Verify context was captured
# Test implementation here
@pytest.fixture
def temp_db_path(self, tmp_path):
"""Provide a temporary database path for testing."""
return tmp_path / "test.db"
- Aim for 90%+ test coverage
- All new features must include tests
- Bug fixes should include regression tests
# Run all tests
make test
# Run with coverage
make test-coverage
# Run specific test file
pytest tests/unit/test_logger.py -v
# Run specific test method
pytest tests/unit/test_logger.py::TestLogger::test_basic_logging -v- All public classes, functions, and methods must have docstrings
- Use Google-style docstrings
- Include type information in docstrings when helpful
- Update README.md for new features
- Add examples for new functionality
- Update CLI help text when adding new commands
- Document all API endpoints
- Include request/response examples
- Update OpenAPI specifications if applicable