Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (223 loc) · 8.56 KB

CONTRIBUTING.md

File metadata and controls

317 lines (223 loc) · 8.56 KB

Contributing to Smart Contract Practices

Guidelines for collaboration and development workflow

Project Structure

Branch Type Purpose Content Restrictions
Master Documentation Hub Markdown files, activity logs No contract code
Weekly Branches Development Work Contracts, tests, scripts Self-contained topics

Branching Strategy

Master Branch - Documentation Hub

The master branch serves as the central documentation and activity tracking hub:

Allowed Content:

  • ACTIVITY.md - Chronological activity log
  • README.md - Project overview and setup
  • CONTRIBUTING.md - Collaboration guidelines
  • public/md/ - Documentation files
  • .github/ - GitHub workflows and templates

Restrictions:

  • ❌ No contract code (.sol files)
  • ❌ No test files (.js, .ts test files)
  • ❌ No deployment scripts
  • ✅ Markdown documentation only

Weekly Branches - Development Work

Each week gets its own dedicated branch for focused development:

Branch Naming: weekly-N (e.g., weekly-1, weekly-2)

Content Structure:

weekly-N/
├── README.md              # Week overview and goals
├── contracts/             # Smart contract modules
│   ├── WeekNContract.sol
│   └── interfaces/
├── test/                  # Test files
│   ├── WeekNContract.test.js
│   └── helpers/
├── scripts/               # Deployment and interaction scripts
│   ├── deploy.js
│   └── interact.js
└── docs/                  # Week-specific documentation
    ├── design-decisions.md
    └── lessons-learned.md

Development Workflow

Starting a New Week

Step Command Description
1 git checkout master Switch to master branch
2 git pull origin master Update with latest changes
3 git checkout -b weekly-N Create new weekly branch
4 git push -u origin weekly-N Push and set upstream

Daily Development Process

Phase Description Duration Tools
Planning Review goals and plan daily tasks 15 min GitHub Issues
Development Implement contract features 2-4 hours Hardhat, VS Code
Testing Write and run tests 1-2 hours Chai, Mocha, Foundry
Documentation Update README and comments 30 min Markdown
Commit Commit with descriptive message 5 min Git

Weekly Completion Process

Step Description Duration
Final Review Code review and testing 1 hour
Documentation Complete week's README 30 min
Activity Update Update master ACTIVITY.md 15 min
Branch Merge Merge to master (docs only) 10 min

Code Standards

Smart Contract Standards

Standard Requirement Tool
Solidity Version ^0.8.0 Pragma directive
NatSpec Comments All functions documented Manual review
OpenZeppelin Use standard libraries Import statements
Security Pass Slither analysis Slither tool
Gas Optimization Optimize for efficiency Gas profiling

Testing Standards

Test Type Coverage Target Framework
Unit Tests 90%+ Chai, Mocha
Integration Tests 85%+ Waffle
Fuzz Tests 80%+ Foundry
Security Tests 100% Slither, MythX

Documentation Standards

Document Purpose Format
README.md Week overview and goals Markdown
Design Decisions Technical choices made Markdown
Lessons Learned Key insights and pitfalls Markdown
Code Comments Inline documentation NatSpec

Commit Message Guidelines

Format

type(scope): brief description

Detailed explanation of changes
- Bullet points for specific changes
- Reference issues if applicable

Closes #issue_number

Types

  • feat: New feature or contract
  • fix: Bug fix or security patch
  • docs: Documentation updates
  • test: Test additions or improvements
  • refactor: Code refactoring
  • style: Code formatting changes
  • chore: Maintenance tasks

Examples

feat(erc20): implement basic ERC20 token with mint/burn

- Add ERC20 contract with OpenZeppelin imports
- Implement mint and burn functions
- Add comprehensive NatSpec documentation
- Include access control for minting

Closes #1

Pull Request Process

Creating a PR

Step Description Checklist
1 Create PR from weekly branch [ ] Descriptive title
2 Fill out PR template [ ] Link to issues
3 Request review [ ] Assign reviewers
4 Address feedback [ ] Update documentation
5 Merge to master [ ] Update ACTIVITY.md

PR Template

## Week N: [Contract Name/Pattern]

### Overview
Brief description of the week's focus and goals.

### Changes Made
- [ ] Contract implementation
- [ ] Test coverage
- [ ] Documentation updates
- [ ] Security analysis

### Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Security analysis clean
- [ ] Gas optimization complete

### Documentation
- [ ] README updated
- [ ] Code comments added
- [ ] Design decisions documented
- [ ] Lessons learned recorded

### Links
- Closes #[issue_number]
- Related to #[issue_number]

Review Guidelines

Code Review Checklist

Category Checklist Items
Functionality [ ] Contract works as intended
[ ] All functions tested
[ ] Edge cases handled
Security [ ] No reentrancy vulnerabilities
[ ] Access controls implemented
[ ] Input validation present
Gas Efficiency [ ] Optimized for gas usage
[ ] No unnecessary operations
[ ] Efficient data structures
Documentation [ ] NatSpec comments present
[ ] README updated
[ ] Code is readable

Review Process

  1. Automated Checks: Ensure all CI/CD checks pass
  2. Security Analysis: Run Slither and other security tools
  3. Test Coverage: Verify test coverage meets standards
  4. Code Quality: Review for readability and best practices
  5. Documentation: Ensure all changes are documented

Community Guidelines

Communication Standards

Platform Purpose Guidelines
GitHub Issues Bug reports and feature requests Use templates, be specific
Discussions General questions and ideas Be respectful, constructive
Pull Requests Code contributions Follow guidelines, be responsive
Discord Real-time collaboration Keep on-topic, be helpful

Code of Conduct

  • Be Respectful: Treat all contributors with respect
  • Be Constructive: Provide helpful feedback and suggestions
  • Be Patient: Allow time for responses and reviews
  • Be Professional: Maintain professional communication
  • Be Inclusive: Welcome contributors from all backgrounds

Getting Help

Resources

Resource Purpose Link
Documentation Project guidelines and standards README.md
Activity Log Project progress and history ACTIVITY.md
Workflow Guide Daily and weekly processes Activity Workflow
Discord Community support and discussion Join Discord

Support Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Discord: Real-time help and collaboration
  • Email: Direct contact for sensitive issues

Last Updated: 2024-01-15 | Version: 1.0.0

Building a collaborative smart contract development community