Skip to content

Latest commit

 

History

History
202 lines (136 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

202 lines (136 loc) · 10.2 KB

TeamCity Build

IdeaVim is an open source project created by 130+ 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!

Awards for Quality Contributions

In February 2025, we’re starting a program to award one-year All Products Pack subscriptions to the implementers of quality contributions to the IdeaVim project. The program will continue for all of 2025 and may be prolonged.

Subscriptions can be awarded for merged pull requests that meet the following requirements:

  • The change should be non-trivial, though there might be exceptions — for example, where a trivial fix requires a complicated investigation.
  • The change should fully implement a feature or fix the root cause of a bug. Workarounds or hacks are not accepted.
  • If applicable, the change should be properly covered with unit tests.
  • The work should be performed by the contributor, though the IdeaVim team is happy to review it and give feedback.
  • The change should fix an issue or implement a feature filed by another user. If you want to file an issue and provide a solution to it, your request for a license should be explicitly discussed with the IdeaVim team in the ticket comments.

We'd like to make sure this award program is helpful and fair. Since we just started it and still fine-tuning the details, the final say on giving licenses remains with the IdeaVim team and the requirements might evolve over time.

Also, a few notes:

  • If you have any doubts about whether your change or fix is eligible for the award, get in touch with us in the comments on YouTrack or in any other way.
  • Please mention this program in the pull request text. This is not an absolute requirement, but it will help ensure we know you would like to be considered for an award, but this is not required.
  • During 2025, a single person may only receive a single subscription. Even if you make multiple contributions, you will not be eligible for multiple awards.
  • Any delays caused by the IdeaVim team will not affect eligibility for an award if the other requirements are met.
  • Draft pull requests will not be reviewed unless explicitly requested.
  • Tickets with the ideavim-bounty tag are good candidates for this award.

Before you begin

  • The project is primarily written in Kotlin with a few Java files. When contributing to the project, use Kotlin unless you’re working in areas where Java is explicitly used.

  • If you come across some IntelliJ Platform code, these links may prove helpful:

  • Having any difficulties? Join the brand new Join the chat at https://gitter.im/JetBrains/ideavim 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 IdeaVim
  • IdeaVim tests
  • IdeaVim full verification

Prepared configurations lightPrepared configurations dark

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 in build/distributions. This file can be installed by using Settings | 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 @VimBehaviorDiffers annotation 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.):

  • Ex commands (:set, :s, :nohlsearch):

  • Extensions:

    • Extensions handler: VimExtensionHandler.
    • Available extensions: package com/maddyhome/idea/vim/extension.

  • Common features:

    • State machine. How every particular keystroke is parsed in IdeaVim: KeyHandler.handleKey().
    • Options (incsearch, iskeyword, relativenumber): VimOptionGroup.
    • Plugin startup: PluginStartup.
    • Notifications: NotificationService.
    • Status bar icon: StatusBar.kt.
    • On/off switch: VimPlugin.setEnabled().

Testing

Here are some guides for testing:

  1. Read the javadoc for the @VimBehaviorDiffers annotation in the source code.

  2. 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.
  1. 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 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 doTest are checked with neovim.
  • Tests with @VimBehaviorDiffers or @TestWithoutNeovim annotations 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 MotionType for that.
  • Have you read the interesting things about IdeaVim? Do you remember how dd, yy, and other similar commands work? DuplicableOperatorAction will help you with that. And we also translate it to d_ and y_: KeyHandler.mapOpCommand().
  • All IdeaVim extensions use the same command names as the originals (e.g. <Plug>(CommentMotion), <Plug>ReplaceWithRegisterLine), so you can reuse your .vimrc settings. 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

The IdeaVim plugin is divided into two main modules: IdeaVim and vim-engine. IdeaVim serves as a plugin for JetBrains IDEs, while vim-engine is an IntelliJ Platform-independent Vim engine. This engine is utilized in both the Vim plugin for Fleet 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. If you still encounter any issues with the newer versions of IdeaVim, please contact maintainers.

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.

Resources: