> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/reserve-protocol/reserve-index-dtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## 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

<Steps>
  <Step title="Fork the Repository">
    Fork the [Reserve Folio repository](https://github.com/reserve-protocol/reserve-index-dtf) to your GitHub account.
  </Step>

  <Step title="Clone Your Fork">
    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/reserve-index-dtf.git
    cd reserve-index-dtf
    ```
  </Step>

  <Step title="Set Up Development Environment">
    Follow the [setup guide](/development/setup) to configure your local environment.
  </Step>

  <Step title="Create a Branch">
    Create a branch for your contribution:

    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```

    Use descriptive branch names:

    * `feature/auction-improvements`
    * `fix/rebalance-overflow`
    * `docs/update-deployment-guide`
  </Step>
</Steps>

## Types of Contributions

<CardGroup cols={2}>
  <Card title="Bug Fixes" icon="bug">
    Fix issues, resolve errors, and improve stability
  </Card>

  <Card title="Features" icon="sparkles">
    Add new functionality and capabilities
  </Card>

  <Card title="Documentation" icon="book">
    Improve guides, add examples, fix typos
  </Card>

  <Card title="Tests" icon="vial">
    Expand test coverage and add edge cases
  </Card>

  <Card title="Optimizations" icon="gauge-high">
    Reduce gas costs and improve performance
  </Card>

  <Card title="Security" icon="shield">
    Report vulnerabilities and security improvements
  </Card>
</CardGroup>

## Development Workflow

### 1. Make Your Changes

Follow these best practices:

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Follow Solidity Best Practices">
    * Use Solidity 0.8.28
    * Leverage built-in overflow protection
    * Follow [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html)
    * Use NatSpec documentation format
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### 2. Write Tests

All code contributions must include tests:

```solidity test/YourFeature.t.sol theme={null}
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
    }
}
```

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

### 3. Run Quality Checks

Before committing, run all quality checks:

```bash theme={null}
# 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](https://www.conventionalcommits.org/):

```bash theme={null}
# 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

```bash theme={null}
git push origin feature/your-feature-name
```

Then create a pull request on GitHub with:

<Steps>
  <Step title="Descriptive Title">
    Use a clear, concise title summarizing the change:

    * ✅ "Add progressive auction sizing for improved price discovery"
    * ❌ "Update stuff"
  </Step>

  <Step title="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
  </Step>

  <Step title="Link Issues">
    Reference related issues:

    ```markdown theme={null}
    Closes #123
    Relates to #456
    ```
  </Step>
</Steps>

## Pull Request Template

```markdown theme={null}
## 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

<Steps>
  <Step title="Automated Checks">
    CI/CD pipeline runs:

    * Code formatting verification
    * Linting checks
    * Full test suite
    * Gas usage analysis
  </Step>

  <Step title="Peer Review">
    Core contributors review:

    * Code quality and style
    * Security considerations
    * Gas optimization opportunities
    * Test coverage
  </Step>

  <Step title="Revisions">
    Address review comments and push updates:

    ```bash theme={null}
    git add .
    git commit -m "refactor: address review comments"
    git push origin feature/your-feature-name
    ```
  </Step>

  <Step title="Approval and Merge">
    Once approved, maintainers will merge your contribution.
  </Step>
</Steps>

## Code Style Guidelines

### Solidity Conventions

```solidity theme={null}
// 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:

```solidity theme={null}
// {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

<Warning>
  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
</Warning>

### Security Checklist

<Checklist>
  <Check>All external calls properly protected</Check>
  <Check>Access control implemented and tested</Check>
  <Check>Input validation on all user inputs</Check>
  <Check>No unchecked arithmetic (unless explicitly safe)</Check>
  <Check>Events emitted for important state changes</Check>
  <Check>Consider edge cases and boundary conditions</Check>
  <Check>Gas optimization doesn't compromise security</Check>
  <Check>Code reviewed by at least one other developer</Check>
</Checklist>

## Reporting Security Vulnerabilities

<Warning>
  **DO NOT** open public issues for security vulnerabilities.
</Warning>

If you discover a security vulnerability:

1. **Email**: [security@reserve.org](mailto:security@reserve.org)
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:

<CardGroup cols={2}>
  <Card title="Use Gas Profiling" icon="gauge">
    ```bash theme={null}
    forge test --gas-report
    ```
  </Card>

  <Card title="Compare Before/After" icon="code-compare">
    Document gas savings in PRs
  </Card>
</CardGroup>

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

```solidity theme={null}
/**
 * @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

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

## Community

<CardGroup cols={2}>
  <Card title="GitHub Discussions" icon="github" href="https://github.com/reserve-protocol/reserve-index-dtf/discussions">
    Ask questions and share ideas
  </Card>

  <Card title="Discord" icon="discord">
    Join the Reserve Protocol community
  </Card>
</CardGroup>

## 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](https://github.com/reserve-protocol/reserve-index-dtf/discussions)
2. Review [documentation](/introduction)
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.

<Card title="Start Contributing" icon="rocket" href="https://github.com/reserve-protocol/reserve-index-dtf">
  Ready to contribute? Fork the repository and start building!
</Card>