Difference between revisions of "GitHub Pull Requests"

From Lingoport Wiki
Jump to: navigation, search
(Example of a Pull Request Analyzed with Globalyzer)
(Running the Analysis)
(35 intermediate revisions by the same user not shown)
Line 3: Line 3:
   
 
= Git Pull Requests =
 
= Git Pull Requests =
Files can be committed in a Git branch or directly in Master. When committing files in a branch, pull requests let you know what changes you've pushed to a repository on GitHub. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
+
Files can be committed in a Git branch or directly in Master. When committing files in a branch, pull requests let you know what changes you've made to a repository before they are committed to the repository's master branch. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
  +
  +
= SonarQube GitHub Pull Request Plugin =
  +
The SonarQube GitHub Plugin serves only one purpose: analyse GitHub pull requests in a preview mode, and inlay a summary analysis within the Pull Request's comments. This summary analysis showcases the top Globalyzer and LRM issues detected from scan. The latest version of this plugin is found [https://sonarsource.bintray.com/Distribution/sonar-github-plugin/ here]. Further documentation can be found [http://docs.sonarqube.org/display/PLUG/GitHub+Plugin here].
  +
:: '''Note:''' After downloading the latest version of the plugin, place the <code>sonar-github-plugin.jar</code> file in your <code>.../Dashboard-Server/extensions/plugins</code> directory.
   
 
= Dashboard and Pull Requests =
 
= Dashboard and Pull Requests =
Globalyzer Dashboard is based on SonarQube and leverages that platform's feature. Starting with <b>Lingoport Dashboard 5.1.2</b>, the GitHub Plugin is available. It allows to show Dashboard issues within GitHub as comments of the pull request. Globalyzer and LRM issues can then be detected and shown on the code changes before the pull request is merged with the main (master) branch.
+
Globalyzer Dashboard is based on SonarQube and leverages that platform's feature. Starting with <b>Lingoport Dashboard 5.1.2</b>, the GitHub Plugin is available. It allows to show Dashboard issues within GitHub as comments of the pull request. Globalyzer and LRM issues can then be detected and shown on the code changes before the pull request is merged with the main (master) branch. Therefore this GitHub feature is only to be used on working branches and never on master.
  +
Sonar Scanner is used to push Pull Request issues to GitHub.com and to push issues on the master branch to the Globalyzer Dashboard. '''However the differences between these two workflows is very imperative to the capability of these tools! Within your ''sonar-project.properties'' file, publish mode should only be configured/run on your master branch and preview mode should only be configured/run on a working branch.'''
  +
  +
====Example Dashboard and Pull Request Scanning Workflows====
  +
:::[[File:NewPrScanFlow2.png|caption|This diagram showcases the differences between scanning on a master branch ('''publishing''' to dashboard) and scanning on a pull request ('''previewing''' to GitHub.com).]]
  +
:This diagram showcases the differences between scanning on a master branch ('''publishing''' to dashboard) and scanning on a pull request ('''previewing''' to GitHub.com).
   
 
== Example of a Pull Request Analyzed with Globalyzer ==
 
== Example of a Pull Request Analyzed with Globalyzer ==
   
[[File:GlobalyzerGitHubPullRequest.png]]
+
[[File:PrSummaryAnalysis.png]]
   
This is pull request <b>#6</b>. The change to the code in the pull request was to add an embedded string to the file <code>testpull.java</code>, namely <code>String anotherunused = "In the bed string";</code>.
+
This is pull request <b>#44</b>. The change to the code in the pull request was to add multiple embedded strings and a locale-sensitive method to the files <code>ExampleMain.java</code> & <code>ExamplePanel.java</code>. This pull request is reporting 25 different issues, however since the <code>sonar-project.properties</code> attribute is set to <code>sonar.github.disableInlineComments=true</code>, the top ten issues (sorted by severity, by component, then by line) are put into a summary analysis as a pull request comment.
   
Globalyzer analysis flagged this line as a active Embedded String.
+
Globalyzer analysis flagged these lines as critical issues. Clicking on the link next to the issue number will send the user to the line of code in that respective file.
   
Before merging the code back to master, the developer would typically externalize the string and re-submit the changed code and resource file.
+
Before merging the code back to master, the developer would typically externalize these strings, fix the locale-sensitive method issue, and re-submit the changed code / resource files for further analysis.
   
 
====External Dashboard Link====
 
====External Dashboard Link====
   
 
The GitHub pull request issues also showcase a <code>...</code> link to send the user to their dashboard server as configured in the <code>/sonar-runner-2.5.1/conf/sonar-runner.properties</code> file:
 
The GitHub pull request issues also showcase a <code>...</code> link to send the user to their dashboard server as configured in the <code>/sonar-runner-2.5.1/conf/sonar-runner.properties</code> file:
* For Example: Changing the url attribute to <code>sonar.host.url=http://localhost:9010</code> will redirect the user to the following link to give a more detailed report of this unique issue:
+
* For Example: Changing the url attribute to <code>sonar.host.url=<nowiki>http://localhost:9010</nowiki></code> (your local Globalyzer Dashboard Server) will redirect the user to the following link to give a more detailed report of this unique issue:
   
 
:::::[[File:GitHubPullRequestLink.png]]
 
:::::[[File:GitHubPullRequestLink.png]]
Line 38: Line 47:
 
* <code> sonar.github.pullRequest= </code>
 
* <code> sonar.github.pullRequest= </code>
 
** The number of the pull request you plan to run an i18n analysis on.
 
** The number of the pull request you plan to run an i18n analysis on.
  +
* <code> sonar.github.disableInlineComments= </code>
 
  +
** If set to true (highly recommended), issues will not be reported as inline comments but only in the global analysis summary in sorted order. False by default.
  +
** This Wiki page is based around this attribute being set to '''true'''. [https://github.com/ecrawfordLingoport/LiteDemo/pull/44 Here is an example of a Pull Request when this attribute is set to '''false''' (issues appear as individual inline comments within the pull request).]
   
 
===GitHub Personal Access Token Security===
 
===GitHub Personal Access Token Security===
Since the sonar-project.properties file includes a personal access token (OAuth), this file cannot be pushed to a remote repository. This exposes the users personal access token to the public, and therefore will void the token. If this happens, you should receive an email from GitHub acknowledging the user of the exposure and the token's decommission. In order to avoid this, the user must avoid staging the sonar-project.properties file for commit. In order to do this, you can create a <code>.gitignore</code> file in your base repository directory to ignore all files with the <code>.properties</code> extension. It is recommended to do this in your <code>master</code> branch, so all forked and branched repositories will not face this issue.
+
Since the sonar-project.properties file includes a personal access token (OAuth), this file cannot be pushed to a remote repository. This exposes the users personal access token to the public, and therefore will void the token. If this happens, you should receive an email from GitHub acknowledging the user of the exposure and the token's decommission. In order to avoid this, the user must avoid staging the sonar-project.properties file for commit. In order to do this, you can create a <code>.gitignore</code> file in your repository's root directory to ignore all files with the <code>.properties</code> extension. It is recommended to do this in your <code>master</code> branch, so all forked and branched repositories will not face this issue.
   
 
Here is an example <code>.gitignore</code> file that will prevent this issue from occurring:
 
Here is an example <code>.gitignore</code> file that will prevent this issue from occurring:
Line 70: Line 81:
 
sonar.github.repository=ursulaLingoport/indexing2
 
sonar.github.repository=ursulaLingoport/indexing2
 
sonar.github.pullRequest=6
 
sonar.github.pullRequest=6
  +
sonar.github.disableInlineComments=true
 
</pre>
 
</pre>
 
   
 
===Sonar-Runner and GlobalyzerLite Paths/Aliases===
 
===Sonar-Runner and GlobalyzerLite Paths/Aliases===
Line 77: Line 88:
   
 
====Windows====
 
====Windows====
*Create an alias for GlobalyzerLite (running the doskey command is quick way to create an alias on windows)
+
*Create an alias for GlobalyzerLite (running the doskey command is a quick way to create an alias on windows)
 
**<code>doskey lite=java -jar C:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar</code>
 
**<code>doskey lite=java -jar C:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar</code>
 
*Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command <code>sonar-runner</code>
 
*Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command <code>sonar-runner</code>
Line 87: Line 98:
 
*Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command <code>sonar-runner</code>
 
*Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command <code>sonar-runner</code>
 
**<code>echo 'export PATH=$PATH:/etc/sonar-scanner-2.5.1/bin' >> ~/.bashrc</code>
 
**<code>echo 'export PATH=$PATH:/etc/sonar-scanner-2.5.1/bin' >> ~/.bashrc</code>
  +
  +
  +
===Globalyzer Lite Project Definition File===
  +
In order to successfully scan the project directory for analysis, the <code>ProjectDefinition.xml</code> file needs to be correctly configured in your project's root directory.
  +
:[https://www.globalyzer.com/gzserver/help/referenceLite/project-definition-file-overview.html For help on this setup, click here.]
   
 
== Running the Analysis ==
 
== Running the Analysis ==
Line 96: Line 112:
 
** <code>git commit -am "Commit Message"</code>
 
** <code>git commit -am "Commit Message"</code>
 
** <code>git push origin workingBranchName </code>
 
** <code>git push origin workingBranchName </code>
* Create a pull request (usually your branch --> master)
+
* Create a pull request on GitHub.com (your working branch --> master)
  +
* Make sure <kbd>sonar.github.pullRequest=PullRequest#</kbd> within the project's sonar-project.properties file.
 
* Run a couple of commands:
 
* Run a couple of commands:
** <code>java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml</code>
+
** <code>java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml</code> or <code>lite GzProjectDefinition.xml</code> (if you set an alias)
** <code>C:\sonar\sonar-runner-2.4-local\bin\sonar-runner </code>
+
** <code>C:\sonar\sonar-runner-2.4-local\bin\sonar-runner</code> or <code>sonar-runner</code> (if you added sonar-runner to the machines PATH)
 
* Check the pull request comments on GitHub: The i18n issues found on the code in the pull request will be shown.
 
* Check the pull request comments on GitHub: The i18n issues found on the code in the pull request will be shown.
   
<b>Note</b>: The command <code>java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml</code> is used to create a Globalyzer report under the directory <code>GlobalyzerScans</code>. It could be any commands to create that Globalyzer report. The sonar-runner then needs to be executed from above the <code>GlobalyzerScans</code> directory.
+
:::<b>Note</b>: The command <code>java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml</code> is used to create a Globalyzer report under the directory <code>GlobalyzerScans</code>. It could be any commands to create that Globalyzer report. The sonar-runner then needs to be executed from above the <code>GlobalyzerScans</code> directory.
  +
  +
== Additional Information ==
  +
http://stackoverflow.com/questions/32047585/jenkins-sonar-github-integration

Revision as of 17:53, 4 November 2016

GitHub

GitHub is a Web-based Git repository hosting service. It offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features.

Git Pull Requests

Files can be committed in a Git branch or directly in Master. When committing files in a branch, pull requests let you know what changes you've made to a repository before they are committed to the repository's master branch. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

SonarQube GitHub Pull Request Plugin

The SonarQube GitHub Plugin serves only one purpose: analyse GitHub pull requests in a preview mode, and inlay a summary analysis within the Pull Request's comments. This summary analysis showcases the top Globalyzer and LRM issues detected from scan. The latest version of this plugin is found here. Further documentation can be found here.

Note: After downloading the latest version of the plugin, place the sonar-github-plugin.jar file in your .../Dashboard-Server/extensions/plugins directory.

Dashboard and Pull Requests

Globalyzer Dashboard is based on SonarQube and leverages that platform's feature. Starting with Lingoport Dashboard 5.1.2, the GitHub Plugin is available. It allows to show Dashboard issues within GitHub as comments of the pull request. Globalyzer and LRM issues can then be detected and shown on the code changes before the pull request is merged with the main (master) branch. Therefore this GitHub feature is only to be used on working branches and never on master. Sonar Scanner is used to push Pull Request issues to GitHub.com and to push issues on the master branch to the Globalyzer Dashboard. However the differences between these two workflows is very imperative to the capability of these tools! Within your sonar-project.properties file, publish mode should only be configured/run on your master branch and preview mode should only be configured/run on a working branch.

Example Dashboard and Pull Request Scanning Workflows

This diagram showcases the differences between scanning on a master branch (publishing to dashboard) and scanning on a pull request (previewing to GitHub.com).
This diagram showcases the differences between scanning on a master branch (publishing to dashboard) and scanning on a pull request (previewing to GitHub.com).

Example of a Pull Request Analyzed with Globalyzer

PrSummaryAnalysis.png

This is pull request #44. The change to the code in the pull request was to add multiple embedded strings and a locale-sensitive method to the files ExampleMain.java & ExamplePanel.java. This pull request is reporting 25 different issues, however since the sonar-project.properties attribute is set to sonar.github.disableInlineComments=true, the top ten issues (sorted by severity, by component, then by line) are put into a summary analysis as a pull request comment.

Globalyzer analysis flagged these lines as critical issues. Clicking on the link next to the issue number will send the user to the line of code in that respective file.

Before merging the code back to master, the developer would typically externalize these strings, fix the locale-sensitive method issue, and re-submit the changed code / resource files for further analysis.

External Dashboard Link

The GitHub pull request issues also showcase a ... link to send the user to their dashboard server as configured in the /sonar-runner-2.5.1/conf/sonar-runner.properties file:

  • For Example: Changing the url attribute to sonar.host.url=http://localhost:9010 (your local Globalyzer Dashboard Server) will redirect the user to the following link to give a more detailed report of this unique issue:
GitHubPullRequestLink.png

Pull Request Analysis Configuration

Globalyzer Dashboard uses the SonarQube sonar-project.properties file for configuration. This file should be in your repositories base directory. For the i18n analysis of the pull request, the sonar-project.properties file needs the following attributes:

GitHub Personal Access Token Security

Since the sonar-project.properties file includes a personal access token (OAuth), this file cannot be pushed to a remote repository. This exposes the users personal access token to the public, and therefore will void the token. If this happens, you should receive an email from GitHub acknowledging the user of the exposure and the token's decommission. In order to avoid this, the user must avoid staging the sonar-project.properties file for commit. In order to do this, you can create a .gitignore file in your repository's root directory to ignore all files with the .properties extension. It is recommended to do this in your master branch, so all forked and branched repositories will not face this issue.

Here is an example .gitignore file that will prevent this issue from occurring:

GitIgnore.png

Sample sonar-project.properties file:

For instance, here is a test sonar-project.properties with some properties modified for security reasons:

sonar.projectKey=Lingoport.indexing2:scan
sonar.projectName=Lingoport.indexing2
sonar.projectVersion=5.1
sonar.sources=C:/Users/Joe/Documents/GitHub/indexing2
sonar.importSources=true
sonar.lingoport.project.root=.
sonar.language=lport

#sonar.lingoport.extensions=as,mxml,asp,asax,ascx,ashx,aspx,awk,c,c++,cc,cpp,cxx,h,hpp,hxx,sqc,sqx,qml,cs,dfm,dpk,dpr,pas,java,jsp,jspf,js,perl,pl,pm,plx,inc,php,sql,sqc,sqx,bas,cls,ctl,dob,
dsr,frm,pag,vb,vbs,htm,html,shtml,vm,html5,xml,xsd,xsl,xslt,wsdl,wsdd,rmd,tld,xliff,xul,xhtml,mxml,jspx,xaml,css,cat,resx,msg,po,properties,rc,rc2,strings,json,ts,rxml,rjs,properties 

#
# For the GitHub SonarQube Plugin
#
sonar.analysis.mode=preview
sonar.github.login=ursulaLingoport
sonar.github.oauth=d60bbe9d6d3c7caa995f5119ff2997b26d0ef191
sonar.github.repository=ursulaLingoport/indexing2
sonar.github.pullRequest=6
sonar.github.disableInlineComments=true

Sonar-Runner and GlobalyzerLite Paths/Aliases

Instead of having to call the path of your respective program/script each time (I.E. - java -jar "C:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml), you can create command-line aliases to run these commands quickly and more efficiently (I.E. - lite GzProjectDefinition.xml)

Windows

  • Create an alias for GlobalyzerLite (running the doskey command is a quick way to create an alias on windows)
    • doskey lite=java -jar C:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar
  • Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command sonar-runner
    • set PATH=%PATH%;C:\path\to\sonar-scanner-2.5.1

Unix

  • Create an alias for GlobalyzerLite (this command adds the alias to the end of your .bashrc file)
    • echo 'alias lite="java -jar /destination/to/globalyzer-lite-5.0/globalyzer-lite.jar" ' >> ~/.bashrc
  • Add sonar-runner to your path if you have not already, to allow the scanner to be run within any directory with the simple command sonar-runner
    • echo 'export PATH=$PATH:/etc/sonar-scanner-2.5.1/bin' >> ~/.bashrc


Globalyzer Lite Project Definition File

In order to successfully scan the project directory for analysis, the ProjectDefinition.xml file needs to be correctly configured in your project's root directory.

For help on this setup, click here.

Running the Analysis

  • Checkout code from a branch (not master) or create a new branch
    • git checkout <-b> workingBranchName (use the -b flag to create a new branch)
  • Modify the code in your working branch
  • Add, commit & push the code to the branch (not master)
    • git add .
    • git commit -am "Commit Message"
    • git push origin workingBranchName
  • Create a pull request on GitHub.com (your working branch --> master)
  • Make sure sonar.github.pullRequest=PullRequest# within the project's sonar-project.properties file.
  • Run a couple of commands:
    • java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml or lite GzProjectDefinition.xml (if you set an alias)
    • C:\sonar\sonar-runner-2.4-local\bin\sonar-runner or sonar-runner (if you added sonar-runner to the machines PATH)
  • Check the pull request comments on GitHub: The i18n issues found on the code in the pull request will be shown.
Note: The command java -jar "c:\lingoport\globalyzer-lite-4.8.5\globalyzer-lite.jar" GzProjectDefinition.xml is used to create a Globalyzer report under the directory GlobalyzerScans. It could be any commands to create that Globalyzer report. The sonar-runner then needs to be executed from above the GlobalyzerScans directory.

Additional Information

http://stackoverflow.com/questions/32047585/jenkins-sonar-github-integration