Squirrel Servers Manager
🤝

Contributing to SSM

⏱️ 15 min read

Thank you for your interest in contributing to Squirrel Servers Manager (SSM)! This guide will help you understand how to contribute effectively to the project, whether you're fixing bugs, adding features, improving documentation, or helping with design.

In a Nutshell (🌰)

  • Contributions welcome in code, documentation, testing, and design
  • Follow the 9-step contribution workflow for smooth collaboration
  • Use project-specific coding standards and documentation templates
  • Join our Discord community for real-time help and discussions

"Adopt me!" tasks ​

A list of pre-identified tasks to improve SMM are available here: Adopt me!

Contribution Workflow Overview ​

Contribution Workflow
SSM Contribution Workflow Diagram
Figure 1: The 9-step contribution workflow for Squirrel Servers Manager

Ways to Contribute ​

There are many ways to contribute to SSM, regardless of your technical background:

💻 Code Contributions

Fix bugs, add features, optimize performance, and improve the codebase.

📝 Documentation

Improve guides, create tutorials, fix errors, and make SSM easier to use.

🧪 Testing

Help test SSM on different platforms, report bugs, and write automated tests.

🎨 Design

Enhance the UI/UX, create visual assets, and improve the overall design.

Setting Up Your Development Environment ​

1

Fork the Repository

Visit the https://github.com/SquirrelCorporation/SquirrelServersManager SSM GitHub repository and click the 'Fork' button in the top right corner.

↓
2

Clone Your Fork

Clone your forked repository to your local machine.

↓
3

Install Dependencies

Install the required dependencies for both the server and client.

↓
4

Run in Development Mode

Start the development server and client to verify your setup.

Step 1: Fork the Repository ​

  1. Visit SSM on GitHub
  2. Click the "Fork" button in the top-right corner
  3. Wait for GitHub to create your copy of the repository

Step 2: Clone Your Fork ​

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

Step 3: Install Dependencies ​

bash
# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

# Install shared-lib dependencies (if needed)
cd ../shared-lib
npm install

Step 4: Run in Development Mode ​

bash
# Start the server
cd server
npm run dev

# In a new terminal, start the client
cd client
npm run dev

Visit http://localhost:8000 to see the application running.

Finding Issues to Work On ​

Good First Issues
✓ Small scope
✓ Clear requirements
✓ Labeled in GitHub
✓ Good for beginners
Feature Requests
✓ Add new capabilities
✓ Enhancement requests
✓ UI/UX improvements
✓ Performance optimizations
Bug Fixes
✓ Fix reported issues
✓ Improve stability
✓ Address edge cases
✓ Solve usability problems
Documentation
✓ Fix typos/errors
✓ Add missing information
✓ Create tutorials
✓ Improve existing guides

We recommend starting with these types of issues:

  1. Issues labeled good first issue
  2. Documentation improvements
  3. Bug fixes with clear reproduction steps
  4. Features you personally need or would use

Making Changes ​

Creating a Branch ​

Create a branch for your contribution with a descriptive name:

bash
git checkout -b feature/my-contribution

Use these branch naming conventions:

  • feature/ for new features
  • bugfix/ for bug fixes
  • docs/ for documentation changes
  • refactor/ for code refactoring

Code Style Guidelines ​

SSM follows specific code style guidelines to maintain code quality and consistency:

TypeScript/JavaScript Style Guide
  • Formatting: 2-space indentation, LF line endings, single quotes
  • Naming Conventions:
    • PascalCase for classes, interfaces, types, decorators
    • camelCase for variables, functions, methods
    • ALL_CAPS for constants
  • Code Structure:
    • Limit function size (< 50 lines recommended)
    • Use meaningful variable names
    • Add comments for complex logic
  • Types:
    • Use strict typing with interfaces and types
    • Avoid any type when possible
    • Define return types for functions
  • Testing:
    • Write tests for new features
    • Cover edge cases
    • Aim for high code coverage
Server-Side Guidelines
  • NestJS Architecture:
    • Follow the module pattern
    • Use dependency injection
    • Implement interfaces for services
    • Apply proper validation using DTOs
  • Module Encapsulation:
    • Only export services, never repositories
    • Access functionality through service interfaces
    • Use tokens for injection (e.g., DEVICES_SERVICE)
  • Error Handling:
    • Use standardized exception types
    • Include relevant context in errors
    • Follow the API error response format
Client-Side Guidelines
  • React Patterns:
    • Use functional components with hooks
    • Implement proper state management
    • Follow Ant Design Pro patterns
    • Use composition over inheritance
  • UI/UX:
    • Follow the existing design system
    • Ensure responsive design
    • Maintain accessibility standards
    • Consider performance impact

For more detailed guidelines, refer to:

Testing Your Changes ​

Before submitting your changes, ensure they pass all tests:

bash
# Run server tests
cd server
npm run test

# Run client tests
cd client
npm run test

# Run linting checks
npm run lint:check

Fix any issues that arise from these checks.

Submitting Changes ​

Creating a Pull Request ​

  1. Ensure your code passes all tests and checks
  2. Push your branch to your fork:
    bash
    git push origin feature/my-contribution
  3. Visit your fork on GitHub and click the "Compare & pull request" button
  4. Fill out the PR template with a clear description of your changes

PR Description Best Practices ​

Write a descriptive pull request that:

  • Clearly explains what your changes do
  • References any related issues (Fixes #123 or Relates to #456)
  • Includes before/after screenshots for UI changes
  • Lists any breaking changes or migrations required
  • Mentions any testing you've done

Code Review Process ​

After submitting your PR:

  1. Automated CI/CD checks will run on your code
  2. Maintainers will review your changes
  3. Address any feedback or requested changes
  4. Once approved, a maintainer will merge your PR

- Keep PRs focused on a single concern - Break large features into smaller PRs - Respond promptly to review comments - Be open to feedback and suggestions - Update your PR based on review feedback

Documentation Contributions ​

Documentation is crucial for SSM. When contributing documentation:

Documentation Templates ​

All documentation must use one of the official templates:

  1. Feature Guide Template
  2. Concept Explanation Template

Documentation Best Practices ​

  • Use clear, concise language
  • Include screenshots for UI features
  • Add diagrams for architecture concepts
  • Follow the Documentation Template Guide
  • Ensure documentation is accessible to users of all skill levels

Community Guidelines ​

When participating in the SSM community:

  • Be Respectful: Treat all community members with respect
  • Be Constructive: Provide helpful feedback and suggestions
  • Be Collaborative: Work together to find solutions
  • Be Inclusive: Welcome newcomers and help them get started
  • Be Patient: Understand that maintainers are volunteers

Getting Help ​

If you need assistance with your contribution:

Recognition ​

All contributors are valued members of the SSM community:

  • Contributors are credited in release notes
  • Significant contributions may receive special recognition
  • Regular contributors may be invited to join the core team

Next step

🏷️
Good First Issues

Find beginner-friendly issues to get started with

→

Made with love

Copyright © 2025-present Squirrel Team & Contributors