Code Monkey home page Code Monkey logo

vim-mr-interface's Introduction

vim-mr-interface

vim plugin that support doing CRs and MRs in gitlab

Introduction

Writing code require doing code reviews (CRs) on this code. Since you are writing the code in vim, why not do the CR inside vim as well?

The aim of this plugin is to let you do CR on code in gitlab from vim. CR usually include opening a merge request (MR), and then moving over the diff in the code and adding comments into the gitlab's MR. Since you are reading about vim plugins, you probably know and understand why vim is a good tool for writing and reading code. Why won't you want to do your CR in vim as well? This plugin let you do the CR from vim, adding comments and discussion threads wherever you want and updating all this information on the gitlab's MR.

The plugin does all this by using gitlab's API, which let you get, add, change or delete comments from MRs in it (with a lot of other stuff that this plugin doesn't touch).

Usage

This plugin lets you review the code and add comments directly into an open MR.

In order to use it, you should have an open MR in gitlab. Add your comments from vim using the various commands of the plugin, instead of by opening gitlab's web.

Commands

Gitlab Commands

  • MRInterfaceAddComment - Add a comment into the MR.
  • MRInterfaceAddGeneralDiscussionThread - Add a general discussion thread into the MR. A general discussion thread is the same as a comment, but it can be resolved.
  • MRInterfaceAddCodeDiscussionThread - Add a discussion thread on specific location for the MR. This location currently can be only a line of text in one of the changed files (which is enough for almost anything).
  • MRInterfaceAddCodeDiscussionThreadOnOldCode - Add a discussion thread on specific location from old code into the MR. This command will take the current location of the cursor, assume that it is the desired location on an old file and adds a code comment there.
  • MRInterfaceAddCodeDiscussionThreadOnNewCode - Add a discussion thread on specific location from new code into the MR. This command will take the current location of the cursor, assume that it is the desired location on an new file and adds a code comment there.

Cache Commands

The plugin has some commands that can control the internal cache it keeps. This cache will make you type the common values for the MR just once for every merge request. You can read in the help file more about this cache mechanism.

The commands are:

  • MRInterfaceResetCache - Reset the cache.
  • MRInterfaceSetCache - Set all the values in the cache. You will be prompted to insert the values for the different keys one by one.
  • MRInterfaceUpdateValueInCache - Set a specific value in the cache.
  • MRInterfaceAddDefaultToCache - Add all the arguments that the plugin can understand by itself into the cache.

Configuration Options

These flags can be configured for the plugin. These flags should be configured using Glaive.

  • gitlab_server_address - The address of the gitlab server to use (in case you are not using gitlab.com).
  • gitlab_private_token - Your private token to authenticate with gitlab.
  • automatically_insert_cache - Should the cache be inserted authomatically, or should it be only the default.

Mappings

This plugin doesn't define any default mappings by itself. Adding mappings might be annoying to user who customize their vim a lot (it can run over other used mappings, for example). Moreover, the plugin has only commands, adding mapping to them doesn't add any additional value except the speed of using these commands.

You can add mappings by yourself into your .vimrc in order to make the plugin easier to user.

Here is an example for mappings that can be used with this plugin:

nnoremap <unique> <silent> <leader>mc :MRInterfaceAddComment<CR>
nnoremap <unique> <silent> <leader>md :MRInterfaceAddGeneralDiscussionThread<CR>
nnoremap <unique> <silent> <leader>mC :MRInterfaceAddCodeDiscussionThread<CR>
nnoremap <unique> <silent> <leader>mo :MRInterfaceAddCodeDiscussionThreadOnOldCode<CR>
nnoremap <unique> <silent> <leader>mn :MRInterfaceAddCodeDiscussionThreadOnNewCode<CR>
nnoremap <unique> <silent> <leader>ma :MRInterfaceAddDefaultToCache<CR>

Installation

This plugin is written in pure vimscript, but it require some other plugins and system commands in the system.

The plugin can be installed using any method of plugin installation for vim as long as all the Dependencies will be present when the plugin is loaded and run.

An example of how to install this plugin using Vundle:

Plugin 'google/vim-maktaba'
Plugin 'google/vim-glaive'
Plugin 'LucHermitte/lh-vim-lib'
Plugin 'omrisarig13/vim-mr-interface'

Dependencies

  • Curl - command line tool and library for transferring data with URLs
  • google/vim-maktaba - A vimscript plugin library. Used internally by the plugin.
  • google/vim-glaive - utility for configuring maktaba plugins. It is used to set the different configurable variables in the plugin.
  • LucHermitte/lh-vim-lib - Library of Vim functions.

Supported platforms

This plugin should work on any platform that can run the CURL from within vim. However, it was tested only on Linux, so it is not guaranteed to work the same under other systems.

Gitlab API Notes

The plugin uses gitlab's API. Good information about it can be found in the docs pages in Gitlab. Useful pages are:

Here is some more information about the interface that might be a bit harder to find in their site:

Discussion threads on code interface

The interface of adding new discussion threads on code is weird, and act in unexpected ways (for example, when should the value of old line be present).

It seems that this is currently a problem in gitlab itself. I documented some of the usage in this section.

You can read some open issues in gitlab about this here:

(In case one of these issues are closed, this plugin might not be updated, and please report it to me in case you notice it.)

How to add new code discussion thread

The needed information when adding a new discussion thread on the code might be counter intuitive sometimes.

This table includes some of the information for when to set what value in order to add the wanted comment to the line you want to add it.

Comment Type Code On New Line Code On Deleted Line Modified Code (old part) Modified Code (new part) Unmodified code in changed file Renamed File
Old Path New File Name Deleted File Name File Name File Name File Name Old File Name
New Path New File Name Deleted File Name File Name File Name File Name New File Name
Old Line null Wanted Line Wanted Line null Line in old code As described before
New Line Wanted Line null null Wanted Line Line in new code As described before

Generating Tokens

This plugin uses gitlab private token when it authenticate with gitlab. In order you use this plugin, you will need to have a private token that can access gitlab's API.

More information about private tokens (how to generate them, for example), can be found here.

Getting project id

In order to add comments into an MR, you need to know the ID of your project. The ID of the project is a unique identifier that gitlab gave your project when it was created.

The project ID is written in gitlab, in the Details section of your project, right under the name of the project.

Common problems

Comments doesn't appear on changes

In order to make the comment appear as change, you must specify the full sha of all the commits connected to it (base, head and start). If you don't specify the full hash, it will seem to work, however, the comment won't appear on the changes screen. In case you are inside the git repository you are using to add comments, the plugin should automatically send the full SHA.

It is impossible to add comments on unmodified files

It seems that there isn't any way to do it with the current API of gitlab.

There are a couple of issues on it in gitlab:

(In case one of these issues are closed, this plugin might not be updated, and please report it to me in case you notice it.)

Adding comments on multiple lines of code

It seems that this doesn't currently work as well.

The relevant issue on gitlab is here:

(In case one of these issues are closed, this plugin might not be updated, and please report it to me in case you notice it.)

More recommended tools

This plugin aims to help you do CRs in vim. There are some more tools that can help you do MRs in your computer:

  • git-extras - A library that adds more git command. The command that can help solves MRs is git mr. More information can be found in the man page of this command.
  • fugitive - This great vim plugin let you run a lot of git commands from vim. A great command that can help solve MRs is Gdiff with all its different styles (Gvdiff and Gsdiff). This command will let you look about the diff between two git revisions, which can be extremely useful for looking at diff between the target and the source branches of an MR.

FAQ

How should I solve the MR

Sadly, currently this plugin doesn't support any options to solve the MR. It is planned for the future, and if you want to help, you are more than welcome.

Why isn't this plugin developed in gitlab

I already had a user with git plugin in github, and I wanted all the plugins to be in the same place. It might move over to gitlab as well in some point in time the future.

Will this plugin ever support PRs in github as well

Right now, it is not planned to. However, if it will turn to be easy and possible, the plugin might support these options in the future.

Contributing

If you want to contribute anything to this plugin, first of all, thank you.

Secondly, please read CONTRIBUTING.md.

Roadmap

This is the general road-map of the Plugin implementation. Issues might be release in versions prior to their planned release, but they should not be released in versions later than the planned one (except for special cases).

Release v0.1

  • Add roadmap (#1)
  • Add contributing guidelines (#12)
  • Add comments (#2)
  • Add general discussion threads (#3)
  • Add code discussion threads (#4)
  • Add Plugin default parameters (#14)
  • Create Plugin documentation (#5)
  • Release v0.1 (#6)

Release v0.2

  • Change comments to use temporary buffers (#7)
  • Print errors for bad requests (#29)
  • Add option to create comment on current line (#8)
  • Add parameter calculation to the plugin (#9)
  • Add documentation and recommended mappings (#33)
  • Release v0.2 (#16)

Release v1.0

  • Support user configured flags to curl command (#37)
  • Fix single quote in body bug (#36)
  • Add code discussions using fugitive (#10)
  • Release v1.0 (#17)

Future Releases

  • Change authentication to be more secured (#11)
  • Get comments from gitlab (#13)
  • Add comments on the code (#15)

vim-mr-interface's People

Contributors

omrisarig13 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

Forkers

laeeth

vim-mr-interface's Issues

Update all flags in README.md

README.md doesn't include documentation about all the different flags in the plugin.

It should be fixed by adding documentation about all the flags of the plugin. This documentation can be copied from the doc file of the plugin.

Release v0.2

Release v0.2 of the plugin.

Should be close to the issue of #6.

Release v1.0

Release the first actual version of the plugin.

It should add all the documentation just like #6, but it should also include publishing the plugin a bit more (in reddit for example).

Make the plugin understand some of the parameters by itself

There are certain parameters that the code can know how to generate by itself (for example, the current sha of the commit, the mr number, the project id, current file name).

This commit should add the functionality of running the needed commands to get these parameters and add them to the needed functions.

These parameters should still have the option to be configured by the command parameters, but the default should be by running these commands.

Add option to create comments on the current line of code

Add an option to create a comment on the current line of code.

In this issue, the new function that will be added should be able to add the new discussion thread on the current line of code.

This will support only adding comments on the current revision of the code. It will not support adding comments on old revisions of the code as for now (it might need to get the old revision of the code when it is adding the comment).

Support adding suggestions

Gitlab's suggestion let you as a CRer suggest the fix on the given code in the merge request.,

This is done using a message from a specific format. It should be added to the plugin.

This should not be too hard since all that should be done is to construct the message as it is needed by GitLab.

The plugin should support a command that will get a range, and create a buffer with suggestion about this range of lines. The default value of the lines should be the current strings in them (so the user will only need to change the wanted information in it, without copying the rest of the data).

Comment on code results in error

Hi,

thanks for your plugin. Unfortunately it does not completely work for me (might be a problem on my side). At the moment my company uses GitLab Community Edition 13.8.5.

MRInterfaceAddComment does work but adding comments on code lines does not. I edited the autoload/mr_interface.vim a little bit to get back the error. It's the same as if I try the generated curl-command directly in the command line. The result is always:
{"message":"400 Bad request - Note {:line_code=\u003e[\"can't be blank\", \"must be a valid line code\"]}"}
As can be seen here line_code should only be needed if you comment on multiple lines.

The feature to comment on multiple lines got added some time ago, maybe this is the problem.

Or maybe I just don't understand everything correctly. To get the base, start and head_sha I used the command from the gitlab doku here
curl --request GET --header "PRIVATE-TOKEN: xxxx" https://example.com/api/v4/projects/nnnn/merge_requests/mmmm

Despite beeing inside the repo and on the MR-Branches head the SHAs don't get calculated automatically. But I can use HEAD, HEAD~1 and so on. These SHAs are correct if I look at the curl command. Maybe I just understood the documentation wrong and this is the intended behaviour.

Tell me if you need more information.

Add functions to get MR comments from gitlab

Add an action that will get all the MR comments from gitlab and open them in Vim.

These comments should be opened in the quickfixlist (or some close list) and the user should be able to jump between the locations of the various comments in the code.

This should be asynchronous (it goes to gitlab and fetch content, we shouldn't make the user wait for this time).

The user should be able to get different types of comments using different commands (for example, a command for unresolved comments, a command for discussion threads and so on...)

Add MR comments on the code

Add option to see the MR comments on the code itself.

A sign should appear in the sign bar for every comment from gitlab. When the user will stand on this line, the actual comment should appear in the command line of vim. The user should have an option to open the full comment in a preview window.

The sign (and color) will be different for resolved and unresolved comments. Whenever there will be more than one unresolved comment on a line, the sign that will be used will be the sign for unresolved comments.

This should also add a command to toggle the signs.

Add roadmap

Fill the readme with an explanation about what this plugin will do, and a roadmap of the issues that will be done in it.

Add function that will add a discussion thread on the code in gitlab mr

Create a function that will add a new discussion thread about code to the gitlab mr with the given text in it, on the wanted line.

This function should add the new discussion thread on the code as it was added from the use. The function should get all the parameters from the user, without understanding anything by itself.

The function should use the same basic functions that adding general discussion threads and general comments issues has created.

Change autentication method to a more protected one

By now, the plugin should use the authentication method of private tokens. This is quite a bad method because it sends important keys in plain text.

Understand what is the more secure method, and try to change the plugin and make it use it.

Add function that will add a comment on the gitlab mr

Create a function that will add a comment to the gitlab mr with the given text in it.

This function should really basic, and just make sure to talk with the interface of gitlab of adding new comments on an open merge request.

The function should get all the parameters when it is being called, without assuming anything or calculating anything by itself.

This function should currently use private tokens, since it is easier, even if less secured.

Add user flags to curl

Let the user set flags to the curl command, in case he wants to customize it by himself.

Should add a user flag that will be added to the curl command.

Create default parameters to the plugin

Add default variables to the plugin.
They should be used in all the functions, and make it easier to use the different functions (the user will have to type less).

Release version 0.1 of the Plugin

Release the first version of the plugin.

It includes tagging the code on the master branch, adding a release inside github and adding the plugin to vim.org

This version will be very simple, but it is a start and it should be usable (even if not very good).

Create documentation to the Plugin

Create good documentation for the plugin.

It should include:

  • filling the README.md file with all the general information of the plugin.
  • Creating a documentation directory for vim with helpfile, generating documentation on the code using vimdoc, and adding more general documentation for the plugin.

Support adding code discussion threads using fugitive

Fugitive has some commands that let the user see diff in the code (Gdiffsplit, Gvdiffsplit, Ghdiffsplit`, maybe more).

make the plugin support adding comments on code when looking at this diff.

This should make the function that adds discussion threads on the code really easy, and make the plugin actually good. After this issue, the plugin should become really usable for the first time.

Add tests to the plugin

The plugin is written without any tests in it. Add tests on all the functionality of the plugin.

It might not be possible to test all the functionality of the plugin (depending on whethere there are mocks in vimscript), but it is better to have some tests than none at all.

Allow single quote in comments

Currently, whenever there is a single quote in a comment that the user is adding, the comment breaks and no comment at all is being added to the MR.

This is a bug in the plugin, and it should be fixed. The fixed would probably be done by adding some kind of escaping to this character.

Change comment functions to use buffers for comment body

Change all the functions that add comments to the MR (regular comment, general discussion thread, and code discussion thread) to open a temporary buffer, let the user fill it, and then send the code from the temporary buffer to the MR.

It should be a lot easier to write the message in a buffer than to write it as a parameter to the function.

Add bad-request error

whenever there is an error of bad request, the plugin currently prints that the command was added successfully.

This error should be handled like all the other errors are currently being handled in the code.

Make the plugin asynchronic

The plugin is currently written as synchronic (I don't know how to write synchronically plugins as for now).

After the first version (v1.0) of the plugin is released, it should be refactored to be asynchronous.

Add function that will create a new general discussion thread on a gitlab mr

Create a function that will add a discussion thread to the gitlab mr with the given text in it.

This function should be really basic, and just make sure to talk with the interface of gitlab of adding new comments on an open merge request. It should have the same interface as the function written in #2, and use the same internal functions.

The function should get all the parameters when it is being called, without assuming anything or calculating anything by itself.

Change plugin to use maktaba

Maktaba seems like a very good plugin for writing vimscripts.

Change the plugin to be such a plugin.

It would have been better to start with the plugin written in this format, but I want to release the first version and don't have the time to learn it right now.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.