Skip to content

# Contributing to Fractum

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

## Quick Links

- 🐛 Report Issues: GitHub Issues
- 💬 Join Discussions: GitHub Discussions
- 🗺️ View Roadmap & Features: Project Kanban Board

## 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

1. Fork the repository:
2. Visit https://github.com/katvio/fractum

3. Click the "Fork" button in the top-right corner

4. Clone your fork:

   Bash

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

5. Set up your development environment:

6. Follow the Manual Installation guide

7. Make sure to activate the virtual environment

8. Add the upstream repository:

   Bash

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

### Development Workflow

1. Create a new branch for your changes:

   Bash

       git checkout -b your-feature-branch

2. Make your changes:

3. Write your code
4. Add or update tests as needed

5. Update documentation to reflect your changes

6. Run tests:

   Bash

       cd tests ; python run_tests.py

7. Commit your changes:

   Bash

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

8. Push to your fork:

   Bash

       git push origin your-feature-branch

9. Create a pull request:

10. Go to your fork on GitHub
11. Click "New Pull Request"
12. 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

1. Update your branch: Before submitting, merge the latest upstream changes

   Bash

       git fetch upstream
       git merge upstream/main

2. Submit your pull request: Include a clear description of the changes and any relevant issue numbers

3. Respond to feedback: Be open to feedback and make requested changes

4. Wait for review: Maintainers will review your pull request and provide feedback

## Reporting Bugs

When reporting bugs, please create a new issue and 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! You can suggest enhancements through:

- GitHub Issues: For specific feature requests with clear implementation paths
- GitHub Discussions: For broader ideas and community feedback
- Project Roadmap: Check what's already planned or in progress

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.

Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Help us improve by opening an issue.