The jSparrow GitHub App is now available as a free beta version!
Check it out at GitHub
The jSparrow GitHub App (JGA) is the integration of jSparrow's refactorings as part of a GitHub app.
It is a continuous integration tool, integrated in your build pipeline and used to apply automatic refactorings. The JGA supplies similar rules as the jSparrow Eclipse plugin, but works without user input and is started automatically on every creation of a pull request.
jSparrow automates by..
- ..taking care of formatting and minimizing code smells
- ..transforming old language constructs to new language constructs
- ..using more efficient constructs thus improving performance
The idea to develop jSparrow for GitHub was to create a tool that improves the code quality automatically during the review process. Whenever a developer using jSparrow creates a pull request, jSparrow is started and a commit to the pull request with code improvement is created automatically. If the reviewer confirms the pull request, the modifications jSparrow is proposing are merged into the branch.
Why GitHub App
Apps on GitHub allow you to automate and improve your workflow. GitHub Apps are first-class actors within GitHub. A GitHub App acts on its own behalf, taking actions via the API directly using its own identity.
The jSparrow GitHub App can be installed directly on organizations and user accounts and granted access to specific repositories. This means, when you set up your GitHub App, you can select the repositories you want it to have access to. For example, if you set up the JGA on the octocat repository, it will write only to the octocat repository. To install a GitHub App in an organization account, you must be an organization owner, or have an admin permissions in a repository.
You can install apps from the GitHub Marketplace to use in your personal account or in your organization. To install the jSparrow GitHub App, please follow these simple steps:
- Open the provided link for the beta version in your browser.
- Click on the Install button.
- Choose the location for the installation. Decide and select whether you want to install the app on your personal account, or as an organization account.
- The app requires access to repositories. You have to decide whether to grant the app access to all of your repositories, or just to certain repositories, then select
Only selected repositoriesaccordingly.
- Review the app's access permissions, then click Install.
- Maven project
- Maven 2.2.1 or later
How to use once it is installed
- Create a pull request to GitHub
- Wait until jSparrow finishes and pushes back changes
- Review the results
Rule selection and configuration
To configure which rules should be applied, use the configuration file (
jsparrow.yml). Place this file in your project's root directory.
The child projects will inherit the parent's configuration, unless another
jsparrow.yml is placed in their base directory. If the configuration file is not present and no configuration is inherited from parents, the JMP will use the default configuration. If the configuration file has errors, an exception will be thrown and the JMP will terminate.
jsparrow.yml file consists of three optional sections.
The first section contains the profiles definition.
To define a profile you should specify its name, the list of rules included in the profile and their configuration if any applies (e.g., configuration for LoggerRule and RenamingRule).
Any number of profiles can be defined. The profile to be used for refactoring should be designated with the
The second section contains a list of rules which will be used for refactoring if no profile is designated as
Similarly as in profile definition, the list of rules can be followed by the rule configuration if any is required.
The third section under
excludes node consists of the modules, packages and classes that shall not be refactored by JMP. If no
excludes are defined, JMP will refactor the entire main resources of the project.
This section will only be recognized in the
yml file in the root project, i.e., in any
yml file placed in child projects the
excludes section will be discarded.
The following is an example of a
jsparrow.yml configuration file:
# Specify one of the profiles declared below as the selected profile. # If the selectedProfile is not specified the rules in the “rules:” section # will be applied selectedProfile: profile1 # define profiles here profiles: - name: profile1 rules: - TryWithResource - MultiCatch - FieldRenaming - StandardLogger # The configuration for LoggerRule and RenamingRule can be placed together # with the profile in which the rules are included. If the configuration # within the profile is missing, then the default values are used. The # following is a configuration sample with default values loggerRule: systemOutReplaceOption: INFO systemErrReplaceOption: ERROR printStacktraceReplaceOption: ERROR systemOutPrintExceptionReplaceOption: INFO systemErrPrintExceptionReplaceOption: ERROR addMissingLoggingStatement: ERROR attachExceptionObject: true renamingRule: fieldTypes: - private - protected - package-protected - public underscoreReplacementOption: Upper dollarReplacementOption: Leave # The rules in this section will be executed, if no profile has been # specified as selectedProfile or via maven. To deactivate rules, they can be # commented with the #-sign. The configuration for RenamingRule and LoggerRule # in this section can be done the same way as in the configuration # in profiles, under the rules section. rules: - TryWithResource - MultiCatch - FieldRenaming - StandardLogger loggerRule: systemOutReplaceOption: INFO systemErrReplaceOption: ERROR printStacktraceReplaceOption: ERROR systemOutPrintExceptionReplaceOption: INFO systemErrPrintExceptionReplaceOption: ERROR addMissingLoggingStatement: ERROR attachExceptionObject: true renamingRule: fieldTypes: - private - protected - package-protected - public underscoreReplacementOption: Upper dollarReplacementOption: Leave # Define modules, classes and packages that you don't want to apply refactoring # to. Excluded modules can only be defined on the parent project and those modules # are then entirely ignored. If the module project has it's own yml file, it # overrides the entire configuration inherited from the yml configuration of # the parent project, unless it is an excluded module. excludes: excludeModules: - eu.jsparrow.core excludePackages: - eu.jsparrow.core - eu.jsparrow.core.rule excludeClasses: - eu.jsparrow.core.Activator.java
Any configuration options in the YAML file are case sensitive and require precise indentation.