Contributing

Contributing to mage-db-sync

Thank you for your interest in contributing to mage-db-sync! We welcome contributions from the community.

Getting Started

Before you begin:

• Read the documentation to understand what the project does
• Check existing issues to see if your contribution is already being discussed
• For major changes, open an issue first to discuss your proposed changes

Development Setup

Prerequisites

• Basic understanding of TypeScript
• Basic understanding of SSH and database operations (for testing)

Setting Up Your Development Environment

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/mage-db-sync.git
   cd mage-db-sync

3. Add upstream remote:

   git remote add upstream https://github.com/jellesiderius/mage-db-sync.git

4. Install dependencies:

   npm install

5. Build the project:

   npm run build

6. Test your local version:

   npm link
   # Now you can run mage-db-sync from anywhere

7. Development workflow:

   For active development, use TypeScript's watch mode for automatic compilation:

   # In one terminal, start the TypeScript compiler in watch mode
   tsc --watch

   This will automatically recompile your TypeScript files whenever you save changes, making development faster and more convenient. You can then test your changes immediately with mage-db-sync in another terminal.

Project Structure

mage-db-sync/
├── src/
│   ├── controllers/      # Command controllers (start, open-folder, etc.)
│   ├── core/            # Core services (DI container, task factory)
│   ├── models/          # Data models
│   ├── questions/       # Interactive CLI questions
│   ├── services/        # Business logic services
│   ├── tasks/           # Task implementations (download, import, etc.)
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Utility functions and helpers
├── config/              # Configuration samples
├── scripts/             # Build and setup scripts
├── bin/                 # CLI entry point
└── dist/                # Compiled JavaScript (generated)

Key Files

• src/mage-db-sync.ts - Main entry point
• src/controllers/StartController.ts - Main workflow orchestration
• src/tasks/DownloadTask.ts - Database download logic
• src/services/ConfigService.ts - Configuration management
• src/utils/ConfigPathResolver.ts - Config file resolution logic

Making Changes

TypeScript Style

• Use TypeScript for all new code
• Enable strict mode where possible
• Provide proper type definitions (avoid any when possible)
• Use meaningful variable and function names

Code Formatting

• Use 4 spaces for indentation
• Follow existing code style in the project
• Run the linter before committing:

  npm run lint

Best Practices

• Error Handling: Provide clear, actionable error messages

  • Include file paths when relevant
  • Suggest solutions with [TIP] hints
  • Don't show stack traces to end users (only in debug mode)

• Logging: Use the logger service for important operations

  const logger = this.services.getLogger();
  logger.info('Operation completed', { component: 'YourComponent' });

• User Experience:

  • Keep CLI output clean and informative
  • Use progress indicators for long operations
  • Show clear success/error messages

• Security:

  • Never log sensitive data (passwords, SSH keys)
  • Validate user input
  • Use secure file permissions

Comments

• Write self-documenting code
• Add comments for complex logic
• Document public APIs with JSDoc:

  /**
   * Resolves config file path with fallback mechanism
   *
   * @param relativePath - Relative path within config directory
   * @returns Full path to config file, or null if not found
   */
  public static resolveConfigPath(relativePath: string): string | null {
      // ...
  }

Testing

Manual Testing

Currently, the project relies on manual testing. When contributing:

1. Test your changes thoroughly:

   • Test with different strip modes (stripped, full, custom)
   • Test with and without import enabled
   • Test error conditions and edge cases

2. Test in different scenarios:

   • Fresh install
   • Upgrade from previous version
   • With and without .mage-db-sync-config.json

3. Test the full workflow:

   • Database download
   • Database import
   • Configuration resolution

Submitting Your Changes

Once you've completed your changes and tested them thoroughly, follow these steps to submit a pull request:

1. Commit your changes:

   git add .
   git commit -m "Clear description of your changes"

2. Push to your fork:

   git push origin your-branch-name

3. Create a Pull Request:

   • Go to your fork on GitHub
   • Click "Pull Request" or "Compare & pull request"
   • Fill in a clear title and description
   • Reference any related issues (e.g., "Fixes #123")
   • Describe what you changed and why

4. PR Description Template:

   ## Description
   Brief description of the changes
   
   ## Changes Made
   - Change 1
   - Change 2
   
   ## Testing
   How you tested the changes
   
   ## Related Issues
   Fixes #123

5. Wait for review:

   • Maintainers will review your PR
   • Be responsive to feedback and questions
   • Make any requested changes by pushing to the same branch

Types of Contributions

We welcome many types of contributions:

Code Contributions

• New Features: Add new functionality
• Bug Fixes: Fix reported issues
• Performance: Improve speed or efficiency
• Refactoring: Improve code quality without changing behavior

Documentation

• README: Improve main documentation
• Code Comments: Add or improve inline documentation
• Wiki: Add guides and tutorials
• Examples: Add example configurations

Thank you for contributing to mage-db-sync! 🎉