Skip to content

Instantly share code, notes, and snippets.

@mikehostetler

mikehostetler/best_practices.md

Created August 3, 2025 13:05
Show Gist options
  • Save mikehostetler/a3795e1d8ad0012667e4435128193596 to your computer and use it in GitHub Desktop.
Save mikehostetler/a3795e1d8ad0012667e4435128193596 to your computer and use it in GitHub Desktop.
Download ZIP
Elixir Package best practices
Raw
best_practices.md

Elixir Open Source Best Practices Checklist

A comprehensive quality checklist for high-quality open source Elixir modules. Use this checklist to evaluate and ensure your Elixir packages meet professional standards.

GitHub & CI/CD Infrastructure

GitHub Actions ✅

  • Comprehensive CI pipeline that runs on every PR and push to main
  • Multi-version testing matrix (test against multiple Elixir/OTP versions)
  • Automated formatting check (mix format --check-formatted)
  • Dependency audit (mix deps.unlock --check-unused)
  • Test coverage reporting with GitHub integration (mix coveralls.github)
  • Proper caching for dependencies and build artifacts
  • Security scanning for dependencies and code
  • Manual workflow dispatch option for maintainers

Dependabot Configuration ✅

  • Automated dependency updates with weekly schedule
  • Proper PR limits (e.g., max 10 open PRs)
  • Consistent labeling (dependencies, elixir tags)
  • Semantic commit messages with scope prefixes

Repository Setup

  • Clear repository description and topics/tags
  • Comprehensive README.md (see README section below)
  • Contributing guidelines (CONTRIBUTING.md)
  • Issue templates for bugs and features only
  • Pull request template with checklist

Mix.exs Configuration

Project Metadata ✅

  • Semantic versioning with clear version strategy
  • Complete project description and source URL
  • Proper Elixir version constraint (e.g., ~> 1.17)
  • Correct license specification (Apache-2.0, MIT, etc.)
  • Homepage and documentation URLs configured

Package Configuration ✅

  • Complete package metadata with maintainers
  • Appropriate files list (lib, mix.exs, README, LICENSE)
  • Relevant links (GitHub, docs, related projects)
  • Descriptive package summary

Dependencies & Development Tools ✅

  • Production dependencies properly versioned with ~>
  • Splode for error handling ({:splode, "~> 0.2"})
  • Complete dev/test toolchain:
    • credo for static analysis
    • dialyxir for type checking
    • doctor for documentation coverage
    • ex_doc for documentation generation
    • excoveralls for test coverage
    • expublish for release management
    • mix_test_watch for development
    • quokka for advanced formatting and code quality
    • Property testing with stream_data
    • Mocking with mimic (test only)

Mix Aliases & Commands ✅

  • Quality command (mix q or mix quality) that runs:
    • Code formatting
    • Format verification
    • Compilation with warnings as errors
    • Dialyzer type checking
    • Credo static analysis
  • Documentation command (mix docs) with browser opening
  • Test configuration that excludes flaky tests by default
  • Coverage thresholds defined (aim for >90%)

Documentation Excellence

README.md Structure ✅

  • Quality badges showing:
    • Hex.pm version
    • Documentation link
    • CI status
    • License
    • Test coverage
  • Clear project description and value proposition
  • Installation instructions with version specification
  • Quick start guide with runnable examples
  • Core concepts explanation
  • Comprehensive usage examples
  • API reference links
  • Contributing guidelines reference
  • License information
  • Related projects and ecosystem links

Code Documentation ✅

  • Complete @moduledoc for every public module
  • @doc strings for all public functions
  • @spec type specifications for public APIs
  • @typedoc for custom types
  • Doctests for simple examples
  • Usage examples in documentation
  • Error condition documentation
  • Parameter and return value descriptions

Guides & Tutorials ✅

  • Getting started guide for new users
  • Advanced usage guides for complex features
  • Architecture documentation explaining design decisions
  • Module map showing all modules and their purposes
  • API reference generated from code
  • Changelog with semantic versioning
  • Migration guides between major versions

Code Quality & Architecture

Code Style & Standards ✅

  • Consistent formatting with mix format
  • Snake_case for functions and variables
  • PascalCase for modules
  • Descriptive naming that explains intent
  • Pattern matching preferred over conditionals
  • Function heads for different argument patterns
  • Tagged tuples for return values ({:ok, result} | {:error, reason})

Error Handling ✅

  • Splode for error handling - consistent error structs and utilities
  • Specific error types for different failure modes
  • with statements for complex operations
  • No silent failures - all errors are handled or propagated
  • Documented error conditions in function specs
  • Minimal exception usage - prefer tagged tuples

Type Safety ✅

  • Dialyzer passes with zero warnings
  • Complete @spec definitions for public functions
  • Custom types defined with @type
  • Struct definitions using TypedStruct when appropriate
  • NimbleOptions for configuration validation

Performance & Scalability

  • Appropriate data structures for use cases
  • Efficient algorithms with documented complexity
  • Resource cleanup in all code paths
  • Memory usage consideration for long-running processes
  • Timeout handling for external operations
  • Benchmarking for performance-critical code

Testing Excellence

Test Coverage ✅

  • High test coverage (>90% line coverage)
  • Branch coverage for conditional logic
  • Edge case testing including error conditions
  • Property-based testing for complex logic
  • Integration tests for system behavior
  • Performance tests for critical paths

Test Organization ✅

  • Clear test structure mirroring lib directory
  • Descriptive test names explaining what's being tested
  • Grouped tests using describe blocks
  • Test helpers in support directory
  • Async tests where possible for speed
  • Proper test isolation with clean setup/teardown

Test Quality ✅

  • Both success and failure paths tested
  • Mock usage appropriate and minimal
  • Test data factories for complex structures
  • Flaky test management with proper tagging
  • Test documentation for complex test scenarios

Security & Compliance

Security Practices ✅

  • No secrets in code or documentation
  • Dependency vulnerability scanning
  • Input validation for all public APIs
  • Safe string interpolation

License & Legal ✅

  • Clear license (Apache-2.0, MIT, etc.)
  • License headers where required
  • Copyright attribution proper
  • Dependency license compatibility
  • Contributor agreements if needed

Release Management

Automated Release Process ✅

  • GitHub Action for Hex publishing with manual workflow dispatch
  • Automated version bumping (major/minor/patch) via workflow input
  • Automatic changelog updates with release notes
  • Quality gate enforcement (tests, format, dialyzer, credo before release)
  • Git tagging and GitHub releases automatically created
  • Documentation regeneration as part of release process

Version Control ✅

  • Semantic versioning (MAJOR.MINOR.PATCH)
  • Changelog maintenance with each release
  • Git tagging for releases
  • Release notes for major changes
  • Breaking change documentation

Publication ✅

  • Hex.pm publication with proper metadata
  • Documentation publishing to HexDocs
  • Package verification before release
  • Release automation via GitHub Actions

Community & Maintenance

Contributing ✅

  • Clear contribution guidelines
  • Code review process documented
  • Issue templates for different types
  • PR templates with checklists
  • Welcoming tone for new contributors

Maintenance ✅

  • Active maintenance with regular updates
  • Issue response time commitments
  • Deprecation strategy for breaking changes
  • Long-term support policy
  • Successor planning if needed

Bonus: Advanced Features

Observability ✅

  • Telemetry integration for metrics
  • Structured logging throughout application
  • Health checks for services
  • Monitoring guidelines in documentation

Developer Experience ✅

  • Live reloading support for development
  • Development scripts and helpers
  • Debugging guides and tools

Integration ✅

  • OTP application structure when appropriate
  • Supervision tree design documented

Scoring Guide

Excellent (90-100%): Production-ready, professional-grade package Good (80-89%): High quality with minor improvements needed
Fair (70-79%): Functional but needs significant quality improvements Poor (<70%): Not ready for production use

Example Reference: jido_signal

This checklist is based on the jido_signal package, which demonstrates most of these best practices in action. Use it as a reference implementation for quality standards.

Usage for Junior Engineers

  1. Self-assessment: Use this checklist to evaluate your own packages
  2. Code review: Reference specific items during PR reviews
  3. Project planning: Use as acceptance criteria for new packages
  4. Learning guide: Each item represents a skill to develop
  5. Quality gate: Require 85%+ compliance before production release

This checklist should be updated as the Elixir ecosystem evolves and new best practices emerge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment