Contributing - Reserve Folio

Welcome Contributors

Thank you for your interest in contributing to Reserve Folio! This guide will help you understand our development process and how to make meaningful contributions.

Reserve Folio is an open-source protocol. We welcome contributions from developers of all experience levels.

Code of Conduct

Be respectful, professional, and constructive in all interactions. We’re building a collaborative community focused on creating secure, reliable DeFi infrastructure.

Getting Started

Fork the Repository

Fork the Reserve Folio repository to your GitHub account.

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/reserve-index-dtf.git
cd reserve-index-dtf

Set Up Development Environment

Follow the setup guide to configure your local environment.

Create a Branch

Create a branch for your contribution:

git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/auction-improvements
fix/rebalance-overflow
docs/update-deployment-guide

Types of Contributions

Bug Fixes

Fix issues, resolve errors, and improve stability

Features

Add new functionality and capabilities

Documentation

Improve guides, add examples, fix typos

Tests

Expand test coverage and add edge cases

Optimizations

Reduce gas costs and improve performance

Security

Report vulnerabilities and security improvements

Development Workflow

1. Make Your Changes

Follow these best practices:

Write Clean Code

Follow existing code style and conventions
Use clear, descriptive variable and function names
Add comments for complex logic
Keep functions focused and modular

Follow Solidity Best Practices

Use Solidity 0.8.28
Leverage built-in overflow protection
Follow Solidity Style Guide
Use NatSpec documentation format

Maintain Documentation

Update inline comments and NatSpec
Document complex algorithms and formulas
Use units notation ({tok}, D27{tok/share}, etc.)
Update README.md if adding major features

2. Write Tests

All code contributions must include tests:

test/YourFeature.t.sol

contract YourFeatureTest is BaseTest {
    function setUp() public override {
        super.setUp();
        // Additional setup
    }
    
    function test_YourNewFeature() public {
        // Arrange
        // Act
        // Assert
    }
    
    function test_RevertWhen_InvalidInput() public {
        vm.expectRevert(ExpectedError.selector);
        // Action that should revert
    }
    
    function test_extreme_BoundaryCondition() public {
        // Extreme test case
    }
}

Aim for high test coverage. New features should have >95% coverage.

3. Run Quality Checks

Before committing, run all quality checks:

# Format code
yarn format

# Run linter
yarn lint

# Compile contracts
yarn compile

# Run tests
yarn test:all

# Check coverage
yarn coverage:summary

# Check contract sizes
yarn size

All checks must pass before submitting a pull request.

4. Commit Your Changes

Use clear, descriptive commit messages following Conventional Commits:

# Feature
git commit -m "feat: add progressive auction sizing"

# Bug fix
git commit -m "fix: prevent overflow in basket weight calculation"

# Documentation
git commit -m "docs: update rebalancing guide with examples"

# Tests
git commit -m "test: add extreme cases for auction pricing"

# Refactor
git commit -m "refactor: optimize gas usage in mint function"

Commit message format:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or modifications
refactor: Code refactoring
perf: Performance improvements
chore: Maintenance tasks

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub with:

Descriptive Title

Use a clear, concise title summarizing the change:

✅ “Add progressive auction sizing for improved price discovery”
❌ “Update stuff”

Detailed Description

Include:

What: What changes were made
Why: Why these changes are needed
How: How the implementation works
Testing: What tests were added/modified

Link Issues

Reference related issues:

Closes #123
Relates to #456

Pull Request Template

## Summary

Brief description of the changes.

## Changes

- Added feature X
- Fixed bug Y
- Updated documentation for Z

## Testing

- [ ] All existing tests pass
- [ ] Added new tests for new features
- [ ] Ran extreme tests
- [ ] Checked gas usage
- [ ] Manual testing completed

## Checklist

- [ ] Code follows style guidelines
- [ ] NatSpec documentation added/updated
- [ ] Tests added with >95% coverage
- [ ] All quality checks pass
- [ ] README updated (if needed)

## Related Issues

Closes #XXX

Code Review Process

Automated Checks

CI/CD pipeline runs:

Code formatting verification
Linting checks
Full test suite
Gas usage analysis

Peer Review

Core contributors review:

Code quality and style
Security considerations
Gas optimization opportunities
Test coverage

Revisions

Address review comments and push updates:

git add .
git commit -m "refactor: address review comments"
git push origin feature/your-feature-name

Approval and Merge

Once approved, maintainers will merge your contribution.

Code Style Guidelines

Solidity Conventions

// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

/**
 * @title ContractName
 * @notice Brief description of contract purpose
 * @dev Additional implementation details
 */
contract ContractName {
    // State variables
    uint256 public constant MAX_VALUE = 1e27;
    uint256 private _internalValue;
    
    // Events
    event ValueUpdated(uint256 oldValue, uint256 newValue);
    
    // Errors
    error InvalidValue(uint256 value);
    
    /**
     * @notice Updates the internal value
     * @param newValue The new value to set
     * @dev Emits ValueUpdated event
     */
    function updateValue(uint256 newValue) external {
        if (newValue > MAX_VALUE) revert InvalidValue(newValue);
        uint256 oldValue = _internalValue;
        _internalValue = newValue;
        emit ValueUpdated(oldValue, newValue);
    }
}

Formatting Rules

Indentation: 4 spaces (no tabs)
Line length: Maximum 120 characters
Naming:
- Contracts: PascalCase
- Functions: camelCase
- Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Internal/private: _leadingUnderscore
Imports: Organized and grouped logically
Comments: Use NatSpec for all public/external functions

Units Notation

Always document units in comments:

// {share} = {tok} * D27 / D27{tok/share}
uint256 shares = (tokenAmount * D27) / tokensPerShare;

// D27{tok/share} = {tok} * D27 / {share}
uint256 tokensPerShare = (totalTokens * D27) / totalShares;

Units notation:

{tok}, {share}, {reward}: Token balances
D18{1}: Percentage (18 decimals)
D27{tok/share}: Exchange rate (27 decimals)
D27{UoA/tok}: Price in nanoUSD (27 decimals)
{s}: Seconds

Security Considerations

Security is paramount. Always consider:

Reentrancy attacks
Integer overflow/underflow (use Solidity 0.8.x)
Access control
Input validation
Gas limit issues
Front-running vulnerabilities

Security Checklist

Reporting Security Vulnerabilities

DO NOT open public issues for security vulnerabilities.

If you discover a security vulnerability:

Email: security@reserve.org
Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)
Wait for confirmation before public disclosure

We take security seriously and will respond promptly to all reports.

Gas Optimization

When optimizing for gas:

Use Gas Profiling

forge test --gas-report

Compare Before/After

Document gas savings in PRs

Common optimizations:

Use calldata instead of memory for read-only parameters
Cache storage variables in memory
Use uint256 instead of smaller types (unless packing)
Avoid unnecessary storage writes
Use custom errors instead of string reverts

Documentation Guidelines

NatSpec Format

/**
 * @notice User-facing description of function purpose
 * @dev Technical details for developers
 * @param paramName Description of parameter
 * @return Description of return value
 */
function exampleFunction(uint256 paramName) external returns (uint256) {
    // Implementation
}

Inline Comments

// Calculate new shares with 27 decimals of precision
// {share} = {tok} * D27 / D27{tok/share}
uint256 newShares = (depositAmount * D27) / exchangeRate;

Community

GitHub Discussions

Ask questions and share ideas

Discord

Join the Reserve Protocol community

Recognition

Valuable contributions are recognized through:

Attribution in release notes
Contributor badges
Potential bug bounty rewards
Community acknowledgment

Questions?

If you have questions about contributing:

Check existing GitHub Discussions
Review documentation
Open a new discussion
Reach out on Discord

Thank You!

Your contributions help make Reserve Folio more secure, efficient, and accessible. We appreciate your time and effort in improving the protocol.

Start Contributing

Ready to contribute? Fork the repository and start building!

Get Started

Core Concepts

Guides

Advanced

Development

Documentation Index

​Welcome Contributors

​Code of Conduct

​Getting Started

​Types of Contributions

Bug Fixes

Features

Documentation

Tests

Optimizations

Security

​Development Workflow

​1. Make Your Changes

​2. Write Tests

​3. Run Quality Checks

​4. Commit Your Changes

​5. Push and Create Pull Request

​Pull Request Template

​Code Review Process

​Code Style Guidelines

​Solidity Conventions

​Formatting Rules

​Units Notation

​Security Considerations

​Security Checklist

​Reporting Security Vulnerabilities

​Gas Optimization

Use Gas Profiling

Compare Before/After

​Documentation Guidelines

​NatSpec Format

​Inline Comments

​Community

GitHub Discussions

Discord

​Recognition

​Questions?

​Thank You!

Start Contributing

Build docs developers (and LLMs) love

Welcome Contributors

Code of Conduct

Getting Started

Types of Contributions

Development Workflow

1. Make Your Changes

2. Write Tests

3. Run Quality Checks

4. Commit Your Changes

5. Push and Create Pull Request

Pull Request Template

Code Review Process

Code Style Guidelines

Solidity Conventions

Formatting Rules

Units Notation

Security Considerations

Security Checklist

Reporting Security Vulnerabilities

Gas Optimization

Documentation Guidelines

NatSpec Format

Inline Comments

Community

Recognition

Questions?

Thank You!