From 73344ba01e14c3cdc34ff2a2291ccb65ad6bca14 Mon Sep 17 00:00:00 2001 From: HusseinAdeiza Date: Mon, 18 May 2026 21:24:56 +0100 Subject: [PATCH] docs: add comprehensive documentation and tooling - Add TROUBLESHOOTING.md (addresses #1, #5, #6) - Add FAQ.md with 40+ common questions - Add quick-start.sh automated setup script - Add CONTRIBUTING.md guidelines Closes #1 Closes #5 Closes #6 --- CONTRIBUTING.md | 400 ++++++++++++++++++++++++++++++++++++ docs/FAQ.md | 404 +++++++++++++++++++++++++++++++++++++ docs/PR_SUMMARY.md | 187 +++++++++++++++++ docs/TROUBLESHOOTING.md | 436 ++++++++++++++++++++++++++++++++++++++++ scripts/quick-start.sh | 318 +++++++++++++++++++++++++++++ 5 files changed, 1745 insertions(+) create mode 100755 CONTRIBUTING.md create mode 100755 docs/FAQ.md create mode 100755 docs/PR_SUMMARY.md create mode 100755 docs/TROUBLESHOOTING.md create mode 100755 scripts/quick-start.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100755 index 0000000..a6d7670 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,400 @@ +# Contributing to GIWA + +Thank you for your interest in contributing to GIWA! This document provides guidelines and instructions for contributing to the GIWA ecosystem. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Contribution Guidelines](#contribution-guidelines) +- [Community](#community) + +--- + +## Code of Conduct + +By participating in this project, you agree to maintain a respectful, inclusive, and harassment-free environment for everyone. + +### Our Standards + +- ✅ Be respectful and inclusive +- ✅ Welcome newcomers and help them learn +- ✅ Focus on what's best for the community +- ✅ Show empathy towards others +- ❌ No harassment, discrimination, or offensive behavior + +--- + +## How Can I Contribute? + +There are many ways to contribute to GIWA: + +### 1. 📝 Documentation + +- Improve existing documentation +- Write tutorials and guides +- Create examples and demos +- Fix typos and clarify instructions +- Translate documentation + +### 2. 🐛 Bug Reports + +- Report issues you encounter +- Provide detailed reproduction steps +- Include system information and logs + +### 3. 💡 Feature Requests + +- Suggest new features +- Propose improvements +- Share use cases and requirements + +### 4. 🔧 Code Contributions + +- Fix bugs +- Implement features +- Improve performance +- Add tests +- Refactor code + +### 5. 🧪 Testing + +- Test on different platforms +- Validate setup instructions +- Perform security audits +- Benchmark performance + +### 6. 🤝 Community Support + +- Answer questions in issues +- Help newcomers get started +- Share your experiences +- Create content (blog posts, videos) + +--- + +## Getting Started + +### Prerequisites + +- **Git** installed +- **Docker & Docker Compose** (for node repo) +- **Node.js v18+** (for dojang repo) +- **Foundry** (for Solidity development) + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork: + ```bash + git clone https://github.com/YOUR-USERNAME/REPO-NAME.git + cd REPO-NAME + ``` + +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/giwa-io/REPO-NAME.git + ``` + +4. Create a branch: + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/your-bug-fix + ``` + +--- + +## Development Workflow + +### For Node Repository + +```bash +# Install dependencies +docker compose build + +# Run node +CLIENT=reth NETWORK_ENV=.env.sepolia docker compose up -d + +# View logs +docker compose logs -f + +# Stop node +docker compose down +``` + +### For Dojang Repository + +```bash +# Install dependencies +pnpm install + +# Build +pnpm build + +# Run tests +pnpm test + +# Check coverage +pnpm test:coverage + +# Lint +pnpm lint +pnpm lint:fix + +# Deploy (testnet) +source .env +forge script script/deploy/Deploy.s.sol --rpc-url $RPC_URL --broadcast +``` + +--- + +## Contribution Guidelines + +### Documentation Contributions + +**What We Welcome:** +- Tutorials and how-to guides +- FAQ entries +- Troubleshooting tips +- Platform-specific instructions +- Integration examples +- Video tutorials and screencasts + +**Style Guide:** +- Use clear, concise language +- Include code examples where relevant +- Add screenshots/diagrams when helpful +- Test all instructions before submitting +- Use consistent formatting (Markdown) + +**File Structure:** +``` +docs/ +├── guides/ # How-to guides +├── tutorials/ # Step-by-step tutorials +├── reference/ # API/technical reference +└── troubleshooting/ # Common issues & solutions + +examples/ +├── basic/ # Simple examples +├── advanced/ # Complex integrations +└── production/ # Production-ready configs +``` + +### Code Contributions + +**Before You Start:** +1. Check existing issues for similar work +2. Comment on the issue to claim it +3. Discuss major changes in an issue first + +**Code Style:** +- Follow existing code style +- Use meaningful variable names +- Add comments for complex logic +- Write self-documenting code + +**For Solidity:** +- Follow [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html) +- Add NatSpec comments +- Write comprehensive tests +- Check gas optimization + +**For TypeScript/JavaScript:** +- Use ES6+ features +- Follow Prettier formatting +- Add JSDoc comments +- Handle errors properly + +**For Bash Scripts:** +- Use `set -e` for error handling +- Add comments for complex logic +- Test on multiple platforms +- Make scripts idempotent + +### Testing + +**Requirements:** +- All code changes must include tests +- Tests must pass before merging +- Maintain or improve code coverage +- Test on multiple environments when possible + +**Test Types:** +- Unit tests for individual functions +- Integration tests for contracts/services +- End-to-end tests for full flows +- Manual testing on testnet + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + + +