From 2f357533a9cad7a90bada110c186f2e8729b192e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Cort=C3=AAs?= Date: Mon, 2 Mar 2020 11:38:51 +0000 Subject: [PATCH] docs: clean up README --- README.md | 297 +++++---------------------------------- docs/authentication.md | 18 +++ docs/commit_detection.md | 35 +++++ docs/installation.md | 177 +++++++++++++++++++++++ 4 files changed, 264 insertions(+), 263 deletions(-) create mode 100644 docs/authentication.md create mode 100644 docs/commit_detection.md create mode 100644 docs/installation.md diff --git a/README.md b/README.md index 8fe7995d..ef7c24f0 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,50 @@ # Codacy Coverage Reporter -[![Codacy Badge](https://api.codacy.com/project/badge/grade/1c524e61cd8640e79b80d406eda8754b)](https://www.codacy.com/app/Codacy/codacy-coverage-reporter) +[![Codacy Badge](https://api.codacy.com/project/badge/Grade/1c524e61cd8640e79b80d406eda8754b)](https://www.codacy.com/gh/codacy/codacy-coverage-reporter?utm_source=github.com&utm_medium=referral&utm_content=codacy/codacy-coverage-reporter&utm_campaign=Badge_Grade) +[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/1c524e61cd8640e79b80d406eda8754b)](https://www.codacy.com/gh/codacy/codacy-coverage-reporter?utm_source=github.com&utm_medium=referral&utm_content=codacy/codacy-coverage-reporter&utm_campaign=Badge_Coverage) [![Build Status](https://circleci.com/gh/codacy/codacy-coverage-reporter.png?style=shield&circle-token=:circle-token)](https://circleci.com/gh/codacy/codacy-coverage-reporter) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.codacy/codacy-coverage-reporter/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.codacy/codacy-coverage-reporter) Multi-language coverage reporter for Codacy https://www.codacy.com -## Requirements - -- Java JRE 8 and higher - ## Setup -Codacy assumes that coverage is previously configured for your project. -The supported coverage formats can be found [here](https://github.com/codacy/coverage-parser). - -1. Set up the project API token. You can find the token in Project -> Settings -> Integrations -> Project API. - -1. Set the API token in your terminal, replacing %Project_Token% with your own token: +1. Copy a *Project API Token*. You can find the token within a repository *Settings* → *Integrations* → *Project API*. +1. Set the *Project API Token* in your terminal, replacing %Project_Token% with your own: ``` export CODACY_PROJECT_TOKEN=%Project_Token% ``` -**As an alternative**, you can use an API Token instead: - -1. Set up the Account API token. You can find the token in Your account -> API tokens +⚠️ **You should keep your API token well protected, as it grants owner permissions to your projects.** -1. Set the API token in your terminal, replacing %API_Token% with your own token +> If you'd like to automate this process for multiple repositories you can [authenticate using an Account API Token](docs/authentication.md). -1. Set your project name in your terminal, replacing %Project_Name% +### Self-hosted -1. Set your username in your terminal, replacing %Username% +To upload coverage to a self-hosted installation of Codacy you need to set your installation URL: ``` -export CODACY_API_TOKEN=%API_Token% -export CODACY_PROJECT_NAME=%Project_Name% -export CODACY_USERNAME=%Username% +export CODACY_API_BASE_URL=:16006 ``` -### Running Codacy Coverage Reporter with a script +Or use the flag: `--codacy-api-base-url :16006`. -Additional requirements: +## Running Codacy Coverage Reporter -- curl +Requirements: bash, curl, glibc. ```bash bash <(curl -Ls https://coverage.codacy.com/get.sh) ``` -If you want to specify a coverage reporter version, use `CODACY_REPORTER_VERSION` environment variable. +> To specify a coverage reporter version, use `CODACY_REPORTER_VERSION` environment variable. You can find all versions in the [Releases tab](https://github.com/codacy/codacy-coverage-reporter/releases). +Using CircleCI? Check out the [codacy/coverage-reporter orb](docs/installation.md#circleci-orb). -#### Supported formats +If the automated script does not cover your use case, [check the manual installation methods](docs/installation.md). + +## Supported formats The following table contains the formats supported and which coverage tools generate them: @@ -66,109 +58,19 @@ The following table contains the formats supported and which coverage tools gene | Ruby | [SimpleCov](https://github.com/colszowka/simplecov) | [Cobertura](https://github.com/dashingrocket/simplecov-cobertura)
[LCOV](https://github.com/fortissimo1997/simplecov-lcov) | cobertura.xml
lcov.info, lcov.dat, *.lcov | | C# | [OpenCover](https://github.com/OpenCover/opencover)
[DotCover CLI](https://www.jetbrains.com/dotcover/) | OpenCover
DotCover-DetailedXML | opencover.xml
dotcover.xml | -You can use this script with any of the listed coverage formats, even if your language or coverage tool of choice is not in the table above. -If your coverage reports are in a different format you can use a format converter, such as -[ReportGenerator](https://danielpalme.github.io/ReportGenerator/), to generate a supported format. - -This command assumes the coverage reports filename follow the name convention. Otherwise, you must define the report's location with the flag `-r`. - -### Running Codacy Coverage Reporter by manually downloading the binary - -#### Linux amd64 - -Download the latest binary and use it to post the coverage to Codacy - -##### Bintray +The reporter assumes the coverage reports filename follow the name convention. Otherwise, you must define the report's location with the flag `-r`. -```bash -LATEST_VERSION="$(curl -Ls https://api.bintray.com/packages/codacy/Binaries/codacy-coverage-reporter/versions/_latest | jq -r .name)" -curl -Ls -o codacy-coverage-reporter "https://dl.bintray.com/codacy/Binaries/${LATEST_VERSION}/codacy-coverage-reporter-linux" -chmod +x codacy-coverage-reporter -./codacy-coverage-reporter report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml -``` - -##### GitHub - -```sh -curl -Ls -o codacy-coverage-reporter "$(curl -Ls https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | contains("codacy-coverage-reporter-linux"))) | .[0].browser_download_url')" -chmod +x codacy-coverage-reporter -./codacy-coverage-reporter report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml -``` - -If you are experiencing segmentation faults uploading the coverage (due to [oracle/graal#624](https://github.com/oracle/graal/issues/624)), do this before running the reporter, as a workaround: - -```sh -echo "$(dig +short api.codacy.com | tail -n1) api.codacy.com" >> /etc/hosts -``` +> If your coverage reports are in a different format you can use a format converter, such as [ReportGenerator](https://danielpalme.github.io/ReportGenerator/), to generate a supported format. -#### Others +### Unsuported Languages -- Linux x86, MacOS, Windows, ... +If your language is not in the list of supported languages, you can still send coverage to Codacy. You can do it by providing the correct `--language` name and then add the `--force-language` flag. -Download the latest jar and use it to post the coverage to Codacy - -##### Bintray - -```sh -LATEST_VERSION="$(curl -Ls https://api.bintray.com/packages/codacy/Binaries/codacy-coverage-reporter/versions/_latest | jq -r .name)" -curl -Ls -o codacy-coverage-reporter-assembly.jar "https://dl.bintray.com/codacy/Binaries/${LATEST_VERSION}/codacy-coverage-reporter-assembly.jar" -java -jar codacy-coverage-reporter-assembly.jar report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml -``` - -##### GitHub - -```sh -curl -LS -o codacy-coverage-reporter-assembly.jar "$(curl -LSs https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | endswith(".jar"))) | .[0].browser_download_url')" -java -jar codacy-coverage-reporter-assembly.jar report -l Java -r jacoco.xml -``` - -### Commit UUID Detection - -Codacy automatically detects the commit UUID from several sources: - -**Providers** - -- Appveyor -- Bitrise -- Buildkite -- Circle CI -- Codefresh -- Codeship -- Docker -- Gitlab -- Greenhouse CI -- Jenkins -- Magnum CI -- Semaphore CI -- Shippable CI -- Solano CI -- TeamCity CI -- Travis CI -- Wercker CI - -**Git directory** - -- If it finds a git directory it will get current commit. - -**Force commit UUID** - -- You can force using a specific commit UUID with: - -``` -codacy-coverage-reporter report -l Java --commit-uuid "mycommituuid" -r coverage.xml -``` - -**Upload coverage** - -Next, simply run the Codacy reporter. It will find the current commit and send all details to your project dashboard: - -``` -codacy-coverage-reporter report -l Java -r coverage.xml -``` +## Commit SHA hash detection -> Note: You should keep your API token well **protected**, as it grants owner permissions to your projects. +Codacy automatically detects a commit SHA hash from CI workflows, the git repository or command line arguments. See [all supported environments](docs/commit_detection.md). -#### Multiple coverage reports for the same language +## Multiple coverage reports for the same language In order to send multiple reports for the same language, you need to upload each report separately with the flag `--partial` and then notify Codacy, after all reports were sent, with the `final` command. @@ -180,151 +82,12 @@ In order to send multiple reports for the same language, you need to upload each If you are sending reports with the partial flag for a certain language you should use it in all reports for that language to ensure the correct calculation of the coverage. -It might also be possible to merge the reports before uploading them to Codacy, since most coverage tools support merge/aggregation, example: http://www.eclemma.org/jacoco/trunk/doc/merge-mojo.html . - -#### Other Languages - -If your language is not in the list of supported languages, you can still send coverage to Codacy. Just provide the correct `--language` name and then add `--force-language` to make sure it is sent. - -### Enterprise - -To send coverage in the enterprise version you should: - -``` -export CODACY_API_BASE_URL=:16006 -``` - -Or use the option `--codacy-api-base-url :16006`. +It might also be possible to merge the reports before uploading them to Codacy, since most coverage tools support merge/aggregation, example: http://www.eclemma.org/jacoco/trunk/doc/merge-mojo.html. ## Other commands -For a complete list of commands and options run: - -``` -java -jar codacy-coverage-reporter--assembly.jar --help -``` - -## Java 6 - -Due to a limitation in Java 6, the plugin is unable to establish a connection to codacy.com. -You can run [this script](https://gist.github.com/mrfyda/51cdf48fa0722593db6a) after the execution to upload the generated report to Codacy. - -## Build from source - -If you are having any issues with your installation, you can also build the coverage reporter from source. - -1. Clone our repository https://github.com/codacy/codacy-coverage-reporter +For a complete list of commands and options: `--help` -2. Run the command `sbt assembly`. This will produce a .jar that you can run in the `codacy-coverage-reporter/target/codacy-coverage-reporter--assembly.jar` - -3. In the project you want to send the coverage, use the jar. Example: - -``` -/java-project$ java -jar ../codacy-coverage-reporter/target/codacy-coverage-reporter--assembly.jar report -l Java -r jacoco.xml -``` - -## Gradle task - -A big shout-out to [tompahoward](https://github.com/tompahoward), you can create a gradle task as suggested in https://github.com/mountain-pass/hyperstate/commit/857ca93e1c8484c14a5e2da9f0434d3daf3328ce - -```gradle -task uploadCoverageToCodacy(type: JavaExec, dependsOn : jacocoTestReport) { - main = "com.codacy.CodacyCoverageReporter" - classpath = configurations.codacy - args = [ - "report", - "-l", - "Java", - "-r", - "${buildDir}/test-results/jacoco/${archivesBaseName}.xml" - ] -} - -task (codacyDepsize) << { -def size = 0; -configurations.codacy.collect { it.length() / (1024 * 1024) }.each { size += it } -println "Total dependencies size: ${Math.round(size * 100) / 100} Mb" - -configurations - .codacy - .sort { -it.length() } - .each { println "${it.name} : ${Math.round(it.length() / (1024) * 100) / 100} kb" } -} - -task (codacyLocs) << { - configurations.codacy.each { - String jarName = it - println jarName - } -} -``` - ---- - -Gradle task by [Mr_ramych](https://github.com/MrRamych). Made up from solution above. - -```gradle -configurations { codacy } -repositories { - jcenter() -} -dependencies { - codacy 'com.codacy:codacy-coverage-reporter:latest.release' -} -task sendCoverageToCodacy(type: JavaExec, dependsOn: jacocoTestReport) { - main = "com.codacy.CodacyCoverageReporter" - classpath = configurations.codacy - args = [ - "report", - "-l", - "Java", - "-r", - "${buildDir}/reports/jacoco/test/jacocoTestReport.xml" - ] -} -``` - -## Community supported alternatives - -### Maven plugin - -Thanks to the amazing job of [halkeye](https://github.com/halkeye) you can now send your coverage to Codacy using a [maven plugin](https://github.com/halkeye/codacy-maven-plugin)! - -Just follow the [instructions on his repository](https://github.com/halkeye/codacy-maven-plugin/blob/master/README.md#usage). - -### Travis CI - -If you want to use codacy with Travis CI and report coverage generated from your tests run in Travis, update your .travis.yml to include the following blocks: - -```yaml -before_install: - - sudo apt-get install jq - - curl -LSs "$(curl -LSs https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | endswith(".jar"))) | .[0].browser_download_url')" -o codacy-coverage-reporter-assembly.jar - -after_success: - - java -jar codacy-coverage-reporter-assembly.jar report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml -``` - -Make sure you have set `CODACY_PROJECT_TOKEN` as an environment variable in your travis job! - -## CircleCI - -If you want to use codacy with Circle CI and report coverage generated from your tests run in CircleCI, you can use our [coverage reporter orb](https://circleci.com/orbs/registry/orb/codacy/coverage-reporter): - -Example: - - jobs: - send-coverage-report: - steps: - - checkout - - "run commands to generate the coverage result" - - coverage-reporter/send_report - workflows: - version: 2 - coverage-example: - jobs: - - send-coverage-report - ## Troubleshooting ### `Failed to upload report: Not Found` @@ -360,6 +123,14 @@ Example codacy-coverage-reporter report -l Java -r api/target/site/jacoco/jacoco.xml --prefix api/src/main/java/ ``` +### `SubstrateSegfaultHandler caught signal 11` + +If you are experiencing segmentation faults uploading the coverage (due to [oracle/graal#624](https://github.com/oracle/graal/issues/624)), do this before running the reporter, as a workaround: + +```sh +echo "$(dig +short api.codacy.com | tail -n1) api.codacy.com" >> /etc/hosts +``` + ## What is Codacy? [Codacy](https://www.codacy.com/) is an Automated Code Review Tool that monitors your technical debt, helps you improve your code quality, teaches best practices to your developers, and helps you save time in Code Reviews. diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 00000000..c3facd34 --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,18 @@ +# Authentication + +## Authenticating using an Account API token + +If you'd like to automate uploading coverage for multiple repositories you can authenticate using an Account API Token: + +1. Create an Account API token on Codacy. You can find the token in *Your account* → *API tokens* +1. Set the API token in your terminal, replacing *%API_Token%* with your own token +1. Set your repository name in your terminal, replacing *%Repo_Name%* +1. Set your username in your terminal, replacing *%Username%* + +``` +export CODACY_API_TOKEN=%API_Token% +export CODACY_PROJECT_NAME=%Repo_Name% +export CODACY_USERNAME=%Username% +``` + +⚠️ **You should keep your API token well protected, as it grants owner permissions to your projects.** diff --git a/docs/commit_detection.md b/docs/commit_detection.md new file mode 100644 index 00000000..17661913 --- /dev/null +++ b/docs/commit_detection.md @@ -0,0 +1,35 @@ +# Commit SHA hash detection + +Codacy automatically detects a commit SHA hash from several sources in the following order: + +**CI providers** + +- Appveyor +- Bitrise +- Buildkite +- Circle CI +- Codefresh +- Codeship +- Docker +- Gitlab +- Greenhouse CI +- Jenkins +- Magnum CI +- Semaphore CI +- Shippable CI +- Solano CI +- TeamCity CI +- Travis CI +- Wercker CI + +**Git repository directory** + +- If it finds a git directory it will get current commit. + +**Force commit SHA hash** + +- You can force using a specific commit SHA hash with: + +``` +codacy-coverage-reporter report -l Java --commit-uuid "my_commit_hash" -r coverage.xml +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..d8fe4a03 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,177 @@ +# Installation + +## Automatic script + +Requirements: bash, curl, glibc. + +```bash +bash <(curl -Ls https://coverage.codacy.com/get.sh) +``` + +To specify a coverage reporter version, use `CODACY_REPORTER_VERSION` environment variable. + +## CircleCI orb + +If you want to use Codacy with CircleCI and report coverage generated from your tests ran in CircleCI, you can use our [coverage reporter orb](https://circleci.com/orbs/registry/orb/codacy/coverage-reporter): + +Example: + + jobs: + send-coverage-report: + steps: + - checkout + - "run commands to generate the coverage result" + - coverage-reporter/send_report + workflows: + version: 2 + coverage-example: + jobs: + - send-coverage-report + +## Community supported alternatives + +### Maven plugin + +Thanks to the amazing job of [halkeye](https://github.com/halkeye) you can now send your coverage to Codacy using a [maven plugin](https://github.com/halkeye/codacy-maven-plugin)! + +Just follow the [instructions on his repository](https://github.com/halkeye/codacy-maven-plugin/blob/master/README.md#usage). + +### Travis CI + +If you want to use codacy with Travis CI and report coverage generated from your tests run in Travis, update your .travis.yml to include the following blocks: + +```yaml +before_install: + - sudo apt-get install jq + - curl -LSs "$(curl -LSs https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | endswith(".jar"))) | .[0].browser_download_url')" -o codacy-coverage-reporter-assembly.jar + +after_success: + - java -jar codacy-coverage-reporter-assembly.jar report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml +``` + +Make sure you have set `CODACY_PROJECT_TOKEN` as an environment variable in your travis job! + +### Gradle task + +A big shout-out to [tompahoward](https://github.com/tompahoward), you can create a gradle task as suggested in https://github.com/mountain-pass/hyperstate/commit/857ca93e1c8484c14a5e2da9f0434d3daf3328ce + +```gradle +task uploadCoverageToCodacy(type: JavaExec, dependsOn : jacocoTestReport) { + main = "com.codacy.CodacyCoverageReporter" + classpath = configurations.codacy + args = [ + "report", + "-l", + "Java", + "-r", + "${buildDir}/test-results/jacoco/${archivesBaseName}.xml" + ] +} + +task (codacyDepsize) << { +def size = 0; +configurations.codacy.collect { it.length() / (1024 * 1024) }.each { size += it } +println "Total dependencies size: ${Math.round(size * 100) / 100} Mb" + +configurations + .codacy + .sort { -it.length() } + .each { println "${it.name} : ${Math.round(it.length() / (1024) * 100) / 100} kb" } +} + +task (codacyLocs) << { + configurations.codacy.each { + String jarName = it + println jarName + } +} +``` + +--- + +Gradle task by [Mr_ramych](https://github.com/MrRamych). Made up from solution above. + +```gradle +configurations { codacy } +repositories { + jcenter() +} +dependencies { + codacy 'com.codacy:codacy-coverage-reporter:latest.release' +} +task sendCoverageToCodacy(type: JavaExec, dependsOn: jacocoTestReport) { + main = "com.codacy.CodacyCoverageReporter" + classpath = configurations.codacy + args = [ + "report", + "-l", + "Java", + "-r", + "${buildDir}/reports/jacoco/test/jacocoTestReport.xml" + ] +} +``` + +## Manually downloading the native binary + +### Linux amd64 + +Download the latest binary and use it to post the coverage to Codacy + +#### Bintray + +```bash +LATEST_VERSION="$(curl -Ls https://api.bintray.com/packages/codacy/Binaries/codacy-coverage-reporter/versions/_latest | jq -r .name)" +curl -Ls -o codacy-coverage-reporter "https://dl.bintray.com/codacy/Binaries/${LATEST_VERSION}/codacy-coverage-reporter-linux" +chmod +x codacy-coverage-reporter +./codacy-coverage-reporter report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml +``` + +#### GitHub + +```sh +curl -Ls -o codacy-coverage-reporter "$(curl -Ls https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | contains("codacy-coverage-reporter-linux"))) | .[0].browser_download_url')" +chmod +x codacy-coverage-reporter +./codacy-coverage-reporter report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml +``` + +If you are experiencing segmentation faults uploading the coverage (due to [oracle/graal#624](https://github.com/oracle/graal/issues/624)), do this before running the reporter, as a workaround: + +```sh +echo "$(dig +short api.codacy.com | tail -n1) api.codacy.com" >> /etc/hosts +``` + +## Manually downloading the Java binary + +- Linux x86, MacOS, Windows, ... + +Download the latest jar and use it to post the coverage to Codacy + +#### Bintray + +```sh +LATEST_VERSION="$(curl -Ls https://api.bintray.com/packages/codacy/Binaries/codacy-coverage-reporter/versions/_latest | jq -r .name)" +curl -Ls -o codacy-coverage-reporter-assembly.jar "https://dl.bintray.com/codacy/Binaries/${LATEST_VERSION}/codacy-coverage-reporter-assembly.jar" +java -jar codacy-coverage-reporter-assembly.jar report -l Java -r build/reports/jacoco/test/jacocoTestReport.xml +``` + +#### GitHub + +```sh +curl -LS -o codacy-coverage-reporter-assembly.jar "$(curl -LSs https://api.github.com/repos/codacy/codacy-coverage-reporter/releases/latest | jq -r '.assets | map({name, browser_download_url} | select(.name | endswith(".jar"))) | .[0].browser_download_url')" +java -jar codacy-coverage-reporter-assembly.jar report -l Java -r jacoco.xml +``` + +## Build from source + +If you are having any issues with your installation, you can also build the coverage reporter from source. + +1. Clone our repository https://github.com/codacy/codacy-coverage-reporter + +2. Run the command `sbt assembly`. This will produce a .jar that you can run in the `codacy-coverage-reporter/target/codacy-coverage-reporter--assembly.jar` + +3. In the project you want to send the coverage, use the jar. Example: + +``` +/java-project$ java -jar ../codacy-coverage-reporter/target/codacy-coverage-reporter--assembly.jar report -l Java -r jacoco.xml +```