7.1 KiB
Contributing to Smart Follow-up Suggestions
Thank you for considering contributing to this project! ๐
๐ Table of Contents
- Code of Conduct
- How Can I Contribute?
- Development Setup
- Coding Standards
- Submitting Changes
- Testing Guidelines
๐ค Code of Conduct
This project follows the Contributor Covenant. Please be respectful and constructive in all interactions.
TL;DR: Be kind, inclusive, and professional.
๐ก How Can I Contribute?
Reporting Bugs
Found a bug? Help us fix it!
- Check existing issues first to avoid duplicates
- Create a new issue with:
- Clear, descriptive title
- Steps to reproduce
- Expected vs actual behavior
- Environment details (Node version, OS, Bot version)
- Sample input/output if applicable
Example:
Title: JSON parsing fails for markdown-wrapped responses
Steps to reproduce:
1. Run: cat test.json | node cli/followups-cli.js --mode json
2. API returns response wrapped in ```json...```
3. CLI crashes with SyntaxError
Expected: CLI should extract JSON from markdown
Actual: SyntaxError thrown
Environment: Node v18.16.0, Ubuntu 22.04, @anthropic-ai/sdk v0.32.0
Suggesting Enhancements
Have an idea? We'd love to hear it!
- Open an issue with tag
enhancement - Describe the feature and use case
- Explain why it's valuable
- (Optional) Suggest implementation approach
Adding Channel Support
Want to add a new messaging platform?
- Update
supportsInlineButtons()inhandler.js - Add channel-specific formatting if needed
- Create examples in
examples.md - Test with real account on that platform
- Update
package.jsonbot.channels - Submit PR with screenshots/recordings
Improving Documentation
Documentation improvements are always welcome!
- Fix typos or unclear explanations
- Add missing examples
- Improve code comments
- Translate to other languages (future)
๐ ๏ธ Development Setup
Prerequisites
- Node.js 18+
- npm or yarn
- Anthropic API key
- Git
Setup Steps
-
Fork and clone:
git clone https://github.com/your-username/bot-smart-followups.git cd bot-smart-followups -
Install dependencies:
npm install -
Set API key:
export ANTHROPIC_API_KEY="sk-ant-your-key-here" -
Test your setup:
./test.sh -
Create a branch:
git checkout -b feature/your-feature-name
๐ Coding Standards
Style Guide
- Language: JavaScript (ES2020+)
- Formatting: Standard JS style (2-space indent)
- Line length: Max 100 characters
- Naming:
camelCasefor functions and variablesUPPER_CASEfor constants- Descriptive names (no single-letter except loop counters)
Code Principles
-
Readability over cleverness
// โ Good const isInteractiveChannel = buttonChannels.includes(channel); // โ Bad (too clever) const isInteractiveChannel = ~buttonChannels.indexOf(channel); -
Error handling
// โ Always handle errors try { const result = await apiCall(); return result; } catch (error) { console.error('API call failed:', error.message); throw new Error(`Failed to generate: ${error.message}`); } -
Comments for "why", not "what"
// โ Good // Truncate to 40 chars to stay under Telegram's 64-byte callback_data limit const callbackData = `ask:${question.substring(0, 40)}`; // โ Bad (obvious) // Substring the question to 40 characters const callbackData = `ask:${question.substring(0, 40)}`; -
Small, focused functions
- One function = one responsibility
- Max ~50 lines per function
- Extract complex logic into helpers
File Organization
smart-followups/
โโโ cli/ # CLI tool (standalone)
โ โโโ followups-cli.js
โโโ handler.js # Bot integration
โโโ test/ # Tests (future)
โ โโโ cli.test.js
โ โโโ handler.test.js
โโโ docs/ # Documentation
โ โโโ README.md
โ โโโ SKILL.md
โ โโโ examples.md
โ โโโ INTERNAL.md
โโโ package.json
๐ Submitting Changes
Pull Request Process
- Update documentation if needed
- Add tests for new features (when test framework added)
- Ensure tests pass:
npm test - Update CHANGELOG.md under
[Unreleased] - Create PR with clear description
PR Template
## Description
Brief description of changes
## Motivation
Why is this change needed?
## Changes
- Added X
- Modified Y
- Fixed Z
## Testing
How was this tested?
## Screenshots (if applicable)
[Attach images/videos]
## Checklist
- [ ] Documentation updated
- [ ] Tests added/passing
- [ ] CHANGELOG.md updated
- [ ] No breaking changes (or documented)
Review Process
- Maintainers will review within 3-5 days
- Address feedback promptly
- Be open to suggestions
- Once approved, maintainer will merge
๐งช Testing Guidelines
Manual Testing Checklist
Before submitting PR, verify:
- CLI runs without errors:
./test.sh - All output modes work (json, telegram, text, compact)
- Error handling works (invalid input, missing API key)
- Different conversation lengths (1, 3, 10 exchanges)
- Various topics (technical, casual, creative)
Testing Channels (if applicable)
- Telegram inline buttons
- Signal numbered list
- Discord (if you have access)
Future: Unit Tests
When test framework is added:
// Example test structure
describe('generateFollowups', () => {
it('should return 6 suggestions across 3 categories', async () => {
const exchanges = [{ user: 'test', assistant: 'response' }];
const result = await generateFollowups(exchanges);
expect(result.quick).toHaveLength(2);
expect(result.deep).toHaveLength(2);
expect(result.related).toHaveLength(2);
});
});
๐ฏ Priority Areas
Current focus areas for contributions:
-
High Priority
- Unit tests (Jest/Mocha)
- Integration tests
- Rate limiting implementation
- Error message improvements
-
Medium Priority
- Multi-language support
- Caching layer
- User feedback tracking
- Performance optimizations
-
Nice to Have
- Additional channels (WhatsApp, Teams, etc.)
- Custom category definitions
- Prompt engineering experiments
- Analytics/metrics
๐ Questions?
- General questions: Open a GitHub Discussion
- Bug reports: GitHub Issues
- Security issues: Email [email protected] (do not open public issue)
- Direct contact: @robbyczgw-cla
๐ Recognition
Contributors will be:
- Listed in README.md
- Mentioned in release notes
- Credited in CHANGELOG.md
Thank you for making Smart Follow-ups better! ๐
Last Updated: January 20, 2026