Development workflow

Follow this workflow when contributing to Erst to ensure smooth collaboration and maintain code quality.

Branch naming

Create descriptive branch names based on the type of work:

Features: feat/my-feature-name
Bug fixes: fix/issue-description
Documentation: docs/update-description
Refactoring: refactor/component-name
Tests: test/test-description

# Create a feature branch
git checkout -b feat/add-source-mapping

# Create a bugfix branch
git checkout -b fix/handle-network-timeout

Development steps

Sync with main branch

Before starting work, ensure your local main branch is up to date:

git checkout main
git pull origin main

Create a new branch

Create a branch for your feature or bug fix:

git checkout -b feat/my-feature

Make your changes

Write your code following the code standards.

Test locally

Run all tests and linting before committing:

go test ./...
cargo test --all

go fmt ./...
cd simulator && cargo fmt --all

golangci-lint run ./...
cd simulator && cargo clippy --all-targets -- -D warnings

Or use Make targets:

make test
make rust-test
make lint-all-strict

Commit your changes

Follow the commit message convention:

git add .
git commit -m "feat(sim): add transaction replay caching"

Push and create a pull request

Push your branch and create a PR on GitHub:

git push origin feat/my-feature

Then create a PR with a detailed description.

Address review feedback

Make requested changes, commit, and push:

git add .
git commit -m "fix: address review comments"
git push origin feat/my-feature

Commit message convention

Erst follows the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: A new feature
fix: A bug fix
test: Adding or improving tests
docs: Documentation changes
refactor: Code refactoring without feature changes
perf: Performance improvements
chore: Build, CI, or dependency updates
ci: CI/CD configuration changes

Scopes

Use specific areas of the codebase:

sim: Simulator (Rust)
cli: CLI interface (Go)
updater: Update mechanism
trace: Trace viewer
analyzer: Transaction analyzer
rpc: RPC client

Examples

feat(sim): add protocol version spoofing for harness

Implements protocol version override to allow testing
transactions from different network versions locally.

Closes #350

fix(updater): handle network timeouts gracefully

Previously, network timeouts would cause the updater to panic.
Now we retry with exponential backoff up to 3 times.

Fixes #412

test(sim): add 1000+ transaction regression suite

Adds comprehensive regression tests using real mainnet
transactions to prevent future breakage.

docs: add comprehensive contribution guidelines

Commit rules

Keep subject under 50 characters
Use imperative mood: “add” not “added” or “adds”
No period at the end of the subject
Provide detailed explanation in the body if the change is non-obvious
Reference related issues: Closes #350, Refs #343

Never use emojis in commit messages or PR titles.

Pull request structure

Create clear, well-documented pull requests:

PR title

Follow the same format as commit messages:

feat(sim): add transaction replay caching

PR description template

## Description
Brief explanation of the changes and why they're needed.

## Related issues
Closes #350, relates to #343

## Changes made
- Added caching layer for transaction replay
- Implemented LRU eviction policy
- Added configuration options for cache size

## Testing
- Added unit tests for cache operations
- Added integration tests for replay with cache
- Tested with 1000+ transaction replays
- Verified 3x performance improvement

## Breaking changes
None

## Checklist
- [x] Code follows style guidelines
- [x] Tests added/updated
- [x] Documentation updated
- [x] No new warnings or errors
- [x] All tests pass locally
- [x] Strict linting passes

PR checks

Before submitting, ensure:

All CI checks pass
Code coverage doesn’t decrease
All tests pass locally
Strict linting passes (make lint-all-strict)
Documentation is updated if needed

The CI pipeline will automatically run tests, linting, and coverage checks. PRs with failing checks will not be merged.

Formatting and linting

Run formatting and linting before every commit:

Format code

make fmt-go

make fmt-rust

make fmt

Run linting

make lint-strict

make rust-lint-strict

make lint-all-strict

Using pre-commit hooks

Install pre-commit hooks to automatically check your code:

Install pre-commit

pip install pre-commit

Install hooks

pre-commit install

Or use Make:

make pre-commit

Run manually

Test the hooks on all files:

pre-commit run --all-files

Pre-commit hooks will automatically:

Format Go code with gofmt
Format Rust code with cargo fmt
Run golangci-lint
Run cargo clippy
Check for merge conflicts
Validate YAML files

Code review checklist

When reviewing PRs, ensure:

Common development tasks

Building the project

# Build Go CLI
go build -o erst cmd/erst/main.go

# Or use Make
make build

# Build for release (optimized)
make build-release

# Build Rust simulator
cd simulator && cargo build --release

# Or use Make
make rust-build

Building for specific OS

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o erst-linux-amd64 ./cmd/erst

# macOS ARM64
GOOS=darwin GOARCH=arm64 go build -o erst-darwin-arm64 ./cmd/erst

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o erst-windows-amd64.exe ./cmd/erst

Cleaning build artifacts

# Clean Go artifacts
go clean
go clean -cache

# Clean Rust artifacts
cd simulator && cargo clean

# Clean all (using Make)
make clean

Installing dependencies

# Go dependencies
go mod tidy
go mod download

# Or use Make
make deps

# Rust dependencies
cd simulator && cargo fetch

Updating dependencies

# Update Go dependencies
go get -u ./...
go mod tidy

# Update Rust dependencies
cd simulator && cargo update

Addressing review feedback

When maintainers request changes:

Make the requested changes in your local branch
Commit with a descriptive message: fix: address review comments on error handling
Push to your branch: git push origin feat/my-feature
Reply to comments explaining your changes
Re-request review when ready

Don’t force-push unless you’re rebasing or squashing commits. Regular pushes preserve the review history.

Rebasing and squashing

Before merging, you may be asked to rebase or squash commits:

# Rebase onto latest main
git checkout main
git pull origin main
git checkout feat/my-feature
git rebase main

# Squash last 3 commits
git rebase -i HEAD~3

# Force push after rebase (only if necessary)
git push -f origin feat/my-feature

Only force-push to your feature branch, never to main. Be careful when force-pushing to branches others are working on.

Getting unblocked

If you’re stuck:

Review the documentation in docs/
Check existing issues for similar problems
Ask in GitHub Discussions for general questions
Create an issue for specific bugs or feature questions
Tag maintainers in your PR if you need guidance

Important reminders

No emojis in commit messages or PR titles
No vague messages like “fixes stuff” or “updates things”
Always run strict linting before pushing
All tests must pass before requesting review
Update documentation when changing functionality
Reference issues in commit messages and PRs

Testing

​Branch naming

​Development steps

​Commit message convention

​Types

​Scopes

​Examples

​Commit rules

​Pull request structure

​PR title

​PR description template

​PR checks

​Formatting and linting

​Format code

​Run linting

​Using pre-commit hooks

​Code review checklist

​Common development tasks

​Addressing review feedback

​Rebasing and squashing

​Getting unblocked

​Important reminders

Branch naming

Development steps

Commit message convention

Types

Scopes

Examples

Commit rules

Pull request structure

PR title

PR description template

PR checks

Formatting and linting

Format code

Run linting

Using pre-commit hooks

Code review checklist

Common development tasks

Addressing review feedback

Rebasing and squashing

Getting unblocked

Important reminders