GitHub Pull Requests
Contents
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 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.
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!
Example Dashboard and Pull Request Scanning Workflows
The following 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
This is pull request #6. The change to the code in the pull request was to add an embedded string to the file testpull.java
, namely String anotherunused = "In the bed string";
.
Globalyzer analysis flagged this line as a active Embedded String.
Before merging the code back to master, the developer would typically externalize the string and re-submit the changed code and resource file.
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:
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:
sonar.analysis.mode=preview
- It is imperative this attribute is set to preview to work. If not set, it defaults to publish mode, and could create future issues for analysis on this pull request.
sonar.github.login=
- Your GitHub login name
sonar.github.oauth=
- GitHub oauth is your unique GitHub personal access token: created @ https://github.com/settings/tokens
sonar.github.repository=
- The repository you are working in. If repository link is https://github.com/ursulaLingoport/indexing2, this attribute should be set to
sonar.github.repository=ursulaLingoport/indexing2
- The repository you are working in. If repository link is https://github.com/ursulaLingoport/indexing2, this attribute should be set to
sonar.github.pullRequest=
- The number of the pull request you plan to run an i18n analysis on.
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 base repository 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:
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-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 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.
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 (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
orlite GzProjectDefinition.xml
(if you set an alias)C:\sonar\sonar-runner-2.4-local\bin\sonar-runner
orsonar-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 directoryGlobalyzerScans
. It could be any commands to create that Globalyzer report. The sonar-runner then needs to be executed from above theGlobalyzerScans
directory.
- Note: The command