Contributing to MSR

Guide for contributors and maintainers.

Table of contents

  1. Development Setup
    1. Prerequisites
    2. Clone and Install
  2. Development Workflow
    1. Running Tests
    2. Building
    3. Code Quality
  3. Publishing New Versions
    1. Automated Publishing (Recommended)
    2. Manual Publishing
  4. Release Checklist
  5. Code Style
  6. Pull Request Process
  7. Commit Message Guidelines
  8. Documentation
    1. Updating Documentation
  9. Need Help?

Development Setup

Prerequisites

  • Node.js 16 or higher
  • npm 7 or higher
  • Git

Clone and Install 

git clone https://github.com/migration-script-runner/msr-core.git
cd msr-core
npm install

Development Workflow

Running Tests 

# Run all tests (linter + unit + integration)
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run mutation tests (slow)
npm run test:mutation

Building 

# Build the project
npm run build

# The compiled output will be in ./dist

Code Quality 

# Run linter
npm run lint

# Generate all reports (lint + coverage)
npm run test:report

Publishing New Versions

GitHub Actions automatically publishes to npm when the version in package.json changes:

  1. Update the version in package.json: 
    # For patch releases (bug fixes)
npm version patch

# For minor releases (new features, backward compatible)
npm version minor

# For major releases (breaking changes)
npm version major
  2. Commit and push: 
    git push origin master
git push origin --tags
  3. GitHub Actions will automatically:
    • Run all tests
    • Build the package
    • Publish to npm
    • Create git tag

Manual Publishing

If you need to publish manually:

  1. Ensure you’re logged in to npm: 
    npm whoami
# If not logged in:
npm login
  2. Build the project: 
    npm run build
  3. Publish to npm: 
    npm publish --access public
  4. Create and push git tag: 
    git tag v0.2.x
git push origin v0.2.x
  5. Create GitHub release: 
    gh release create v0.2.x \
  --title "v0.2.x - Release Title" \
  --notes "Release notes here"

Release Checklist

Before releasing a new version:

  • All tests pass (npm test)
  • Code coverage is 100% (npm run test:coverage)
  • Documentation is updated
  • CHANGELOG is updated (if exists)
  • Version is bumped in package.json
  • Breaking changes are documented in migration guide (for major/minor with breaking changes)

After releasing:

  • Verify package appears on npm: https://www.npmjs.com/package/@migration-script-runner/core
  • Verify GitHub release is created
  • Update documentation site if needed
  • Close related issues and milestone

Code Style

  • Follow existing code conventions
  • Use TypeScript for all code
  • Add JSDoc comments for all public APIs
  • Keep test coverage at 100%
  • Use meaningful variable and function names

Pull Request Process

  1. Fork the repository
  2. Create a feature branch: 
    git checkout -b feature/your-feature-name
  3. Make your changes
  4. Write tests for new functionality
  5. Run tests to ensure everything passes
  6. Commit your changes with descriptive messages
  7. Push to your fork
  8. Open a Pull Request with:
    • Clear description of changes
    • Link to related issues
    • Test results

Commit Message Guidelines

Use clear, descriptive commit messages:

# Good examples
Fix #42: Resolve backup deletion issue
Add displayLimit configuration option
Update documentation for new list() method

# Bad examples
fix bug
update
changes

Format:

  • Start with action verb (Add, Fix, Update, Remove, etc.)
  • Reference issue number if applicable (Fix #42:)
  • Keep first line under 72 characters
  • Add detailed explanation in body if needed

Documentation

Updating Documentation

Documentation is in the docs/ folder using Jekyll and Just the Docs theme.

Local preview:

# Install Jekyll (one time)
gem install bundler jekyll

# Run locally
cd docs
bundle exec jekyll serve

# View at http://localhost:4000/msr-core/

Documentation structure:

  • docs/index.md - Homepage
  • docs/getting-started.md - Getting started guide
  • docs/configuration.md - Configuration reference
  • docs/api/ - API documentation
  • docs/guides/ - User guides
  • do../version-migration/ - Migration guides

Need Help?

  • Issues: https://github.com/migration-script-runner/msr-core/issues
  • Discussions: https://github.com/migration-script-runner/msr-core/discussions
  • Email: volodyalavrynovych@gmail.com

Thank you for contributing! 🎉