ivuorinen/tree-sitter-shellspec
1
0
Fork 0
mirror of https://github.com/ivuorinen/tree-sitter-shellspec.git synced 2026-01-26 03:34:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
59b45f85058af3bb6ffb0aab2fb6254d4bcda37b
tree-sitter-shellspec/CONTRIBUTING.md
Ismo Vuorinen 59b45f8505 docs: update Node.js requirement to match CI configuration 
- Change Node.js requirement from v16 to v22+ to align with CI matrix
- Update tree-sitter CLI recommendation from global install to npx usage
- Matches actual devDependency configuration in package.json

Addresses PR #1 review comment from CodeRabbit.
2026-01-04 15:32:40 +02:00

8.6 KiB
Raw Blame History

Contributing to tree-sitter-shellspec

Thank you for your interest in contributing to tree-sitter-shellspec! This document provides guidelines and information for contributors.

Table of Contents

Getting Started

Prerequisites

Fork and Clone

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/tree-sitter-shellspec.git
cd tree-sitter-shellspec

  3. Add the upstream repository:

    git remote add upstream https://github.com/ivuorinen/tree-sitter-shellspec.git

Development Setup

  1. Install dependencies:

    npm install

  2. Generate the grammar:

    npm run generate

  3. Run tests:

    npm test

  4. Build the parser:

    npm run build

Development Workflow

Use the provided npm scripts for common development tasks:

# Development loop (generate + test)
npm run dev

# Watch mode for continuous development
npm run dev:watch

# Clean and rebuild everything
npm run rebuild

# Check code style
npm run lint
npm run lint:yaml
npm run lint:markdown

Grammar Development

Understanding the Grammar Structure

The grammar in grammar.js extends tree-sitter-bash and adds ShellSpec-specific constructs:

  • Block types: Describe, Context, It, Example, Specify
  • Hook types: BeforeEach, AfterEach, BeforeAll, AfterAll, etc.
  • Utility blocks: Data, Parameters, Skip, Pending, Todo
  • Statement types: Before/After hooks, Include directive
  • Directives: Include, conditional Skip

Making Grammar Changes

  1. Edit grammar.js with your changes
  2. Generate the parser: npm run generate
  3. Test your changes: npm test
  4. Add test cases in test/corpus/ for new functionality
  5. Update documentation if needed

Grammar Development Guidelines

  • Follow existing patterns - Look at similar rules in the grammar
  • Use appropriate precedence - Avoid conflicts with bash grammar
  • Test extensively - Add comprehensive test cases
  • Document new syntax - Update README.md with examples
  • Consider real-world usage - Test with actual ShellSpec files

Adding Test Cases

Create or update files in test/corpus/:

================================================================================
Test Name
================================================================================

ShellSpec code here

--------------------------------------------------------------------------------

(expected_parse_tree
  structure_here)

Test Organization:

  • describe_blocks.txt - Describe block variations
  • context_blocks.txt - Context block variations
  • it_blocks.txt - It/Example/Specify blocks
  • hook_blocks.txt - Hook block patterns
  • utility_blocks.txt - Data/Parameters/Skip/etc.
  • nested_structures.txt - Complex nested patterns
  • real_world_patterns.txt - Patterns from official examples

Testing

Running Tests

# Run all tests
npm test

# Test specific patterns
tree-sitter test --filter "describe_blocks"
tree-sitter test --filter "real_world_patterns"

# Test with debug output
tree-sitter test --debug

Test Coverage Requirements

  • All new grammar rules must have test coverage
  • Existing tests must continue to pass
  • Real-world examples should be included when possible
  • Edge cases should be tested

Testing New Functionality

  1. Add test cases before implementing
  2. Run tests to see them fail
  3. Implement the grammar changes
  4. Run tests until they pass
  5. Add additional edge case tests

Code Style

Grammar Style

  • Use consistent indentation (2 spaces)
  • Add descriptive comments for complex rules
  • Use meaningful rule names (e.g., shellspec_describe_block)
  • Group related rules together
  • Follow tree-sitter conventions

JavaScript Style

  • Follow Prettier formatting
  • Use const for immutable values
  • Add JSDoc comments for exported functions
  • Follow Node.js best practices

Documentation Style

  • Use clear, concise language
  • Provide practical examples
  • Keep README.md up to date
  • Include code comments where needed

Submitting Changes

Before Submitting

  1. Ensure all tests pass: npm test
  2. Check code style: npm run lint && npm run format -- --check
  3. Update documentation if needed
  4. Test with real ShellSpec files when possible
  5. Run the full development cycle: npm run rebuild

Pull Request Process

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes following the guidelines above

  3. Commit with clear messages:

    git commit -m "feat: add support for Data block modifiers

- Add :raw and :expand modifier support
- Update test cases for new syntax
- Add documentation examples"

  4. Push to your fork:

    git push origin feature/your-feature-name

  5. Create a Pull Request with:

    • Clear description of changes
    • References to related issues
    • Test results and coverage
    • Breaking change notes (if any)

Commit Message Guidelines

Use Conventional Commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • test: - Test additions or changes
  • refactor: - Code refactoring
  • chore: - Maintenance tasks

Reporting Issues

Bug Reports

Use the Bug Report template and include:

  • ShellSpec code that doesn't parse correctly
  • Expected vs actual behavior
  • Environment information
  • Tree-sitter parse output (if available)

Feature Requests

Use the Feature Request template and include:

  • ShellSpec syntax example
  • Use case description
  • Current behavior
  • Links to ShellSpec documentation

Grammar Issues

Use the Grammar Issue template for:

  • Parsing errors
  • Grammar conflicts
  • Performance problems
  • Integration issues

Areas for Contribution

High Priority

  1. Enhanced Data block support

    • :raw and :expand modifiers
    • Pipe filter syntax (Data | command)
    • Multi-line #| syntax

  2. Assertion parsing

    • When/The statement structures
    • Matcher syntax parsing
    • Subject/predicate analysis

  3. Performance optimization

    • Reduce parser conflicts
    • Optimize grammar rules
    • Improve parsing speed

Medium Priority

  1. Editor integration

    • Neovim configuration examples
    • VS Code extension support
    • Emacs tree-sitter integration

  2. Tooling improvements

    • Syntax highlighting themes
    • Language server features
    • Code formatting rules

  3. Documentation

    • Usage tutorials
    • Grammar development guide
    • Editor setup instructions

Low Priority

  1. Advanced features
    • ShellSpec custom matchers
    • Configuration file parsing
    • Metadata extraction

Development Resources

Useful Links

Learning Resources

Getting Help

  • GitHub Discussions: For questions and general discussion
  • Issues: For bugs and feature requests
  • Pull Requests: For code review and collaboration

License

By contributing to tree-sitter-shellspec, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to tree-sitter-shellspec! 🎉