shelby · maniapulai · Jan 25, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,244 @@
+# Contributing to Shelby Feedback
+
+Thank you for helping improve Shelby! This guide will help you find and report bugs effectively.
+
+## Table of Contents
+- [Before You Start](#before-you-start)
+- [Finding Bugs](#finding-bugs)
+- [Reporting Bugs](#reporting-bugs)
+- [Example Bug Reports](#example-bug-reports)
+- [Tips for Great Reports](#tips-for-great-reports)
+
+## Before You Start
+
+1. **Read the Code of Conduct** - [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+2. **Check existing issues** - Use the search feature to avoid duplicates
+3. **Verify it's a bug, not a feature request or question**
+   - Bugs: Something that doesn't work as documented
+   - Features: New functionality or improvements
+   - Questions: Use [Shelby Discord](https://discord.gg/shelbyserves) instead
+
+## Finding Bugs
+
+### Areas to Test
+- **SDK (JS/TS)** - JavaScript/TypeScript SDK functionality
+- **CLI** - Command-line tool operations
+- **Indexer** - Data indexing features
+- **RPC** - Remote procedure calls
+- **Explorer** - Block explorer interface
+- **Services** - API responses and integrations
+
+### Common Bug Categories
+- **Type errors** - Incorrect return types or parameters
+- **Crashes** - Uncaught exceptions or fatal errors
+- **Performance** - Slow operations or memory leaks
+- **Documentation mismatch** - Code doesn't match documented behavior
+- **Edge cases** - Unusual inputs causing failures
+- **Platform-specific issues** - Works on one OS/browser but not others
+- **Version incompatibilities** - Issues with specific versions
+
+### Testing Checklist
+- [ ] Test with the latest version
+- [ ] Test on multiple platforms (Node, Browser, iOS, Android)
+- [ ] Test with edge cases (null, empty strings, large datasets)
+- [ ] Check error messages are helpful
+- [ ] Verify against documentation
+- [ ] Look for performance issues
+
+## Reporting Bugs
+
+### Step-by-Step
+
+1. **Go to [Issues](https://github.com/shelby/feedback/issues)**
+2. **Click "New issue"**
+3. **Select "Bug report"**
+4. **Fill in all fields:**
+
+### Required Information
+
+#### Affected Product
+Select the product where you found the bug:
+- SDK (JS/TS)
+- Indexer
+- CLI
+- RPC
+- Explorer
+- Other / Unsure
+
+#### Version / Commit / Build
+Include the exact version you tested:
+- For SDK: `npm list @shelby/sdk`
+- For CLI: `shelby --version`
+- For services: API version or date tested
+
+#### Platform / Environment
+Select all that apply:
+- OS: MacOS, Windows, Linux
+- Runtime: Node.js (with version), Browser (with type)
+- Mobile: iOS, Android
+
+#### Steps to Reproduce
+Provide numbered steps that someone else can follow:
+```
+1. Create a new project with `shelby init`
+2. Run `npm install`
+3. Execute `shelby deploy --env production`
+4. Observe the error message
+```
+
+#### Expected Behavior
+What should happen according to documentation:
+- "The contract should deploy successfully"
+- "Response should contain a transaction hash"
+- "CLI should exit with code 0"
+
+#### Actual Behavior & Errors
+What actually happened:
+- Include full error messages
+- Paste stack traces
+- Quote error output exactly
+
+#### Logs / Screenshots
+Attach files or screenshots showing:
+- Terminal output
+- Network inspector logs
+- Error stack traces
+- Screenshots of visual issues
+
+## Example Bug Reports
+
+### Example 1: SDK Type Error
+
+**Title:** `[bug]: TypeScript SDK returns incorrect type for balanceOf()`
+
+**Product:** SDK (JS/TS)
+
+**Version:** 2.1.4
+
+**Platform:** Node.js 18.12.1
+
+**Steps to Reproduce:**
+```typescript
+import { Shelby } from '@shelby/sdk';
+
+const client = new Shelby({ rpc: 'https://rpc.shelby.xyz' });
+const balance = await client.getBalance('0x1234...');
+console.log(typeof balance); // logs "string"
+console.log(balance.toNumber()); // TypeError: balance.toNumber is not a function
+```
+
+**Expected Behavior:**
+Balance should be a `BigNumber` object with a `toNumber()` method, as documented in the SDK reference.
+
+**Actual Behavior & Errors:**
+```
+TypeError: balance.toNumber is not a function
+    at Object.<anonymous> (/path/to/script.js:5:13)
+```
+
+**Logs:**
+Balance value: `"1234567890000000000"`
+
+---
+
+### Example 2: CLI Crash
+
+**Title:** `[bug]: CLI crashes when deploying with special characters in contract name`
+
+**Product:** CLI
+
+**Version:** 1.3.2, commit abc123def
+
+**Platform:** Windows 10
+
+**Steps to Reproduce:**
+1. Create a contract file named `MyContract-v2.0.sol`
+2. Run `shelby deploy --contract "MyContract-v2.0"`
+3. Observe application crash
+
+**Expected Behavior:**
+CLI should successfully deploy the contract and return a transaction hash.
+
+**Actual Behavior & Errors:**
+```
+Error: Invalid contract name
+    at validateName (C:\Program Files\shelby\lib\validator.js:45:12)
+    at deploy (C:\Program Files\shelby\lib\deploy.js:78:33)
+```
+
+**Logs:**
+Attached full CLI output and contract file.
+
+---
+
+### Example 3: Performance Issue
+
+**Title:** `[bug]: Explorer slow when rendering 10,000+ transactions`
+
+**Product:** Explorer
+
+**Version:** Tested on 2026-01-25
+
+**Platform:** Chrome 132.0.6834
+
+**Steps to Reproduce:**
+1. Navigate to a wallet with 10,000+ transactions
+2. Load the transaction history tab
+3. Observe page load time and scroll performance
+
+**Expected Behavior:**
+Page should load within 3 seconds and scroll smoothly.
+
+**Actual Behavior & Errors:**
+- Page takes 15+ seconds to load
+- Scrolling causes UI to freeze for 2-3 seconds at a time
+- Chrome DevTools shows 1.2GB memory usage
+
+**Logs:**
+- Chrome DevTools Performance tab recording attached
+- Memory profiler screenshot showing memory usage spike
+
+---
+
+## Tips for Great Reports
+
+### ✅ Do:
+- **Be specific** - Use exact version numbers, not "latest"
+- **Be reproducible** - Others should be able to follow your steps exactly
+- **Include context** - Show both the code and the error output
+- **Attach files** - Provide logs, screenshots, or minimal code examples
+- **Test thoroughly** - Try on different versions/platforms before reporting
+- **Use code blocks** - Format code and error messages properly
+- **Reference docs** - Link to documentation that contradicts the behavior
+
+### ❌ Don't:
+- **Share secrets** - Never include API keys, private keys, or tokens
+- **Report duplicates** - Search first to avoid duplicate reports
+- **Be vague** - "It doesn't work" isn't helpful
+- **Mix concerns** - Keep one issue per report
+- **Report support issues** - Use support channels for account/billing questions
+- **Include sensitive data** - Redact personal information, email addresses
+- **Complain without detail** - Explain what went wrong, not just that you're frustrated
+
+### Extra Steps for Complex Issues
+- Create a **minimal reproduction** - Remove unrelated code
+- Test with a **clean environment** - Fresh install or isolated project
+- Compare with **previous versions** - Is this a regression?
+- Check **similar issues** - Do others report the same?
+- Provide **a code sample** - Paste the problematic code block
+
+## Response Timeline
+
+- **5 business days** - Initial triage and acknowledgment
+- **Issue labeling** - We'll add labels to help track status
+- **Follow-ups** - We may ask for more details with `state:need-info` label
+- **Priority** - Bugs are labeled as `priority:p0/p1/p2` based on impact
+- **Transfer** - Critical issues may move to a private repo for investigation
+
+## Questions?
+
+- **Community help** - [Shelby Discord](https://discord.gg/shelbyserves)
+- **Security issues** - [SECURITY.md](./SECURITY.md)
+- **Conduct violations** - See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
+Thank you for contributing! Your bug reports help make Shelby better for everyone.
diff --git a/README.md b/README.md
@@ -26,4 +26,6 @@ A single place to file bugs and request features for Shelby.
 - Some issues may be **transferred** to a private repo for investigation; you’ll remain subscribed to updates.
 
 ## Contributing Feedback
+Want to find and report bugs? Check out our [Contributing Guide](./CONTRIBUTING.md) for detailed instructions, testing tips, and example bug reports.
+
 By participating, you agree to our [Code of Conduct](./CODE_OF_CONDUCT.md).