Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
285 lines (207 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

285 lines (207 loc) · 6.95 KB

Contributing to vim-solidity

Thank you for your interest in contributing to vim-solidity! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.

How Can I Contribute?

Reporting Bugs

Before creating a bug report, please check existing issues to avoid duplicates. When creating a bug report, include:

  • Description: Clear description of the problem
  • Steps to reproduce: Minimal steps to reproduce the issue
  • Expected behavior: What you expected to happen
  • Actual behavior: What actually happened
  • Environment: Vim version, OS, terminal emulator
  • Sample code: Minimal Solidity code that demonstrates the issue

Suggesting Enhancements

Enhancement suggestions are welcome! Please provide:

  • Use case: Why is this enhancement useful?
  • Proposed solution: How would you like it to work?
  • Alternatives: Other approaches you've considered
  • Examples: Code examples if applicable

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests if applicable
  5. Run the test suite
  6. Commit your changes (see commit guidelines below)
  7. Push to your branch
  8. Open a Pull Request

Development Setup

Prerequisites

  • Vim 8.0+ or Neovim
  • Git
  • vader.vim for testing

Clone and Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/vim-solidity.git
cd vim-solidity

# Clone vader.vim for testing
git clone https://github.com/junegunn/vader.vim.git test/vader.vim

File Structure

vim-solidity/
├── ftdetect/      # File type detection
├── ftplugin/      # File type plugin settings
├── indent/        # Indentation logic
├── syntax/        # Syntax highlighting
├── test/          # Test suite
│   ├── vader/     # Vader test files
│   ├── fixtures/  # Test Solidity files
│   └── vimrc      # Test configuration
└── README.md

Testing

Running Tests Locally

# Run all tests
vim -Nu test/vimrc -c 'Vader! test/vader/*.vader'

# Run specific test file
vim -Nu test/vimrc -c 'Vader! test/vader/syntax.vader'

# Run interactively (for debugging)
vim -Nu test/vimrc -c 'Vader test/vader/syntax.vader'

Writing Tests

We use vader.vim for testing. Tests are located in test/vader/.

Example syntax test:

Given solidity (test description):
  contract Test {
      uint256 value;
  }

Execute (check syntax highlighting):
  normal! /uint256
  let l:group = synIDattr(synID(line('.'), col('.'), 1), 'name')
  AssertEqual 'solBuiltinType', l:group

Example indentation test:

Given solidity (unindented code):
  contract Test {
  function foo() {
  return 1;
  }
  }

Execute (indent buffer):
  normal! gg=G

Expect solidity (properly indented):
  contract Test {
      function foo() {
          return 1;
      }
  }

Manual Testing

Use the test fixtures to manually verify changes:

# Open a test file
vim test/fixtures/modern.sol

# Check syntax highlighting
:syn list

# Test indentation
gg=G

# Test folding
:set foldmethod=syntax
zM
zR

Submitting Changes

Commit Messages

Follow these guidelines for commit messages:

Add brief summary (50 characters or less)

More detailed explanation if needed. Wrap at 72 characters.

- Use bullet points for multiple changes
- Reference issues: "Fixes #123" or "Closes #456"
- Explain the why, not just the what

Co-Authored-By: Name <email@example.com>

Examples:

Add transient keyword support (0.8.24+)

- Add transient to solKeyword list
- Update syntax tests
- Add test fixture with transient storage

Fixes #45

Pull Request Guidelines

  • One feature per PR: Keep PRs focused on a single feature or fix
  • Update tests: Add or update tests for your changes
  • Update documentation: Update README.md if adding user-facing features
  • Update CHANGELOG: Add an entry to CHANGELOG.md under "Unreleased"
  • Pass CI: Ensure GitHub Actions tests pass
  • Clean history: Rebase and squash commits if needed

PR Template

Your PR description should include:

## Description
Brief description of the changes

## Motivation
Why is this change needed?

## Changes
- List of specific changes
- What was added/modified/removed

## Testing
- How was this tested?
- Which test cases were added/updated?

## Checklist
- [ ] Tests pass locally
- [ ] Added/updated tests for changes
- [ ] Updated CHANGELOG.md
- [ ] Updated README.md if needed
- [ ] Follows style guidelines

Style Guidelines

VimL Style

  • Indentation: 4 spaces (no tabs)
  • Line length: 80 characters where reasonable
  • Comments: Use " for comments, be descriptive
  • Variables: Use descriptive names (l: for local, b: for buffer)
  • Functions: PascalCase for user functions, snake_case for private

Example:

" Check if current line is a function definition
function! s:is_function_line(lnum)
    let l:line = getline(a:lnum)
    return l:line =~# '^\s*function\>'
endfunction

Syntax Highlighting Rules

  • Keyword groups: Use solKeyword, solConstant, solBuiltinType
  • Regions: Use fold option for foldable blocks
  • Contains: Be specific about what regions can contain
  • Highlighting: Link to standard highlight groups when possible

Test Style

  • Descriptive names: Test names should clearly state what they test
  • One concept per test: Each test should verify one thing
  • Fixtures: Add complex test cases to test/fixtures/
  • Comments: Explain non-obvious test logic

Solidity Version Support

vim-solidity aims to support:

  • Current: Latest stable Solidity version (currently 0.8.x)
  • Recent: Previous minor versions still in common use
  • Future: New features added as they're released

When adding support for new Solidity features:

  1. Reference the Solidity version in comments
  2. Add test cases using the new feature
  3. Update CHANGELOG with version info
  4. Consider backward compatibility

Getting Help

  • Questions: Open a GitHub Discussion
  • Bugs: Open an issue with the bug template
  • Features: Open an issue with the feature template
  • Chat: Mention @thesis/vim-solidity maintainers

Recognition

Contributors are recognized in several ways:

  • Mentioned in commit messages (Co-Authored-By)
  • Listed in All Contributors (see README)
  • Highlighted in release notes for major contributions

Thank you for contributing to vim-solidity!