Skip to content

Contributing to Karmafun

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

Code of Conduct

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.

Getting Started

Branch Naming Conventions

  • 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

Commit Style

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

Creating Issues

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

Bug Reports

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

Feature Requests

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

Questions

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.

Helpful Resources

Contribution Workflow

Step-by-Step Process

  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

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

  2. Create a branch from main:

git checkout -b feature/your-feature-name

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

  2. 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
  1. Push and create PR:
git push origin feature/your-feature-name
  • Create a pull request to main
  • Reference the issue (e.g., "Fixes #123")
  1. Respond to review: - Address feedback promptly - Push additional commits as needed - Once approved, a maintainer will merge your PR

Additional Resources

Development Guidelines

Commit Guidelines

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.

Commit Messages

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")

Code Style

Follow the platform conventions. For Go, reference:

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

Testing

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

Versioning

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

Documentation

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

Adding Documentation

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 .

Local Preview

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.