Contributing Guide

​

Code of Conduct

• Be respectful and constructive in all interactions
• Welcome newcomers and help them get oriented
• Focus on the work, not the person
• Accept feedback gracefully and give it kindly
• Report unacceptable behavior to the project maintainers

​

How to Contribute

​

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/fhevm-bootcamp.git
cd fhevm-bootcamp
git remote add upstream https://github.com/Himess/fhevm-bootcamp.git

​

2. Create a Branch

git checkout -b feature/your-description
# or
git checkout -b fix/your-description

• feature/module-15-privacy-nft — new module or major feature
• fix/module-07-typo-in-exercise — bug fix or correction
• docs/update-gas-guide — documentation improvement
• chore/update-dependencies — maintenance task

​

3. Make Your Changes

​

4. Test Your Changes

# Verify all Solidity code compiles
npx hardhat compile

# Run existing tests
npx hardhat test

# Check Markdown formatting
# If you added exercises, include solution files and verify they work

​

5. Submit a Pull Request

​

Types of Contributions

​

Content Improvements

​

New Content

​

Infrastructure

​

Development Setup

​

Prerequisites

• Node.js 20+
• npm 10+ or pnpm 9+
• Git 2.40+

​

Installation

npm install
npx hardhat compile

​

Project Structure

modules/XX-module-name/
├── README.md              # Module overview, learning objectives
├── lesson.md              # Detailed lesson content
├── slides/
│   └── slides.md          # Marp presentation slides
├── exercise.md            # Hands-on exercise with starter code
└── quiz.md                # Assessment questions with answer key

​

Submitting Changes

​

Pull Request Template

## Description
[What does this PR do?]

## Type of Change
- [ ] Content correction / typo fix
- [ ] New content (exercise, example, module)
- [ ] Content update (API changes, version updates)
- [ ] Infrastructure / tooling
- [ ] Documentation improvement

## Module(s) Affected
[List which modules are changed, e.g., Module 07]

## Checklist
- [ ] All Solidity code compiles without errors
- [ ] Code follows the project style guidelines
- [ ] New exercises include starter code AND solutions
- [ ] Quiz questions include answer keys
- [ ] Markdown renders correctly
- [ ] Links are not broken
- [ ] I have tested the changes locally

​

Commit Messages

feat(module-07): add overflow handling exercise

Add a new exercise covering encrypted overflow detection
in ERC-20 transfer functions. Includes starter code,
solution, and three test cases.

• feat: — new feature or content
• fix: — correction or bug fix
• docs: — documentation only
• chore: — maintenance, dependencies
• refactor: — restructuring without changing behavior
• test: — adding or fixing tests

​

Style Guidelines

​

Solidity Code

/// @notice Transfers encrypted tokens from sender to recipient.
/// @param to The recipient address.
/// @param encryptedAmount The encrypted transfer amount.
function transfer(address to, externalEuint32 encryptedAmount, bytes calldata inputProof) external {
    euint32 amount = FHE.fromExternal(encryptedAmount, inputProof);

    // Check balance >= amount (comparison on ciphertexts)
    ebool hasEnough = FHE.ge(balances[msg.sender], amount);

    // Conditionally update balances (no branching on encrypted values)
    balances[msg.sender] = FHE.select(hasEnough, FHE.sub(balances[msg.sender], amount), balances[msg.sender]);
    balances[to] = FHE.select(hasEnough, FHE.add(balances[to], amount), balances[to]);

    // Set ACL permissions
    FHE.allowThis(balances[msg.sender]);
    FHE.allow(balances[msg.sender], msg.sender);
    FHE.allowThis(balances[to]);
    FHE.allow(balances[to], to);
}

​

Markdown

1. Use ATX-style headers (#, ##, ###)
2. Use fenced code blocks with language identifiers
3. Use tables for structured data
4. Use relative links for internal references
5. One sentence per line in source (for cleaner diffs)
6. Avoid emojis in instructional content

​

Exercises

1. Every exercise must have a clear problem statement
2. Provide starter code that compiles but is incomplete
3. Include a working solution
4. Include at least one test case for the solution
5. Difficulty should be clearly stated (Beginner / Intermediate / Advanced)
6. Estimated completion time should be realistic

​

Review Process

1. Automated Checks: PRs must pass CI (compilation, linting, link checks)
2. Maintainer Review: At least one maintainer will review within 5 business days
3. Feedback: Reviewers may request changes. Address all comments before merging
4. Merge: Maintainers merge approved PRs using squash-and-merge

​

What Reviewers Look For

• Accuracy: Is the technical content correct?
• Clarity: Will students understand this?
• Completeness: Are all required files present?
• Consistency: Does it follow the style guide and use the correct API?
• Tested: Does the code compile and work?

​

Reporting Issues

• Title: Clear, concise description
• Description: What is wrong or what you suggest
• Location: Which file/module is affected
• Expected vs Actual: What should be there vs what is there
• Screenshots: If applicable

• bug — something is wrong
• enhancement — improvement to existing content
• new-content — request for new material
• question — need clarification
• good-first-issue — suitable for new contributors

​

Questions?