From 4c7ac61fad2ccf0fed93e184ca013f45a16c93eb Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Sun, 25 Jan 2026 08:18:22 +0000 Subject: [PATCH] docs: add comprehensive contributing guide with bug reporting examples --- CONTRIBUTING.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 246 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..20e5424 --- /dev/null +++ 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. (/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 index 8dacefc..578da40 100644 --- 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).