Contributing to Fractum¶

Thank you for your interest in contributing to Fractum! This guide explains how to contribute to the project.

Ways to Contribute¶

There are many ways to contribute to Fractum:

Reporting bugs: Help identify issues in the codebase
Suggesting enhancements: Propose new features or improvements
Improving documentation: Help make the documentation more clear and comprehensive
Contributing code: Implement fixes or new features
Reviewing pull requests: Help review and test changes from other contributors

Getting Started¶

Setting Up Your Development Environment¶

Fork the repository:
Visit https://github.com/katvio/fractum
Click the "Fork" button in the top-right corner

Clone your fork:

git clone https://github.com/YOUR_USERNAME/fractum.git
cd fractum

Set up your development environment:
Follow the Manual Installation guide
Make sure to activate the virtual environment

Add the upstream repository:

git remote add upstream https://github.com/katvio/fractum.git

Development Workflow¶

Create a new branch for your changes:
```
git checkout -b your-feature-branch
```
Make your changes:
Write your code
Add or update tests as needed
Update documentation to reflect your changes
Run tests:
```
cd tests ; python run_tests.py
```

Commit your changes:

git add .
git commit -m "Description of your changes"

Push to your fork:
```
git push origin your-feature-branch
```
Create a pull request:
Go to your fork on GitHub
Click "New Pull Request"
Select your branch and describe your changes

Coding Standards¶

When contributing to Fractum, please follow these guidelines:

Python Code Style¶

Follow PEP 8 for code style
Use type hints when defining functions
Write docstrings for classes and functions
Keep functions focused and small when possible

Code Quality Tools¶

ruff
safety/pip-audit
bandit
mypy

Testing¶

Write unit tests for new functionality
Ensure all tests pass before submitting a pull request
Aim for high code coverage

Security Considerations¶

Follow secure coding practices
Be especially careful with cryptographic operations
Avoid introducing dependencies unless absolutely necessary
Consider the offline-first nature of Fractum

Pull Request Process¶

Update your branch: Before submitting, merge the latest upstream changes
```
git fetch upstream
git merge upstream/main
```
Submit your pull request: Include a clear description of the changes and any relevant issue numbers
Respond to feedback: Be open to feedback and make requested changes
Wait for review: Maintainers will review your pull request and provide feedback

Reporting Bugs¶

When reporting bugs, please include:

A clear, descriptive title
Steps to reproduce the issue
Expected behavior
Actual behavior
Your operating system and Fractum version
Any relevant logs or error messages

Suggesting Enhancements¶

Feature requests are welcome! When suggesting enhancements:

Describe the feature clearly
Explain why it would be valuable
Consider how it aligns with Fractum's core principles (offline-first, security, etc.)
If possible, outline how it might be implemented

Community Guidelines¶

Be respectful and inclusive
Focus on the technical merits of ideas
Help others when you can
Accept constructive criticism gracefully

Any contribution is welcome¶

Any contribution is better than no contribution :-) Submit a pull request or open an issue even if you are not sure or if you feel the contribution is not significant enough.