Contributing

Guidelines for contributing to the Reserve Folio protocol

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

1. Fork the Repository

   Fork the Reserve Folio repository to your GitHub account.

2. Clone Your Fork

   git clone https://github.com/YOUR_USERNAME/reserve-index-dtf.git
   cd reserve-index-dtf
   
3. Set Up Development Environment

   Follow the setup guide to configure your local environment.

4. 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:

1. Descriptive Title

   Use a clear, concise title summarizing the change:

   • ✅ “Add progressive auction sizing for improved price discovery”
   • ❌ “Update stuff”
2. 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
3. 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

1. Automated Checks

   CI/CD pipeline runs:

   • Code formatting verification
   • Linting checks
   • Full test suite
   • Gas usage analysis
2. Peer Review

   Core contributors review:

   • Code quality and style
   • Security considerations
   • Gas optimization opportunities
   • Test coverage
3. Revisions

   Address review comments and push updates:

   git add .
   git commit -m "refactor: address review comments"
   git push origin feature/your-feature-name
   
4. 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:

1. Email: [e-mail]
2. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)
3. 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:

1. Check existing GitHub Discussions
2. Review documentation
3. Open a new discussion
4. 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!