From 3965e0f43f7875331e57d510021912365b2e1160 Mon Sep 17 00:00:00 2001 From: Nick Merwin Date: Wed, 7 Aug 2019 09:08:08 -0700 Subject: [PATCH] readme / license / contributing updates --- CONTRIBUTING.md | 17 ++++++++++++ LICENSE => LICENSE.md | 4 +-- README.md | 64 +++++++++++++++++++++++++++++++------------ 3 files changed, 66 insertions(+), 19 deletions(-) create mode 100644 CONTRIBUTING.md rename LICENSE => LICENSE.md (95%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e04f3a35 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,17 @@ +## How to contribute to the Coveralls Github Action + +#### **Did you find a bug?** + +* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/coverallsapp/github-action/issues). + +* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/coverallsapp/github-action/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring. + +#### **Did you write a patch that fixes a bug?** + +* Open a new GitHub pull request with the patch. + +* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. + +Thanks! + +- Coveralls diff --git a/LICENSE b/LICENSE.md similarity index 95% rename from LICENSE rename to LICENSE.md index c30833ef..c7d8046e 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,6 +1,6 @@ -MIT License +# MIT License -Copyright (c) 2019 Nick Merwin +## Copyright (c) 2019 Nick Merwin Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 28f82b45..a451a790 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,65 @@ -# Coveralls Github Action +# Coveralls GitHub Action -This Github Action posts your test suite's LCOV coverage data to [coveralls.io](https://coveralls.io) for analysis, change tracking, and notifications. You don't need to add the repo to Coveralls first, it will be created when receiving the post. +This GitHub Action posts your test suite's LCOV coverage data to [coveralls.io](https://coveralls.io) for analysis, change tracking, and notifications. You don't need to add the repo to Coveralls first, it will be created when receiving the post. When running on "pull_request" events, a comment will be added to the PR with details about how coverage will be affected if merged. ## Usage -This step needs to run after your test suite has outputted an LCOV file. Most major test runners can be configured to do so; if you're using Node, see more info [here](https://github.com/nickmerwin/node-coveralls). +The action's step needs to run after your test suite has outputted an LCOV file. Most major test runners can be configured to do so; if you're using Node, see more info [here](https://github.com/nickmerwin/node-coveralls). -The `github-token` input is required so that Coveralls can verify the data on the repo and create a new check based on the coverage results. +### Inputs: + +* `github-token` _(required)_ Must be in form `github-token: ${{ secrets.github_token }}`; Coveralls uses this token to verify the posted coverage data on the repo and create a new check based on the results. +* `path-to-lcov` _(optional), default: './covrerage/lcov.info')_ Local path to the lcov output file produced by your test suite. An error will be thrown if the file can't be found. +* `parallel` _(optional)_ Set to true for parallel (or matrix) based steps, where multiple posts to Coveralls will be performed in the check. +* `parallel-finished` _(optional)_ Set to true in the last job, after the other parallel jobs steps have completed, this will send a webhook to Coveralls to set the build complete. +* `coveralls-endpoint` _(optional)_ Hostname and protocol: `https://`; Specifies a [Coveralls Enterprise](https://enterprise.coveralls.io) hostname. + +### Outputs: + +* `coveralls-api-response`: JSON response from the Coveralls API with a status code and url for the Job on Coveralls. ### Standard Example: +* This example assumes you're building a Node project using the command `make test-coverage`, demo here: [nickmerwin/node-coveralls](https://github.com/nickmerwin/node-coveralls) + ```yaml -- name: Coveralls - uses: coverallsapp/github-action - with: - github-token: ${{ secrets.github_token }} - path-to-lcov: ./coverage/lcov.info # optional (default value) -``` + on: ["push","pull_request"] + + name: Test Coveralls -If `path-to-lcov` is omitted, "./coverage/lcov.info" will be used by default. An error will be thrown if the file is missing. + jobs: + + build: + name: Build + runs-on: ubuntu-latest + steps: + + - uses: actions/checkout@master + + - name: Use Node.js 10.x + uses: actions/setup-node@master + with: + version: 10.x + + - name: npm install, make test-coverage + run: | + npm install + make test-coverage + + - name: Coveralls + uses: coverallsapp/github-action + with: + github-token: ${{ secrets.github_token }} +``` ### Complete Parallel Job Example: ```yaml on: ["push","pull_request"] - name: Test Coveralls + name: Test Coveralls Parallel jobs: @@ -62,14 +94,12 @@ If `path-to-lcov` is omitted, "./coverage/lcov.info" will be used by default. An parallel-finished: true ``` -The "Coveralls Finished" step needs to run after all other steps have completed. - -For [Coveralls Enterprise](https://enterprise.coveralls.io) usage, include the input `coveralls-endpoint: https://`. +The "Coveralls Finished" step needs to run after all other steps have completed; it will let Coveralls know that all jobs in the build are done and aggregate coverage calculation can be calculated and notifications sent. ## Demo _gif placeholder_ -## License +## [MIT License](LICENSE.md) -[MIT License](LICENSE) +## [Contributing](CONTRIBUTING.md)