Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
413 lines (309 loc) · 9.34 KB

CONTRIBUTING.md

File metadata and controls

413 lines (309 loc) · 9.34 KB

Contributing to ShopDevs Multi-Shop

We welcome contributions from the Shopify development community!

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • Git
  • Familiarity with Shopify theme development
  • Understanding of multi-shop/multi-brand workflows

Development Setup

# Clone the repository
git clone https://github.com/shopdevs/multi-shop-cli.git
cd multi-shop-cli

# Install dependencies
pnpm install

# Run tests to verify setup
pnpm test

# Start development mode
pnpm run dev

🛠️ Development Workflow

1. Create Feature Branch

git checkout main
git pull origin main  
git checkout -b feature/your-feature-name

2. Development

# Make your changes
# Add comprehensive tests
# Update documentation

# Validate your changes
pnpm run validate  # Runs lint, typecheck, and tests

3. Testing

# Unit tests
pnpm test

# E2E tests  
pnpm run test:e2e

# Security checks
pnpm run security:audit

# Performance validation
pnpm run test:performance

4. Submit Pull Request

git push origin feature/your-feature-name
# Then create PR via GitHub interface

📋 Pull Request Guidelines

PR Checklist

  • Tests added/updated - All new functionality has tests
  • Documentation updated - README, JSDoc, guides updated
  • Type safety - TypeScript types added for new APIs
  • Security reviewed - No credential exposure, input validation added
  • Performance tested - No performance regressions
  • Cross-platform tested - Works on Windows, macOS, Linux
  • Breaking changes documented - Migration guide provided if needed

PR Description Template

## What does this PR do?

Brief description of the changes

## Why is this change needed?

Context about the problem being solved

## How was this tested?

- [ ] Unit tests added/updated
- [ ] E2E tests pass
- [ ] Manually tested on [OS/environment]
- [ ] Performance impact assessed

## Breaking changes?

- [ ] No breaking changes
- [ ] Breaking changes (migration guide provided)

## Security considerations

- [ ] No new security risks introduced
- [ ] Input validation added where needed
- [ ] No credentials exposed in logs/errors

🧪 Testing Standards

Test Coverage Requirements

  • Minimum 80% coverage for all new code
  • 100% coverage for security-critical functions
  • Integration tests for CLI workflows
  • Performance tests for operations >1000ms

Test Categories

Unit Tests (__tests__/*.test.js)

describe('ShopManager', () => {
  test('should create shop configuration', () => {
    // Test individual methods
  });
});

Integration Tests (__tests__/integration/*.test.js)

describe('Shop Creation Workflow', () => {
  test('should complete full shop setup', () => {
    // Test complete workflows
  });
});

Security Tests (__tests__/security/*.test.js)

describe('Credential Security', () => {
  test('should never expose credentials', () => {
    // Test security measures
  });
});

Performance Tests (__tests__/performance/*.test.js)

describe('Performance', () => {
  test('should complete operations within SLA', () => {
    // Test performance requirements
  });
});

📚 Documentation Standards

Code Documentation

JSDoc Requirements

/**
 * Creates a new shop configuration with validation
 * @param {string} shopId - Unique shop identifier
 * @param {Object} config - Shop configuration object
 * @param {Object} config.shopify - Shopify-specific settings
 * @returns {Promise<Object>} Created shop configuration
 * @throws {ShopValidationError} When configuration is invalid
 * @throws {ShopConfigurationError} When creation fails
 * @example
 * const config = await shopManager.createShop('my-shop', {
 *   name: 'My Shop',
 *   shopify: { stores: { ... } }
 * });
 */
async createShop(shopId, config) {
  // Implementation
}

README Updates

  • Update feature sections for new capabilities
  • Add examples for new commands
  • Update installation instructions if needed
  • Include migration notes for breaking changes

Changelog (CHANGELOG.md)

Follow Conventional Changelog:

## [1.1.0] - 2025-01-25
### Added
- New campaign management features
- Enhanced security validation

### Changed  
- Improved error messages
- Updated CLI interface

### Fixed
- Credential validation edge case
- Performance issue with large shop lists

### Security
- Enhanced credential encryption
- Added audit logging

🔒 Security Guidelines

Credential Handling

✅ DO:

  • Use SecurityManager for all credential operations
  • Validate all user inputs with schemas
  • Log operations without sensitive data
  • Use proper file permissions (600 for credentials)
  • Implement integrity checks for credential files

❌ DON'T:

  • Log or display actual theme tokens
  • Store credentials in environment variables
  • Use credentials in test fixtures (use mocks)
  • Transmit credentials over network
  • Include credentials in error messages

Code Security

// ✅ Correct: Validated input
const validator = new ShopConfigValidator();
const safeShopId = validator.validateShopId(userInput);

// ❌ Wrong: Unvalidated input
const shopId = userInput; // Potential injection vector

🚀 Performance Guidelines

Performance Requirements

  • CLI startup: <500ms cold start
  • Shop operations: <2 seconds for complex operations
  • Memory usage: <100MB for typical workflows
  • File I/O: Minimize filesystem operations

Performance Testing

test('should complete shop listing within performance SLA', () => {
  const startTime = performance.now();
  const shops = shopManager.listShops();
  const duration = performance.now() - startTime;
  
  expect(duration).toBeLessThan(100); // 100ms SLA
});

🏷️ Release Process

Semantic Versioning

We follow Semantic Versioning:

  • MAJOR (1.0.0 → 2.0.0): Breaking changes
  • MINOR (1.0.0 → 1.1.0): New features (backwards compatible)
  • PATCH (1.0.0 → 1.0.1): Bug fixes (backwards compatible)

Release Checklist

  • All tests passing on all supported platforms
  • Security audit clean
  • Performance benchmarks met
  • Documentation updated
  • CHANGELOG.md updated
  • Version bumped appropriately
  • GitHub release created with release notes

Publishing

# Validate release
pnpm run validate

# Version bump and publish
pnpm run release

🔄 CI/CD Pipeline

Continuous Integration

Our CI pipeline runs automatically on every push and pull request:

Test Matrix

  • Node versions: 18, 20, 22
  • Operating systems: Ubuntu, macOS, Windows
  • Total test combinations: 9 (3 nodes × 3 OSes)

CI Jobs

1. Test Job (runs on all matrix combinations)

- Checkout code
- Install dependencies (pnpm)
- Run linter
- Run type checking
- Run test suite
- Upload coverage (Ubuntu + Node 20 only)

2. Quality Job (runs on Ubuntu + Node 20)

- Run full validation (lint + typecheck + test)
- Check package size
- Build package
- Verify build output

3. Security Job (runs on Ubuntu + Node 20)

- Run npm audit
- Check for outdated dependencies

CI Status

All PRs must pass CI before merging:

  • ✅ All tests pass on all platforms
  • ✅ No linting errors
  • ✅ No type errors
  • ✅ Build succeeds
  • ✅ Coverage report uploaded

View CI status: GitHub Actions

Automated Releases

Releases are triggered manually via GitHub Actions:

Release Process

  1. Prepare:

    • Update CHANGELOG.md with release notes
    • Move [Unreleased] content to new version section
    • Commit changelog changes

  2. Trigger Release:

    • Go to Actions → Release workflow
    • Select version type (patch/minor/major)
    • Click "Run workflow"

  3. Automated Steps:

    • Run full validation
    • Build package
    • Version bump (npm version)
    • Create GitHub release
    • Publish to npm
    • Push changes and tags

  4. Post-Release:

    • Verify package on npm
    • Test installation
    • Update dependent projects

Manual Release (if needed)

# Ensure changelog is updated
pnpm run update-changelog

# Run release script
pnpm run release:patch  # or release:minor, release:major

🤝 Community

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and community help
  • Email: security@shopdevs.com (security issues only)

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow
  • Report security issues responsibly

📖 Resources

Learning Materials

Tools We Use

  • ESLint + Prettier: Code formatting and linting
  • Jest: Testing framework with coverage reporting
  • TypeScript: Type safety and documentation
  • Commander.js: CLI framework
  • @clack/prompts: Beautiful CLI interfaces

Thank you for contributing to the Shopify development ecosystem! 🎉