Skip to content

Commit 8d20d60

Browse files
mhluongomhluongo
committed
Add CHANGELOG and CONTRIBUTING documentation
1 parent d14b384 commit 8d20d60

2 files changed

Lines changed: 372 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Changelog
2+
3+
All notable changes to vim-solidity will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Comprehensive testing infrastructure with vader.vim
12+
- GitHub Actions CI for automated testing
13+
- Solidity 0.8.24 `transient` keyword support
14+
- Solidity 0.8.19 `using ... global` syntax support
15+
- Solidity 0.8.18 user-defined value types (`type Foo is uint256`)
16+
- Solidity 0.8.4 `error` keyword for custom errors
17+
- `unchecked` block syntax (0.8.0+)
18+
- `fallback()` and `receive()` special function keywords
19+
- `global` keyword for library attachments
20+
- Contract-level code folding for contracts, libraries, and interfaces
21+
- Foundry test file detection (`.t.sol` extension)
22+
- Foundry script file detection (`.s.sol` extension)
23+
- Buffer-local variable `b:solidity_file_type` to distinguish file types
24+
- Test fixtures for modern Solidity features, indentation, and folding
25+
- Comprehensive test suites for syntax, indentation, and folding
26+
27+
### Fixed
28+
- Contract bodies can now be folded (Issue #11)
29+
30+
### Changed
31+
- Enhanced ftdetect to recognize Foundry file naming conventions
32+
- Improved syntax highlighting for modern Solidity 0.8.x features
33+
- Updated maintainer information
34+
35+
## [0.7.0] - 2021-01-17
36+
37+
### Changed
38+
- Leave foldmethod to be configured by the user
39+
- Fix syntax file maintainer
40+
41+
### Added
42+
- Add 'require' to keywords
43+
- Add 'revert' to keywords
44+
- Add Yul opcode dialect
45+
- Ensure Yul ops only highlight in assembly blocks
46+
- Add 'switch' to statements
47+
48+
### Improved
49+
- Better handling of comments and doc comments
50+
- Enhanced NatSpec comment support
51+
52+
---
53+
54+
## Migration Notes
55+
56+
### From 0.7.0 to Unreleased
57+
58+
If you were using the old vim-solidity, the main changes are:
59+
60+
1. **Modern Solidity Support**: All Solidity 0.8.x features are now supported
61+
2. **Contract Folding**: Enable with `set foldmethod=syntax` to fold entire contracts
62+
3. **Foundry Support**: `.t.sol` and `.s.sol` files are automatically recognized
63+
4. **Testing**: The plugin now has comprehensive automated tests
64+
65+
### Future Breaking Changes
66+
67+
No breaking changes are planned. The plugin maintains backward compatibility
68+
with Vim 8.0+ and works in Neovim (though Neovim users may prefer solidity.nvim
69+
for LSP features).
70+
71+
---
72+
73+
## Version History
74+
75+
- **Unreleased**: Modern Solidity 0.8.x support, testing infrastructure, Foundry integration
76+
- **0.7.0**: Yul support, comment improvements, basic keyword additions
77+
- **Earlier versions**: See git history
78+
79+
---
80+
81+
## Contributing
82+
83+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to vim-solidity.
84+
85+
## License
86+
87+
MIT License - see [LICENSE](LICENSE) for details.

‎CONTRIBUTING.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
# Contributing to vim-solidity
2+
3+
Thank you for your interest in contributing to vim-solidity! This document provides guidelines and instructions for contributing.
4+
5+
## Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [How Can I Contribute?](#how-can-i-contribute)
9+
- [Development Setup](#development-setup)
10+
- [Testing](#testing)
11+
- [Submitting Changes](#submitting-changes)
12+
- [Style Guidelines](#style-guidelines)
13+
14+
## Code of Conduct
15+
16+
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.
17+
18+
## How Can I Contribute?
19+
20+
### Reporting Bugs
21+
22+
Before creating a bug report, please check existing issues to avoid duplicates. When creating a bug report, include:
23+
24+
- **Description**: Clear description of the problem
25+
- **Steps to reproduce**: Minimal steps to reproduce the issue
26+
- **Expected behavior**: What you expected to happen
27+
- **Actual behavior**: What actually happened
28+
- **Environment**: Vim version, OS, terminal emulator
29+
- **Sample code**: Minimal Solidity code that demonstrates the issue
30+
31+
### Suggesting Enhancements
32+
33+
Enhancement suggestions are welcome! Please provide:
34+
35+
- **Use case**: Why is this enhancement useful?
36+
- **Proposed solution**: How would you like it to work?
37+
- **Alternatives**: Other approaches you've considered
38+
- **Examples**: Code examples if applicable
39+
40+
### Pull Requests
41+
42+
1. Fork the repository
43+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
44+
3. Make your changes
45+
4. Add tests if applicable
46+
5. Run the test suite
47+
6. Commit your changes (see commit guidelines below)
48+
7. Push to your branch
49+
8. Open a Pull Request
50+
51+
## Development Setup
52+
53+
### Prerequisites
54+
55+
- Vim 8.0+ or Neovim
56+
- Git
57+
- [vader.vim](https://github.com/junegunn/vader.vim) for testing
58+
59+
### Clone and Setup
60+
61+
```bash
62+
# Clone your fork
63+
git clone https://github.com/YOUR_USERNAME/vim-solidity.git
64+
cd vim-solidity
65+
66+
# Clone vader.vim for testing
67+
git clone https://github.com/junegunn/vader.vim.git test/vader.vim
68+
```
69+
70+
### File Structure
71+
72+
```
73+
vim-solidity/
74+
├── ftdetect/ # File type detection
75+
├── ftplugin/ # File type plugin settings
76+
├── indent/ # Indentation logic
77+
├── syntax/ # Syntax highlighting
78+
├── test/ # Test suite
79+
│ ├── vader/ # Vader test files
80+
│ ├── fixtures/ # Test Solidity files
81+
│ └── vimrc # Test configuration
82+
└── README.md
83+
```
84+
85+
## Testing
86+
87+
### Running Tests Locally
88+
89+
```bash
90+
# Run all tests
91+
vim -Nu test/vimrc -c 'Vader! test/vader/*.vader'
92+
93+
# Run specific test file
94+
vim -Nu test/vimrc -c 'Vader! test/vader/syntax.vader'
95+
96+
# Run interactively (for debugging)
97+
vim -Nu test/vimrc -c 'Vader test/vader/syntax.vader'
98+
```
99+
100+
### Writing Tests
101+
102+
We use [vader.vim](https://github.com/junegunn/vader.vim) for testing. Tests are located in `test/vader/`.
103+
104+
**Example syntax test:**
105+
```vader
106+
Given solidity (test description):
107+
contract Test {
108+
uint256 value;
109+
}
110+
111+
Execute (check syntax highlighting):
112+
normal! /uint256
113+
let l:group = synIDattr(synID(line('.'), col('.'), 1), 'name')
114+
AssertEqual 'solBuiltinType', l:group
115+
```
116+
117+
**Example indentation test:**
118+
```vader
119+
Given solidity (unindented code):
120+
contract Test {
121+
function foo() {
122+
return 1;
123+
}
124+
}
125+
126+
Execute (indent buffer):
127+
normal! gg=G
128+
129+
Expect solidity (properly indented):
130+
contract Test {
131+
function foo() {
132+
return 1;
133+
}
134+
}
135+
```
136+
137+
### Manual Testing
138+
139+
Use the test fixtures to manually verify changes:
140+
141+
```bash
142+
# Open a test file
143+
vim test/fixtures/modern.sol
144+
145+
# Check syntax highlighting
146+
:syn list
147+
148+
# Test indentation
149+
gg=G
150+
151+
# Test folding
152+
:set foldmethod=syntax
153+
zM
154+
zR
155+
```
156+
157+
## Submitting Changes
158+
159+
### Commit Messages
160+
161+
Follow these guidelines for commit messages:
162+
163+
```
164+
Add brief summary (50 characters or less)
165+
166+
More detailed explanation if needed. Wrap at 72 characters.
167+
168+
- Use bullet points for multiple changes
169+
- Reference issues: "Fixes #123" or "Closes #456"
170+
- Explain the why, not just the what
171+
172+
Co-Authored-By: Name <email@example.com>
173+
```
174+
175+
**Examples:**
176+
```
177+
Add transient keyword support (0.8.24+)
178+
179+
- Add transient to solKeyword list
180+
- Update syntax tests
181+
- Add test fixture with transient storage
182+
183+
Fixes #45
184+
```
185+
186+
### Pull Request Guidelines
187+
188+
- **One feature per PR**: Keep PRs focused on a single feature or fix
189+
- **Update tests**: Add or update tests for your changes
190+
- **Update documentation**: Update README.md if adding user-facing features
191+
- **Update CHANGELOG**: Add an entry to CHANGELOG.md under "Unreleased"
192+
- **Pass CI**: Ensure GitHub Actions tests pass
193+
- **Clean history**: Rebase and squash commits if needed
194+
195+
### PR Template
196+
197+
Your PR description should include:
198+
199+
```markdown
200+
## Description
201+
Brief description of the changes
202+
203+
## Motivation
204+
Why is this change needed?
205+
206+
## Changes
207+
- List of specific changes
208+
- What was added/modified/removed
209+
210+
## Testing
211+
- How was this tested?
212+
- Which test cases were added/updated?
213+
214+
## Checklist
215+
- [ ] Tests pass locally
216+
- [ ] Added/updated tests for changes
217+
- [ ] Updated CHANGELOG.md
218+
- [ ] Updated README.md if needed
219+
- [ ] Follows style guidelines
220+
```
221+
222+
## Style Guidelines
223+
224+
### VimL Style
225+
226+
- **Indentation**: 4 spaces (no tabs)
227+
- **Line length**: 80 characters where reasonable
228+
- **Comments**: Use `"` for comments, be descriptive
229+
- **Variables**: Use descriptive names (`l:` for local, `b:` for buffer)
230+
- **Functions**: PascalCase for user functions, snake_case for private
231+
232+
**Example:**
233+
```vim
234+
" Check if current line is a function definition
235+
function! s:is_function_line(lnum)
236+
let l:line = getline(a:lnum)
237+
return l:line =~# '^\s*function\>'
238+
endfunction
239+
```
240+
241+
### Syntax Highlighting Rules
242+
243+
- **Keyword groups**: Use `solKeyword`, `solConstant`, `solBuiltinType`
244+
- **Regions**: Use `fold` option for foldable blocks
245+
- **Contains**: Be specific about what regions can contain
246+
- **Highlighting**: Link to standard highlight groups when possible
247+
248+
### Test Style
249+
250+
- **Descriptive names**: Test names should clearly state what they test
251+
- **One concept per test**: Each test should verify one thing
252+
- **Fixtures**: Add complex test cases to `test/fixtures/`
253+
- **Comments**: Explain non-obvious test logic
254+
255+
## Solidity Version Support
256+
257+
vim-solidity aims to support:
258+
259+
- **Current**: Latest stable Solidity version (currently 0.8.x)
260+
- **Recent**: Previous minor versions still in common use
261+
- **Future**: New features added as they're released
262+
263+
When adding support for new Solidity features:
264+
265+
1. Reference the Solidity version in comments
266+
2. Add test cases using the new feature
267+
3. Update CHANGELOG with version info
268+
4. Consider backward compatibility
269+
270+
## Getting Help
271+
272+
- **Questions**: Open a GitHub Discussion
273+
- **Bugs**: Open an issue with the bug template
274+
- **Features**: Open an issue with the feature template
275+
- **Chat**: Mention @thesis/vim-solidity maintainers
276+
277+
## Recognition
278+
279+
Contributors are recognized in several ways:
280+
281+
- Mentioned in commit messages (Co-Authored-By)
282+
- Listed in All Contributors (see README)
283+
- Highlighted in release notes for major contributions
284+
285+
Thank you for contributing to vim-solidity!

0 commit comments

Comments
 (0)