Thank you for considering contributing to Karmafun! We welcome contributions from the community to help improve the project.

This project and everyone participating in it is governed by the Karmafun Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to antoine@mrtn.me.

• main - Main development branch
• deploy/* - Continuous deployment branches (created by CI/CD)
• Use lowercase with hyphens (-) instead of underscores
• You can create a branch from an issue in the Github UI. It will prefix the branch name with the issue number.
• If you create a branch manually, use one of these prefixes:
  • feature/ - New features
  • fix/ - Bug fixes
  • build/ - Build system changes
  • doc/ - Documentation updates
  • chore/ - Miscellaneous tasks (e.g., refactoring, tooling)

Example: feature/add-container-support or fix/memory-leak

We use gitmoji for commit messages. Consider using the VS Code Plugin to make this easier.

Examples:

• ✨ add container registry support
• 🐛 fix memory leak in image builder
• 📝 update installation guide

Before creating a new issue, please search existing issues to avoid duplicates.

Include the following information:

• Title: Concise description of the problem
• Steps to reproduce: Detailed steps to trigger the bug
• Expected vs actual behavior: What should happen and what does happen
• Environment: OS, Go version, Karmafun version, relevant configuration
• Additional context: Screenshots, logs, or error messages

Describe:

• Problem: What problem does this solve?
• Proposed solution: Your suggested approach
• Alternatives: Other solutions you've considered
• Use cases: Examples or scenarios that illustrate the need

For questions about using Karmafun:

1. Check the documentation first
2. Search existing issues and discussions
3. If still needed, open an issue with context and relevant code snippets

Consider using GitHub Discussions for general questions and community support.

• GitHub: Creating an Issue
• How to Write a Good Bug Report
• Mozilla: Bug Writing Guidelines
• RStudio: Writing Good Feature Requests

1. Fork and clone:

   git clone https://github.com/YOUR-USERNAME/karmafun.git
   cd karmafun
   git remote add upstream https://github.com/karmafun/karmafun.git

2. Create an issue at github.com/karmafun/karmafun/issues to track your contribution.

3. Create a branch from main:

   git checkout -b feature/your-feature-name

4. Make your changes:

   • Write code following the code style guidelines
   • Add unit tests (aim for >85% coverage)
   • Test locally: go test ./...

5. Prepare for submission:

   # Fetch and rebase on latest main
   git fetch upstream
   git rebase upstream/main
   
   # Run pre-commit checks
   pre-commit run --all-files

6. Push and create PR:

   git push origin feature/your-feature-name

   • Create a pull request to main
   • Reference the issue (e.g., "Fixes #123")

7. Respond to review:

   • Address feedback promptly
   • Push additional commits as needed
   • Once approved, a maintainer will merge your PR

• How to Contribute to Open Source
• GitHub Flow
• Fork and Pull Request Workflow
• Git Forks and Upstreams

Key principles:

• Keep commits focused and atomic
• Squash commits that fix issues introduced in the PR with the commit that introduced them
• Rebase to maintain a clean history
• Separate formatting changes from functional changes
• Remove empty commits from rebases

Learn about rebasing and rewriting history.

Follow this guide for writing good commit messages. Keeping the first line under 50 characters is recommended but not enforced. Keep it short but descriptive.

Using gitmoji with Conventional Commits:

• Replace conventional types (feat:, fix:) with emojis (e.g., ✨, 🐛)
• Link to issues with # (e.g., "Fixes #123")

Follow the platform conventions. For Go, reference:

• Effective Go
• The Go Style Guide

General guidelines:

• ✅ Use consistent naming conventions (camelCase, snake_case, etc.)
• ✅ Write descriptive names - avoid abbreviations
• ✅ Fix typos immediately (project uses CSpell with pre-commit)
• ✅ Use English for all identifiers
• ✅ Use verbs for methods, nouns for properties
• ✅ Keep methods small and focused
• ✅ Prefer loose coupling
• ✅ Fail fast and explicitly - never fail silently

• Write unit tests for all changes
• Aim for >85% code coverage
• Run tests locally before submitting: go test ./...

We follow Semantic Versioning (MAJOR.MINOR.PATCH).

We encourage documentation contributions! Documentation is in the docs directory, written in Markdown and built with MkDocs using Material for MkDocs.

Navigation is managed by awesome-nav. Main categories are defined in docs/docs/.nav.yml.

For files outside docs/docs, create symbolic links:

cd docs/docs/some/category
ln -s ../../../../path/to/your/README.md .

!!! tip "Required Tools"

Python and uv

Preview documentation while editing:

cd docs
uv run mkdocs serve --livereload

Then browse at http://localhost:8000/. Stop with CTRL+C.