Contributing to Sayfa

Copy Markdown View Source

Thank you for your interest in contributing to Sayfa! Whether it's a bug report, feature request, documentation improvement, or code contribution, every bit helps.

Types of Contributions

  • Bug reports — Found something broken? Open an issue.
  • Feature requests — Have an idea? Suggest it.
  • Documentation — Typo fixes, better examples, translations.
  • Code — Bug fixes, new features, performance improvements.

Development Setup

Requirements

  • Elixir ~> 1.19 (OTP 27+)
  • Rust (latest stable) — required for MDEx NIF compilation

Getting Started

git clone https://github.com/furkanural/sayfa.git
cd sayfa
mix deps.get
mix test

Verify everything passes before making changes.

Workflow

  1. Fork the repository
  2. Create a branch from main:
    • feature/short-description for new features
    • fix/issue-description for bug fixes
    • docs/what-changed for documentation
  3. Write your code following the style conventions below
  4. Add tests for any new functionality
  5. Run checks:
    mix test
mix format
mix credo --strict
  6. Submit a pull request against main

Code Style

  • Follow existing patterns in the codebase
  • Every public module needs @moduledoc
  • Every public function needs @doc with examples and @spec
  • Use {:ok, result} / {:error, reason} tuples; provide ! variants that raise
  • Use Path.join/2 for file paths (cross-platform compatibility)
  • Refer to CLAUDE.md for detailed conventions

Commit Messages

Follow Conventional Commits:

feat: add Atom feed generation
fix: handle empty front matter
docs: add block usage examples
refactor: simplify build pipeline
test: add content parser tests
chore: update dependencies

Pull Request Guidelines

  • Reference the related issue (e.g., "Closes #42")
  • Describe what changed and why
  • Add tests covering the change
  • Keep PRs focused — one concern per PR
  • Update CHANGELOG.md for user-facing changes

Testing

mix test                              # Run all tests
mix test test/sayfa/content_test.exs  # Run a specific file
mix test --cover                      # With coverage report
  • Write unit tests for individual modules
  • Write integration tests for pipeline-level changes
  • Use temporary directories for tests that write to disk

Review Process

  1. A maintainer will review your PR
  2. Changes may be requested — this is normal and collaborative
  3. Once approved, a maintainer will merge it

Questions?

Open an issue or start a discussion. We're happy to help!