Contributing to WinScan

Thank you for your interest in contributing to WinScan! 🎉

We welcome contributions from the community. This guide will help you get started.

📋 Table of Contents

Code of Conduct
Getting Started
Development Workflow
Branch Strategy
Coding Standards
Commit Guidelines
Pull Request Process
Testing
Need Help?

📜 Code of Conduct

Be respectful and inclusive
Welcome newcomers and help them learn
Focus on constructive feedback
Respect differing opinions and experiences

🚀 Getting Started

Prerequisites

Node.js 18 or higher
npm or yarn
Git
GitHub account

Fork & Clone

Fork this repository
- Click the "Fork" button at the top right of the repository page
- This creates your own copy under your GitHub account

Clone your fork

git clone https://github.com/YOUR-USERNAME/winscan.git
cd winscan

Add upstream remote

git remote add upstream https://github.com/winsnip-official/winscan.git

Verify remotes

git remote -v
# origin    https://github.com/YOUR-USERNAME/winscan.git (your fork)
# upstream  https://github.com/winsnip-official/winscan.git (original)

Install Dependencies

npm install

Environment Setup

cp .env.example .env

Edit .env if needed (default values work for most cases).

Run Development Server

npm run dev

Visit http://localhost:3000 to see the app running.

💻 Development Workflow

⚠️ IMPORTANT: Always Work on `dev` Branch

Never push directly to main! All development happens on dev branch.

Step-by-Step Workflow

Switch to dev branch
```
git checkout dev
```
⚠️ ALWAYS pull latest changes first
```
git pull origin dev
```
This prevents merge conflicts and ensures you have the latest code.

Create a feature branch

# For new features
git checkout -b feature/your-feature-name

# For bug fixes
git checkout -b fix/bug-description

# For documentation
git checkout -b docs/documentation-update

Make your changes
- Write clean, readable code
- Follow existing code style and patterns
- Add comments for complex logic
- Update documentation if needed

Test your changes

# Run development server
npm run dev

# Build to check for errors
npm run build

# Run linter
npm run lint

Commit your changes
```
git add .
git commit -m "feat: add amazing feature"
```
See Commit Guidelines for proper commit message format.
⚠️ Pull again before pushing
```
git pull origin dev
```
Always check for new changes before pushing to avoid conflicts.

Push to your fork

git push origin feature/your-feature-name

Create Pull Request
- Go to your fork on GitHub
- Click "Pull Request" button
- Important: Select dev as the target branch (not main)
- Fill in the PR template with:
  - Clear description of changes
  - Screenshots/videos if UI changes
  - Link to related issues
  - Testing steps
Wait for review
- Maintainers will review your PR
- Address any feedback or requested changes
- Once approved, your PR will be merged to dev

🌿 Branch Strategy

Branch Types

main - Production branch
- Only stable, tested code
- Direct commits not allowed
- Only accepts merges from dev
dev - Development branch
- Active development happens here
- All PRs should target this branch
- Regularly tested before merging to main
feature/* - New features
- Example: feature/wallet-integration
- Example: feature/multi-chain-support
fix/* - Bug fixes
- Example: fix/balance-calculation
- Example: fix/mobile-layout
docs/* - Documentation
- Example: docs/api-reference
- Example: docs/contributing-guide

Branch Lifecycle

main (production)
  ↑
  └── dev (development)
        ↑
        ├── feature/new-feature
        ├── fix/bug-fix
        └── docs/documentation

📝 Coding Standards

TypeScript

Use TypeScript for all new files
Define proper types/interfaces
Avoid using any type when possible
Use meaningful variable and function names

Example:

// ❌ Bad
function calc(a: any, b: any) {
  return a + b;
}

// ✅ Good
function calculateTotal(price: number, quantity: number): number {
  return price * quantity;
}

React Components

Use functional components with hooks
Keep components focused and small
Extract reusable logic into custom hooks
Use proper prop types

Example:

// ✅ Good component structure
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export default function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button 
      onClick={onClick}
      className={`btn btn-${variant}`}
    >
      {label}
    </button>
  );
}

File Organization

components/
  ├── Button.tsx          # Component
  ├── Modal.tsx
  └── ...

lib/
  ├── utils.ts           # Utility functions
  ├── api.ts             # API calls
  └── ...

types/
  ├── chain.ts           # Type definitions
  └── ...

Styling

Use Tailwind CSS utility classes
Follow existing design patterns
Ensure responsive design (mobile-first)
Use consistent spacing and colors

📋 Commit Guidelines

Commit Message Format

Use Conventional Commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, missing semicolons, etc.)
refactor: Code refactoring (no feature change)
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks, dependencies update

Examples

# Feature
git commit -m "feat: add Keplr wallet integration"
git commit -m "feat(validators): add uptime monitoring"

# Bug fix
git commit -m "fix: resolve balance calculation error"
git commit -m "fix(mobile): correct header alignment on small screens"

# Documentation
git commit -m "docs: update contributing guidelines"
git commit -m "docs(api): add endpoint documentation"

# Refactor
git commit -m "refactor: simplify transaction fetching logic"

# Style
git commit -m "style: format code with prettier"

# Chore
git commit -m "chore: update dependencies"
git commit -m "chore: add eslint configuration"

Commit Best Practices

✅ Write clear, descriptive messages
✅ Use present tense ("add feature" not "added feature")
✅ Keep subject line under 72 characters
✅ Separate subject from body with blank line
✅ Use body to explain what and why (not how)
❌ Don't commit unfinished work
❌ Don't commit commented-out code
❌ Don't commit debugging code

🔍 Pull Request Process

Before Creating PR

Code builds without errors (npm run build)
All tests pass
Linter shows no errors (npm run lint)
Changes are tested in browser
Documentation updated if needed
Commit messages follow guidelines
Branch is up to date with dev

PR Title Format

Follow the same format as commit messages:

feat: add wallet integration
fix: resolve mobile layout issue
docs: update API documentation

PR Description Template

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring

## Changes Made
- List key changes
- Another change
- One more change

## Screenshots (if applicable)
[Add screenshots or videos of UI changes]

## Testing
How to test these changes:
1. Step one
2. Step two
3. Expected result

## Related Issues
Closes #123
Related to #456

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No console errors
- [ ] Tested on multiple browsers (if UI changes)

PR Review Process

Maintainer reviews your PR
Automated tests run (if configured)
Feedback or approval given
Address any requested changes
Push updates to same branch
Once approved, PR will be merged

🧪 Testing

Manual Testing

Before submitting PR, test these scenarios:

For UI Changes:

For Features:

Happy path (everything works)
Error cases (what if something fails?)
Edge cases (empty data, large numbers, etc.)
Loading states
Error messages

Build Testing

# Always run before creating PR
npm run build

# Check for TypeScript errors
npm run lint

🚫 What NOT to Do

❌ Don't Do This

Push directly to main branch
Commit node_modules/ folder
Commit .env files with secrets
Make massive PRs with unrelated changes
Ignore ESLint/TypeScript errors
Forget to test your changes
Copy-paste code without understanding it
Leave console.log() statements
Use any type everywhere
Hard-code values that should be configurable

✅ Do This Instead

Always work on dev branch
Add dependencies via package.json
Use .env.example for environment templates
Create focused PRs (one feature/fix per PR)
Fix all linter errors before committing
Test thoroughly before submitting
Understand and adapt code to project style
Remove debug statements before committing
Use proper TypeScript types
Use configuration files or environment variables

🎯 Good First Issues

New to the project? Look for issues labeled:

good first issue - Perfect for beginners
help wanted - Community contributions welcome
documentation - Help improve docs
bug - Fix existing bugs

💡 Need Help?

Questions?

Before Asking

Check existing issues and PRs
Read the documentation
Search in Telegram group history
Google the error message

When Asking for Help

Provide:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Screenshots/code snippets
Your environment (OS, Node version, etc.)

🏆 Recognition

All contributors will be:

Listed in README.md
Recognized in release notes
Given credit in commit history

Top contributors may receive:

Direct collaborator access
Custom Discord/Telegram roles
Early access to new features

📚 Additional Resources

🙏 Thank You!

Every contribution, no matter how small, is valuable. Thank you for helping make WinScan better!

Happy Contributing! 🚀

If you find this project useful, please give it a ⭐️

Website • Twitter • Telegram

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History