From: Sergey Matveev Date: Fri, 17 Jul 2015 20:48:42 +0000 (+0300) Subject: Documentation refactoring and updating X-Git-Tag: 0.1^0 X-Git-Url: http://www.git.stargrave.org/?p=gerrvim.git;a=commitdiff_plain;h=2c7409977586ff6f652cfe7609f17637c1ce93ec Documentation refactoring and updating --- diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 3b4298f..0000000 --- a/INSTALL +++ /dev/null @@ -1,8 +0,0 @@ -You must have Fugitive (http://www.vim.org/scripts/script.php?script_id=2975) -pluging installed in your Vim editor. Just copy plugin/gerrvim.vim file -to ~/.vim/plugin. Optionally copy documentation from doc/gerrvim.txt -to ~/.vim/doc. - -gerrvim2json.pl converter requires Perl interpreter and JSON -(https://metacpan.org/pod/JSON) library. No specific installation for it -required -- just call it from any place. diff --git a/README b/README index 1939e99..d076a9f 100644 --- a/README +++ b/README @@ -1,27 +1,3 @@ - Gerrit review's comments preparation helper (Herr Vim) - -Gerrit (https://www.gerritcodereview.com/) code review system by default -has Web-based interface for creating comments for review. It requires to -be online, with enabled JavaScript. It does not play well with some -browsers that captures keystrokes. IT has no ability to change interface -to something more convenient and comfortable to work with. - -Fortunately it has some API that provides ability to post bunch of -comments for review in JSON format and you can use it to publish -comments created with convenient offline tools. - -This Vim plugin is intended to be Web-interface replacement for review -creation process. It uses Vim with Fugitive plugin to create a temporary -file (gerrvim.txt) with aggregated comments. Then this gerrvim.txt file -is converted to JSON suitable to be posted to Gerrit like this (or use -REST-API interface): - - gerrvim2json.pl /tmp/gerrvim.txt | ssh gerrit gerrit review --json - -It allows creation of multiline optional review message and comments for -line ranges inside files. - -Installation instruction is in INSTALL. -Format of the temporary gerrvim.txt file is described in gerrvim2json.pl. - -gerrvim is free software: see the file COPYING for copying conditions. +Gerrit review's comments preparation helper (Herr Vim). +See doc/gerrvim.txt for description and installation instructions. +Gerrvim is free software: see the file COPYING for copying conditions. diff --git a/doc/gerrvim.txt b/doc/gerrvim.txt index 3b0f3ca..cead1d3 100644 --- a/doc/gerrvim.txt +++ b/doc/gerrvim.txt @@ -1,13 +1,91 @@ -*gerrvim.txt* Gerrit review's comments preparation helper +*gerrvim.txt* Gerrit review's comments preparation helper (Herr Vim) -CONFIGURATION *gerrvim-configuration* +OVERVIEW *gerrvim-overview* -The only option is the placement of temporary file with aggregated -comments. By default it is /tmp/gerrvim.txt. You can override it -in your .vimrc: > +Gerrit (https://www.gerritcodereview.com/) code review system by default +has Web-based interface for creating comments for review. It requires to +be online, with enabled JavaScript. It does not play well with some +browsers that captures keystrokes. IT has no ability to change interface +to something more convenient and comfortable to work with. + +Fortunately it has some API that provides ability to post bunch of +comments for review in JSON format and you can use it to publish +comments created with convenient offline tools. + +Gerrvim is a free software (see |gerrvim-license|) collection of helper +utilities: + +* Converter (gerrvim2json.pl) from simple plain text human readable and + editable |gerrvim-format| itself to JSON suitable to be send to Gerrit. +* Vim plugin to prepare that Gerrvim file by commenting the source code + added for review. It works together with Fugitive + (http://www.vim.org/scripts/script.php?script_id=2975). +* Simple gerrcommget.sh shell/Perl script that downloads + comments and converts them to Gerrvim file. + +Gerrvim file is intended to be edited by human in any editor, in offline +mode, with the whole everything aggregated in it at once. It is +replacement for JavaScript online Web-based native Gerrite interface +when you need to publish comments for the source code and replies to +other one. + +WORKFLOW *gerrvim-workflow* + +So you received a notify about review request. At first you need to +download that patch (this is only an example): > + % git fetch gerrit changes/92/92/1 + +Then you open this commit in Vim's Fugitive plugin: > + :Gedit FETCH_HEAD + +You can navigate through the files and diffs in it. Read Fugitive +documentation for more information. For example you want to add a +comment about some lines in the patch. Open that file inside the commit, +select required lines, call code commenting (see |gerrvim-usage|), enter +the comments in newly appeared window, close it by pressing . + +Repeat that step to add all the comments. They are aggregated in +temporary Gerrvim file (/tmp/gerrvim.txt by default). + +When you finished with it, you can edit and correct Gerrvim file without +any Fugitive later. Possibly to add a comment for the whole review, not +related to any of the files. + +At last you want to publish all your writings. Use converter to create +JSON from Gerrvim and send it directly to Gerrit. > + % gerrvim2json.pl /tmp/gerrvim.txt | ssh gerrit gerrit review --json + +Soon you may receive notification about someone replied to your +comments. You can use gerrcommget.sh script to retrieve them and +save as a Gerrvim file: > + % gerrcommget.sh 92 1 > /tmp/gerrvim.txt + +Be sure to precoconfigure |gerrvim-config| it and specify URL to your +Gerrit's REST-API, your username and password. + +Edit that Gerrvim file and convert to JSON with sending to the server +again. It has slightly different headers and you comments will be +published as a reply to other ones. + +INSTALLATION *gerrvim-install* + +* Install Fugitive plugin for the Vim +* Install Perl JSON (https://metacpan.org/pod/JSON) and Encode modules +* Copy plugin/gerrvim.vim to ~/.vim/plugin +* Optionally copy that readme to ~/.vim/doc/gerrvim.txt + +CONFIGURATION *gerrvim-config* + +The only option for the Vim plugin is the placement of temporary file +with aggregated comments. By default it is /tmp/gerrvim.txt. You can +override it in your .vimrc: > let g:gerrvim_file = "/another/path.txt" -USAGE *gerrvim* +Edit gerrcommget.sh and specify necessary GERRADDR (Gerrit's +server URL), GERRUSER (your username) and GERRPASS (password) variables. +You can override them anytime with environment variables. + +PLUGIN USAGE *gerrvim-usage* * Open necessary commit using Fugitive (:Gedit) and file inside it * Visually select a bunch of code lines you want to comment @@ -18,11 +96,53 @@ USAGE *gerrvim* * Either press in normal mode, or save buffer and exit * Comment window will be closed, saving your consolidated changes in temporary file -* To wipe out all your comments type :GerrvimClear (or remove that - temporary file) +* To wipe out all your comments either call :GerrvimClear or remove + that temporary file) + +GERRVIM FILE FORMAT *gerrvim-format* + +Gerrvim's file includes blocks of text separated by BEGIN/END lines. > + Some main review message. + It can be multilined. + + -----BEGIN 2c5405c8145e61b738953b4e Makefile 27 29----- + foo: bar + make -C some thing + -----END----- + You must replace make with $(MAKE). + + And I could write it multiline too. + + + -----BEGIN 2c5405c8145e61b738953b4e Makefile 1 2----- + #/usr/bin/make + -----END----- + Remove that. + + -----BEGIN R1a014df3_5b8de330 README 20 22----- + Vasyliy Pupkin: + I am not sure about that corrections. What do you think? + -----END----- + Seems you are right. + +BEGIN line contains: + +* Either commit's hash, or comment's id with "R" prefix. If R-prefixed + comment's id is specified, then you will be replying to it +* Path to the file inside source code tree +* Linenumber where comment begins +* Linenumber where comment ends + +You are capable to comment either range of lines, or the single one. + +Everything between BEGIN and END lines is just for convenience and won't +be published anywhere, it is cut. + +The text between END and next BEGIN line is the comment itself. It can +be multilined. All empty lines at the end are removed. -Copied original text (that is between BEGIN and END line) won't be -published in Gerrit. It exists just for your convenience. +Optional text before the very first BEGIN line will be review's main +message, not related to any file. LICENCE *gerrvim-license* diff --git a/gerrvim2json.pl b/gerrvim2json.pl index b38104f..79566e0 100755 --- a/gerrvim2json.pl +++ b/gerrvim2json.pl @@ -15,78 +15,6 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -=pod - -=head1 DESCRIPTION - -This script converts gerrvim Vim pluging temporary file to JSON suitable -to be published in Gerrit. Input file like this: - - Some main review message. - It can be multilined. - - -----BEGIN 5e5a5d9ae9339c8f2c5405c8145e61b738953b4e Makefile 27 29----- - foo: bar - make -C some thing - -----END----- - You must replace make with $(MAKE). - - And I could write it multiline too. - - - -----BEGIN 5e5a5d9ae9339c8f2c5405c8145e61b738953b4e Makefile 1 2----- - #/usr/bin/make - -----END----- - Remove that. - -is transformed to JSON like this: - - { - "message": "Some main review message.\nIt can be multilined.", - "comments": { - "Makefile": [ - { - "message": "You must replace make with $(MAKE).\n\nAnd I could write it multiline too.", - "range": { - "start_line": "27", - "end_line": "29" - } - }, - { - "message": "Remove that.", - "line": 1 - } - ] - } - } - -=head1 INPUT FORMAT - -Each comment to lines of some file starts with -----BEGIN----- block. -After BEGIN word, four parts are comming (space separated): - -=over 4 - -=item * Commit's hash. SHA1 in hexadecimal - -=item * Path to file inside repository - -=item * Linenumber where comment begins - -=item * Linenumber where comment ends - -=back - -After BEGIN goes optional text that won't be included in JSON at all. As -a rule it is just a copy of code to be commented. It ends with -----END-----. - -Everything between END of one block and BEGIN of another is treated as a -comment to the block above. Empty newlines at the end are removed. -Optional text before the first BEGIN block is treated as overall review -message. - -=cut - use strict; use warnings;