8.2 KiB
/statusIcon.svg?guest=1)
IdeaVim is an open source project created by 80+ contributors. Would you like to make it even better? That’s wonderful!
This page is created to help you start contributing. And who knows, maybe in a few days this project will be brighter than ever!
⚠️ The plugin is currently under a huge refactoring aiming to split into vim-engine and IdeaVim in order to support the new Fleet IDE. Please see Fleet refactoring.
Before you begin
-
The project is written in Kotlin and Java. Choose whichever language you feel more comfortable with, or maybe one that you’d like to get to know better (why not start learning Kotlin right now?).
-
If you come across some IntelliJ Platform code, these links may prove helpful:
-
Having any difficulties? Join the brand new
for IdeaVim developers and contributors!
OK, ready to do some coding?
Yes, I'm ready for some coding
- Fork the repository and clone it to the local machine.
- Open the project with IntelliJ IDEA.
Yoo hoo! You’re all set to begin contributing. We've prepared some useful configurations for you:
Start IJ with IdeaVimIdeaVim testsIdeaVim full verification
And here are useful gradle commands:
./gradlew runIde— start the dev version of IntelliJ IDEA with IdeaVim installed../gradlew test— run tests../gradlew buildPlugin— build the plugin. The result will be located inbuild/distributions. This file can be installed by usingSettings | Plugin | >Gear Icon< | Install Plugin from Disk.... You can stay with your personal build for a few days or send it to a friend for testing.
Warmup
- Pick a few relatively simple tasks that are tagged with #patch_welcome in the issue tracker.
- Read the javadoc for the
@VimBehaviorDiffersannotation in the source code and fix the corresponding functionality. - Implement one of the requested #vim plugins.
🔸 Selected an issue to work on? Leave a comment in a YouTrack ticket or create a draft PR to indicate that you've started working on it so that you might get additional guidance and feedback from the maintainers.
Where to start in the codebase
If you are looking for:
-
Vim commands (
w,<C-O>,p, etc.):- Any particular command:
package-info.java. - How commands are executed in common:
EditorActionHandlerBase. - Key mapping:
KeyHandler.handleKey().
- Any particular command:
-
Ex commands (
:set,:s,:nohlsearch):- Any particular ex command: package
com.maddyhome.idea.vim.ex.handler. - Vim script grammar:
Vimscript.g4. - Vim script parsing: package
com.maddyhome.idea.vim.vimscript.parser. - Vim script executor:
Executor.
- Any particular ex command: package
-
Extensions:
- Extensions handler:
VimExtensionHandler. - Available extensions: package
com/maddyhome/idea/vim/extension.
- Extensions handler:
-
Common features:
- State machine. How every particular keystroke is parsed in IdeaVim:
KeyHandler.handleKey(). - Options (
incsearch,iskeyword,relativenumber):OptionServiceImpl. - Plugin startup:
PluginStartup. - Notifications:
NotificationService. - Status bar icon:
StatusBar.kt. - On/off switch:
VimPlugin.setEnabled().
- State machine. How every particular keystroke is parsed in IdeaVim:
Testing
Here are some guides for testing:
-
Read the javadoc for the
@VimBehaviorDiffersannotation in the source code. -
Please avoid senseless text like "dhjkwaldjwa", "asdasdasd", "123 123 123 123", etc. Use a few lines of code or the following template:
Lorem Ipsum
Lorem ipsum dolor sit amet,
consectetur adipiscing elit
Sed in orci mauris.
Cras id tellus in ex imperdiet egestas.
- Don't forget to test your functionality with line start, line end, file start, file end, empty line, multiple carets, dollar motion, etc.
Neovim
IdeaVim has an experimental integration with neovim in tests. Tests that are performed with doTest also executed in
neovim instance, and the state of IdeaVim is asserted to be the same as the state of neovim.
- Only tests that use
doTestare checked with neovim. - Tests with
@VimBehaviorDiffersor@TestWithoutNeovimannotations don't use neovim.
Property-based tests
Property-based tests are located under propertybased package. These tests a flaky by nature
although in most cases they are stable. If the test fails on your TeamCity run, try to check the test output and understand
if the fail is caused by your changes. If it's not, just ignore the test.
A common direction
We’re trying to make IdeaVim close to the original Vim both in terms of functionality and architecture.
- Vim motions can be either inclusive, exclusive, or linewise.
In IdeaVim, you can use
MotionTypefor that. - Have you read the interesting things about IdeaVim?
Do you remember how
dd,yy, and other similar commands work?DuplicableOperatorActionwill help you with that. And we also translate it tod_andy_:KeyHandler.mapOpCommand(). - All IdeaVim extensions use the same command names as the originals (e.g.
<Plug>(CommentMotion),<Plug>ReplaceWithRegisterLine), so you can reuse your.vimrcsettings. We also support proper command mappings (functions are mapped to<Plug>...), the operator function (OperatorFunction), and so on. - Magic is supported as well. See
Magic.
Fleet refactoring
At the moment, IdeaVim is under an active refactoring aiming to split IdeaVim into two modules: vim-engine and IdeaVim.
If you develop a plugin that depends on IdeaVim: We have an instrument to check that our changes don't affect
the plugins in the marketplace. Also, we commit to support currently used API at least till the end of 2022.
If you still encounter any issues with the newer versions of IdeaVim, please contact maintainers.
We kindly ask you not to use anything from the new API (like VimEditor, injector) because at the moment we don't
guarantee the compatibility of this API in the future versions.
I read the whole page but something is still unclear.
Oh no! No cookies for the maintainers today! Please tell us about it so we can help.
I’ve found a bug in this documentation.
No beer in the bar for us unless it's fixed. Let us know situation so we might be able to fix it.
The lack of documentation or a javadoc/ktdoc makes it difficult to start contributing.
This is just terrible. You know what to do.