Skip to content

Latest commit

 

History

History
535 lines (387 loc) · 23.5 KB

README.md

File metadata and controls

535 lines (387 loc) · 23.5 KB
Raw

vscode-code-review

All Contributors

Buy Me A Coffee

VSCode Marketplace Open VSX Registry PRs Welcome Open Source Love

This extension allows you to create a code review file you can hand over to a customer.

Features

create review notes

Simply right click somewhere in the opened file and choose the option "Code Review: Add Note". You will be prompted for your note you want to add. A file code-review.csv will be created containing your comments and the file and line references.

The result will look like this:

sha,filename,url,lines,title,comment,priority,additional
"b45d2822d6c87770af520d7e2acc49155f0b4362","/test/a.txt","https://github.com/d-koppenhagen/vscode-code-review/tree/b45d2822d6c87770af520d7e2acc49155f0b4362/test/a.txt","1:2-4:3","foo","this should be refactored","Complexity",1,"see http://foo.bar"
"b45d2822d6c87770af520d7e2acc49155f0b4362","/test/b.txt","https://github.com/d-koppenhagen/vscode-code-review/tree/b45d2822d6c87770af520d7e2acc49155f0b4362/test/b.txt","1:0-1:4|4:0-4:3","bar","wrong format","Best Practices",1,""

The line column indicates an array of selected ranges or cursor positions separated by a | sign. E.g. "1:0-1:4|4:0-4:3" means that the comment is related to the range marked from line 1 position 0 to line 1 position 4 and line 4 position 0 to line 4 position 3.

Demo

After adding a review note, your can directly edit and review it from the source by clicking on the annotation above the referenced lines(s). Parts in the code that are already commented will be decorated by a small underline and by an icon at the end of the referenced code part. You can also explore and edit/view all comments in the comment explorer (see below).

Code Review Comment Explorer - update, view and delete comments

Once you created your first code review comment and the plugin can find the associated review file (by default code-review.csv), a new button will appear in the sidebar. Clicking on this button will open the Code Review Comment Explorer. This explorer shows you all made comments to the related code base. Selecting an entry will open the comment in the webview form, so you can edit and update it. Performing a right-click on an item, will let you delete a comment.

Demo: Code Review Comment Explorer

export created notes as HTML

Once you finished your review and added your notes, you can export the results as an HTML report. Therefore open the VSCode Command Palette (macOS: ⇧+⌘+P, others: ⇧+Ctrl+P) and search for "Code Review":

Code Review: Export as HTML

Default HTML template

When you choose to generate the report using the default template, it will look like this in the end:

Code Review HTML Export: Default Template

You can define a path to a custom template that's used by default when running this command. Check out the Extension Setting 'defaultTemplatePath' for further information.

Custom HTML handlebars template

You can also choose to export the HTML report by using a custom Handlebars template. Once you choose this option, you got prompted to choose the template file (file extension must be either *.hbs, *.handlebars, *.html or *.htm)

Code Review HTML Export: Use a custom Handlebars template

The used structure to fill the template placeholders is an array of ReviewFileExportSection.

Check out the example default template file template.default.hbs, to see how your template should basically look like.

Export created notes as Markdown

In addition to exporting your notes as HTML, you may also export them as Markdown. Just like with the HTML export, you may use the default Markdown template provided or choose your own.

Default Markdown template

Simply open up the VSCode Command Palette and run the Export As Markdown With Default Template command.

You can define a path to a custom template that's used by default when running this command. Check out the Extension Setting 'defaultMarkdownTemplatePath' for further information.

Custom Markdown handlebars template

You can also choose to export the Markdown report by using a custom Handlebars template. Once you choose this option, you got prompted to choose the template file (file extension must be either *.hbs, *.handlebars, *.md, *.mds or *.markdown)

Check out the example default template file template-markdown.default.hbs, to see how your template should basically look like.

Export for Issue Tracking System

export created notes as GitLab importable CSV file

Once you finished your code review, you can export the results to a formatted csv file that's importable into Gitlab issues.

Code Review GitLab importable CSV export

Once exported, you can import the file in the GitLab project

GitLab import CSV file

export created notes as GitHub importable CSV file

You can export the code review results to a formatted CSV file that's importable into GitHub by using github-csv-tools.

Code Review GitLab importable CSV export

export created notes as JIRA importable CSV file

You can also export the notes as a CSV file to import them into your JIRA issue tracking system.

Code Review JIRA importable CSV export

After exporting, you can import the file in your JIRA instance and probably map the props / ignore what you don't need:

JIRA: import issues from a CSV file JIRA: map CSV file props

Extension Settings

The following settings can be adjusted via the configuration file .vscode/settings.json or globally when configuring vscode. The listing below shows the default configuration:

Visual Studio Code - Code Review Extension Settings

code-review.filename

The filename for the *.csv file that stores all comments. By default, "code-review" is used.

{
  "code-review.filename": "my-review-file"
}

code-review.baseUrl

The base-URL is used to build a full link to the file. It will be appended with the git SHA if available followed by the relative path of the file and the selected lines as an anker. This setting is skipped when the setting code-review.customUrl is defined which is more configurable.

{
  "code-review.baseUrl": "https://github.com/foo/bar/blob"
}

This setting would lead into something like this: https://github.com/foo/bar/blob/b0b4...0175/src/file.txt#L12-L19.

code-review.customUrl

The custom URL is used to build a full link to the file. The following placeholders are available:

  • {sha}: insert the SHA ref for the file
  • {file}: insert the file name/path
  • {start}: insert the start of the line selection as an anker
  • {end}: insert the end of the line selection as an anker
{
  "code-review.customUrl": "https://gitlab.com/foo/bar/baz/-/blob/{sha}/src/{file}#L{start}-{end}"
}

This setting would lead into something like this: https://gitlab.com/foo/bar/baz/-/blob/b0b4...0175/src/file.txt#L12-19

code-review.groupBy

This setting is used when generating a report as HTML or Markdown. The comments will be grouped by either:

  • filename: default, group by filename
  • priority: grouping by priorities
  • category: grouping by the used categories
{
  "code-review.groupBy": "category"
}

code-review.categories

Here you can define the categories that will be available for selection when you create comments.

{
  "code-review.categories": [
      "Architecture",
      "Best Practices",
      ...
  ],
}

code-review.reportWithCodeSelection

Define whether to include the code selection(s) in generated reports or not.

{
  "code-review.reportWithCodeSelection": true
}

Attention! The code included in the report will be BASE64 encoded in order to prevent breaking report generation by unescaped characters that will be accidentally interpreted. You can decode this by using the provided Handlebars helper function codeBlock as shown below:

{{#each this as |item|}}
<section>
  {{#each item.lines as |line|}}
  <div>
    <!-- ... -->
    {{#if line.code}}
    <pre><code>{{codeBlock line.code}}</code></pre>
    {{/if}}
    <!-- ... -->
  </div>
  {{/each}}
</section>
{{/each}}

code-review.reportWithPrivateComments

Define whether to include private comments in generated reports or not.

{
  "code-review.reportWithPrivateComments": true
}

code-review.privateCommentIcon

Identifier of the icon to show next to a private comment. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing. A search engine can be found at https://microsoft.github.io/vscode-codicons/dist/codicon.html.

{
  "code-review.privateCommentIcon": "eye-closed"
}

code-review.defaultTemplatePath

The path to a default Handlebars template to be used for HTML default export. The template is used by default when choosing 'Export as HTML with default template' extension command. If not set, the out-of-the-box template provided by this extension is used. The configured value must be the full path to the Handlebars template file.

{
  "code-review.defaultTemplatePath": "/Users/my-user/my-code-review-template.hbs"
}

code-review.defaultMarkdownTemplatePath

The path to a default Handlebars template to be used for Markdown default export. The template is used by default when choosing 'Export as Markdown with default template' extension command.

If not set, the out-of-the-box template provided by this extension is used. The configured value must be the full path to the Handlebars template file.

{
  "code-review.defaultMarkdownTemplatePath": "/Users/my-user/my-code-review-template.hbs"
}

code-review.priorities

Configure the labels that should be used for the priorities. The first label is used when no priority is defined. The subsequent labels are given in ascending priority (max. 3 priority levels). The defaults are listed below:

{
  "code-review.priorities": [
    "none",   // prio not defined
    "low",    // prio value 1 = green traffic light selected
    "medium", // prio value 2 = yellow traffic light selected
    "high"    // prio value 3 = red traffic light selected
  ] // list must contain exact 4 items
}

code-review.gitDirectory

Use this setting when the Git repository is located in another directory than the workspace one. The path can be relative (prefixed with . or ..) or absolute (prefixed with / on Linux/MacOS or {drive}:\ on Windows).

Examples:

  • ./app: for {workspace}/app (Linux/MacOS)

    {
  "code-review.gitDirectory": "./app"
}

  • ../app: for a folder at the same level as the workspace (Linux/MacOS)

    {
  "code-review.gitDirectory": "../app"
}

  • /path/to/my/app: for an absolute path (Linux/MacOS)

    {
  "code-review.gitDirectory": "/path/to/my/app"
}

  • C:\Path\To\My\App: for an absolute path (Windows)

    {
  "code-review.gitDirectory": "C:\\Path\\To\\My\\App"
}

code-review.filterCommentsByCommit

Define whether to view only the comments from the current commit or not.

{
  "code-review.filterCommentsByCommit": true
}

code-review.filterCommentsByFilename

Define whether to view only the comments from the current file or not.

{
  "code-review.filterCommentsByFilename": true
}

code-review.filterCommentsByPriority

Define whether to hide the comments that have green priority.

{
  "code-review.filterCommentsByPriority": true
}

code-review.importBackup

Define whether to backup, the existing comments before importing new ones or not

{
  "code-review.importBackup": true
}

code-review.importConflictMode

Action to automatically take when importing comments already present:

  • empty: always ask.
  • skip: keep the existing comment.
  • overwrite: replace the existing comment with the imported one.
  • clone: keep both the existing and the imported comments.
{
  "code-review.importConflictMode": "clone"
}

code-review.importCloneSuffix

Suffix to append to the title when existing comments are imported in clone mode.

{
  "code-review.importCloneSuffix": "(copy)"
}

code-review.codeSelectionBackgroundColor

Background color used to highlight the code associated to a comment. Must be specified using a hexadecimal representation - with or without the alpha part (#C8C832 or #C8C83226) - or a rgba() definition.

{
  "code-review.codeSelectionBackgroundColor": "#C8C83226"
}
{
  "code-review.codeSelectionBackgroundColor": "rgba(200, 200, 50, 0.15)"
}

Themable colors

codereview.priority.green

Color for comments with priority level 1.

codereview.priority.yellow

Color for comments with priority level 2.

codereview.priority.red

Color for comments with priority level 3.

codereview.code.selection.background

Background color for highlighted code.

Keybindings

To easily add a new comment, you can use the keybinding combination ctrl + ⇧ + n.

The review approach

If you got a customer request for doing a code review you will ideally receive read access to it's github / gitlab repository or similar. To create a code review with a report you should install this extension and go on with the following steps:

Enjoy!

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Nick Dunne
Nick Dunne
💻		 elazarcoh
elazarcoh
💻 🐛		 Michel Caradec
Michel Caradec
💻 🤔 🐛 📖 ⚠️		 Danny Koppenhagen
Danny Koppenhagen
💻 ⚠️ 👀 🚧 🤔 💡 📖 🐛		 Carsten Rösnick-Neugebauer
Carsten Rösnick-Neugebauer
🐛		 brandonchupp
brandonchupp
💻		 inconspicuous-username
inconspicuous-username
🤔
Stefano Guazzotti
Stefano Guazzotti
💻		 Jarmo Puttonen
Jarmo Puttonen
💻

This project follows the all-contributors specification. Contributions of any kind welcome!