Usage Rules

IMPORTANT: Consult these usage rules early and often when working with the packages listed below. Before attempting to use any of these packages or to discover if you should use them, review their usage rules to understand the correct patterns, conventions, and best practices.

usage_rules usage

A dev tool for Elixir projects to gather LLM usage rules from dependencies

Using Usage Rules

Many packages have usage rules, which you should thoroughly consult before taking any action. These usage rules contain guidelines and rules directly from the package authors. They are your best source of knowledge for making decisions.

Modules & functions in the current app and dependencies

When looking for docs for modules & functions that are dependencies of the current project, or for Elixir itself, use mix usage_rules.docs

# Search a whole module
mix usage_rules.docs Enum

# Search a specific function
mix usage_rules.docs Enum.zip

# Search a specific function & arity
mix usage_rules.docs Enum.zip/1

Searching Documentation

You should also consult the documentation of any tools you are using, early and often. The best way to accomplish this is to use the usage_rules.search_docs mix task. Once you have found what you are looking for, use the links in the search results to get more detail. For example:

# Search docs for all packages in the current application, including Elixir
mix usage_rules.search_docs Enum.zip

# Search docs for specific packages
mix usage_rules.search_docs Req.get -p req

# Search docs for multi-word queries
mix usage_rules.search_docs "making requests" -p req

# Search only in titles (useful for finding specific functions/modules)
mix usage_rules.search_docs "Enum.zip" --query-by title

usage_rules:elixir usage

Elixir Core Usage Rules

Pattern Matching

Use pattern matching over conditional logic when possible
Prefer to match on function heads instead of using if/else or case in function bodies
%{} matches ANY map, not just empty maps. Use map_size(map) == 0 guard to check for truly empty maps

Error Handling

Use {:ok, result} and {:error, reason} tuples for operations that can fail
Avoid raising exceptions for control flow
Use with for chaining operations that return {:ok, _} or {:error, _}

Common Mistakes to Avoid

Elixir has no return statement, nor early returns. The last expression in a block is always returned.
Don't use Enum functions on large collections when Stream is more appropriate
Avoid nested case statements - refactor to a single case, with or separate functions
Don't use String.to_atom/1 on user input (memory leak risk)
Lists and enumerables cannot be indexed with brackets. Use pattern matching or Enum functions
Prefer Enum functions like Enum.reduce over recursion
When recursion is necessary, prefer to use pattern matching in function heads for base case detection
Using the process dictionary is typically a sign of unidiomatic code
Only use macros if explicitly requested
There are many useful standard library functions, prefer to use them where possible

Function Design

Use guard clauses: when is_binary(name) and byte_size(name) > 0
Prefer multiple function clauses over complex conditional logic
Name functions descriptively: calculate_total_price/2 not calc/2
Predicate function names should not start with is and should end in a question mark.
Names like is_thing should be reserved for guards

Data Structures

Use structs over maps when the shape is known: defstruct [:name, :age]
Prefer keyword lists for options: [timeout: 5000, retries: 3]
Use maps for dynamic key-value data
Prefer to prepend to lists [new | list] not list ++ [new]

Mix Tasks

Use mix help to list available mix tasks
Use mix help task_name to get docs for an individual task
Read the docs and options fully before using tasks

Testing

Run tests in a specific file with mix test test/my_test.exs and a specific test with the line number mix test path/to/test.exs:123
Limit the number of failed tests with mix test --max-failures n
Use @tag to tag specific tests, and mix test --only tag to run only those tests
Use assert_raise for testing expected exceptions: assert_raise ArgumentError, fn -> invalid_function() end
Use mix help test to for full documentation on running tests

Debugging

Use dbg/1 to print values while debugging. This will display the formatted value and other relevant information in the console.

usage_rules:otp usage

OTP Usage Rules

GenServer Best Practices

Keep state simple and serializable
Handle all expected messages explicitly
Use handle_continue/2 for post-init work
Implement proper cleanup in terminate/2 when necessary

Process Communication

Use GenServer.call/3 for synchronous requests expecting replies
Use GenServer.cast/2 for fire-and-forget messages.
When in doubt, use call over cast, to ensure back-pressure
Set appropriate timeouts for call/3 operations

Fault Tolerance

Set up processes such that they can handle crashing and being restarted by supervisors
Use :max_restarts and :max_seconds to prevent restart loops

Task and Async

Use Task.Supervisor for better fault tolerance
Handle task failures with Task.yield/2 or Task.shutdown/2
Set appropriate task timeouts
Use Task.async_stream/3 for concurrent enumeration with back-pressure

igniter usage

A code generation and project patching framework

igniter usage rules

Quality Guidelines

MANDATORY Pre-Commit Quality Gates

STOP: Before considering ANY work complete or committing code, you MUST run ALL quality checks:

# Complete quality gate check (run this EVERY TIME)
mix format --check-formatted && \
mix credo --strict && \
mix test && \
mix audit

Why this matters: Examples and tests must pass compilation and linting. When examples fail, users cannot learn from them. Always validate the entire project, not just the code you changed.

If any check fails:

STOP immediately
Fix the root cause (don't suppress warnings)
Re-run all checks
Only proceed when all pass

Additional Quality Practices

Write unit tests for new functions
Ensure existing tests pass when updating code
Run mix test after writing/updating tests
Run mix test --cover on task completion (coverage above threshold)
Run mix credo --strict on task completion and fix issues

Security Guidelines

Run mix deps.audit and mix hex.audit after dependency changes
Run mix hex.outdated to check outdated dependencies
Run mix sobelow --config on task completion and fix issues

Release Process

Versioning

Follow semantic versioning (semver): MAJOR.MINOR.PATCH
Update version in mix.exs
Update CHANGELOG.md with release notes

Publishing a Release

The release pipeline is fully automated. When you create a GitHub release, the CI/CD workflow will:

Run all quality checks (format, credo, test, security audit)
Build and publish the package to Hex.pm
Deploy documentation to GitHub Pages

Steps to Release

# 1. Update version in mix.exs (e.g., @version "1.1.0")

# 2. Update CHANGELOG.md
#    - Add new version section with date: ## [1.1.0] - YYYY-MM-DD
#    - Document all changes under appropriate headers (Added, Changed, Fixed, etc.)

# 3. Commit and push
git add mix.exs CHANGELOG.md
git commit -m "chore: prepare v1.1.0 release"
git push origin main

# 4. Create GitHub release (this triggers the publish)
gh release create v1.1.0 \
  --title "v1.1.0 - Release Title" \
  --notes "## What's New

- Feature 1
- Feature 2

See [CHANGELOG.md](CHANGELOG.md) for full details."

The pipeline will automatically publish to Hex.pm using the HEX_API_KEY secret configured in the repository.

CI/CD Pipeline

The GitHub Actions workflow (.github/workflows/build.yml) runs:

Trigger	Quality Checks	Docs Deploy	Hex Publish
Push to main	✅	❌	❌
Pull request	✅	❌	❌
Release published	✅	✅	✅

Required GitHub Secrets:

HEX_API_KEY - Hex.pm API key for publishing (generate with mix hex.user key generate)

Pre-Release Checklist

Before creating a release:

[ ] All tests pass: mix test
[ ] Format check passes: mix format --check-formatted
[ ] Credo passes: mix credo --strict
[ ] Security audit clean: mix audit
[ ] Docs build: mix docs
[ ] Version updated in mix.exs
[ ] CHANGELOG.md updated
[ ] Changes committed and pushed to main

Useful Commands

Development

mix deps.get       # Install dependencies
mix compile        # Compile project

Testing

mix test                           # All tests
mix test test/path/to/test.exs     # Specific file
mix test test/path/to/test.exs:42  # Specific line
mix test --cover                   # With coverage

Quality Checks

mix format                    # Format code
mix format --check-formatted  # Check formatting
mix credo --strict            # Linting
mix audit                     # Security audit

Documentation

mix docs        # Generate documentation

Before Committing

mix format --check-formatted && mix credo --strict && mix test && mix audit

← Previous Page Overview