Microsoft-Rewards-Bot/CONTRIBUTING.md

🤝 Contributing to Microsoft Rewards Script

Thank you for considering contributing to this project!

---

📋 Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Standards
• Documentation

---

🤝 Code of Conduct

This project follows a simple principle: Be respectful and constructive.

• Treat all contributors with respect
• Welcome newcomers and help them learn
• Focus on constructive feedback
• Keep discussions professional and on-topic

---

💡 How Can I Contribute?

🐛 Reporting Bugs

Before creating a bug report:

• Check existing issues to avoid duplicates
• Gather diagnostic information (see Diagnostics Guide)

Good bug reports include:

• Clear title and description
• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Node.js version, script version)
• Logs and screenshots (remember to redact sensitive info!)

✨ Suggesting Features

Feature suggestions are welcome! Please:

• Check if the feature already exists or is planned
• Explain the use case and benefits
• Consider backward compatibility
• Be open to discussion and alternatives

📝 Improving Documentation

Documentation improvements are highly valued:

• Fix typos or unclear instructions
• Add examples or clarifications
• Translate content (if applicable)
• Update outdated information

💻 Code Contributions

Contributions to the codebase are welcome! See Development Setup below.

---

🛠️ Development Setup

Prerequisites

• Node.js 20+ (version 22 recommended)
• Git
• A code editor (VS Code recommended)

Getting Started

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/Microsoft-Rewards-Bot.git
   cd Microsoft-Rewards-Bot
   

3. Install dependencies:

   npm install
   

4. Set up configuration:

   cp src/accounts.example.jsonc src/accounts.jsonc
   # Edit accounts.jsonc with test credentials
   

5. Build the project:

   npm run build
   

6. Run in development mode:

   npm run dev
   

Project Structure

src/
├── browser/          # Browser automation (Playwright)
├── functions/        # Core features (activities, login, workers)
│   └── activities/   # Individual activity handlers
├── interface/        # TypeScript interfaces
└── util/             # Utility classes (logging, analytics, etc.)

---

🔄 Pull Request Process

Before Submitting

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes:

   • Write clean, documented code
   • Follow existing code style
   • Add comments for complex logic

3. Test your changes:

   npm run build
   npm run start
   

4. Commit your changes:

   git add .
   git commit -m "feat: add amazing new feature"
   

   Use conventional commits:

   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation
   • refactor: for code refactoring
   • test: for tests
   • chore: for maintenance tasks

Submitting the PR

1. Push to your fork:

   git push origin feature/your-feature-name
   

2. Create a Pull Request on GitHub:

   • Provide a clear title and description
   • Reference any related issues
   • Explain what changed and why
   • Include screenshots/examples if applicable

3. Respond to feedback:

   • Be open to suggestions
   • Make requested changes promptly
   • Keep the discussion focused and professional

PR Review Process

• Maintainers will review your PR as soon as possible
• Changes may be requested before merging
• Once approved, a maintainer will merge your contribution

---

📐 Coding Standards

TypeScript Style

• Indentation: 2 spaces (no tabs)
• Quotes: Single quotes for strings
• Semicolons: Required
• Naming:
  • camelCase for variables and functions
  • PascalCase for classes and interfaces
  • UPPER_CASE for constants

Best Practices

• Write self-documenting code with clear variable names
• Add comments for complex logic
• Keep functions small and focused (single responsibility)
• Handle errors gracefully
• Avoid code duplication
• Use TypeScript types properly (avoid any when possible)

Example

// ✅ Good
async function calculateRewardPoints(account: Account): Promise<number> {
  try {
    const points = await fetchPointsFromAPI(account);
    return points;
  } catch (error) {
    this.log.error('POINTS-FETCH', `Failed to fetch points: ${error.message}`);
    return 0;
  }
}

// ❌ Bad
async function calc(a: any): Promise<any> {
  const p = await fetch(a);
  return p;
}

---

📚 Documentation

Documentation Standards

• Keep documentation clear and concise
• Use examples wherever possible
• Update documentation when changing functionality
• Follow the existing documentation structure

Documentation Files

• README.md — Main project overview and quick start
• docs/*.md — Detailed guides for specific topics
• Code comments — Inline documentation for complex logic

Writing Style

• Use clear, simple language
• Break complex topics into steps
• Include code examples
• Add visual aids (screenshots, diagrams) when helpful
• Use emojis sparingly for visual navigation

---

🧪 Testing

Currently, this project doesn't have a formal test suite. If you'd like to contribute tests:

• Use a testing framework (Jest, Mocha, etc.)
• Write unit tests for utility functions
• Consider integration tests for critical flows
• Document how to run tests

---

🐛 Debugging

When debugging issues:

1. Enable diagnostics in config.jsonc:

   {
     "diagnostics": {
       "enabled": true,
       "saveScreenshot": true,
       "saveHtml": true
     }
   }
   

2. Check logs in the console and reports/ folder

3. Use VS Code debugger with launch configuration

---

💬 Getting Help

• Discord: Join our community
• GitHub Issues: Ask questions or report problems
• Documentation: Check the docs folder

---

🎯 Contribution Ideas

Not sure where to start? Here are some ideas:

Beginner-Friendly

• Fix typos in documentation
• Improve error messages
• Add code comments
• Create examples or tutorials

Intermediate

• Refactor complex functions
• Improve error handling
• Add new configuration options
• Optimize performance

Advanced

• Implement new activity types
• Enhance anti-detection mechanisms
• Add comprehensive testing
• Improve Docker deployment

---

🙏 Recognition

Contributors will be:

• Listed in the project's contributors page
• Mentioned in release notes (for significant contributions)
• Appreciated by the community! 🌟

---

📄 License

---

📄 License

By contributing, you agree that your contributions will be licensed under the same Non-Commercial Personal Use License as the project.

---

---

Thank you for contributing! 🎉

Back to README • Documentation • Discord