Update readme with consumers guide and features

README.md

@@ -3,12 +3,51 @@
 [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://issues.jenkins-ci.org/issues/?jql=component%20%3D%20checks-api-plugin)
 [![Jenkins](https://ci.jenkins.io/job/Plugins/job/checks-api-plugin/job/master/badge/icon?subject=Jenkins%20CI)](https://ci.jenkins.io/job/Plugins/job/checks-api-plugin/job/master/)
 [![GitHub Actions](https://github.com/jenkinsci/checks-api-plugin/workflows/CI/badge.svg?branch=master)](https://github.com/jenkinsci/checks-api-plugin/actions)
+[![codecov](https://codecov.io/gh/jenkinsci/checks-api-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/jenkinsci/checks-api-plugin)
 
+Inspired by the [GitHub Checks API](https://docs.github.com/en/rest/reference/checks#runs), this plugin aims to provide a general API to allow Jenkins plugins publishing checks (or reports) to remote source code management (SCM) platforms (e.g. GitHub, GitLab, BitBucket, etc.).
 
-This a [Google Summer of Code](https://summerofcode.withgoogle.com/) project for [Jenkins Organization](https://www.jenkins.io/), it is still under development.
+By consuming this API, other plugins can publish check with customized parameters for a Jenkins build, such as status, summary, warnings, code annotations, or even images.
+Implementations of this API decide on how to make use of these parameters and where to publish the checks.
 
-## Useful links:
-* [Project Idea](https://www.jenkins.io/projects/gsoc/2020/project-ideas/github-checks/)
-* [Project Design](https://docs.google.com/document/d/1hVQTd9jKw0sx8JQR8KjbM-7lWW84e2vFjmmkzBpBbSk/edit?usp=sharing)
-* [Meeting Notes](https://docs.google.com/document/d/1TZLmu3nBPbwUjzLVYGnV_YtYvmzxzw6A4eEVYpbmi3Y/edit?usp=sharing)
+Known consumers:
+* [Warnings Next Generation Plugin](https://plugins.jenkins.io/warnings-ng)
+* [Code Coverage API Plugin](https://plugins.jenkins.io/code-coverage-api)
 
+Implementations:
+* [GitHub Checks Plugin](https://plugins.jenkins.io/github-checks)
+
+This plugin, along with it's [GitHub implementation](https://plugins.jenkins.io/github-checks), has been installed on [ci.jenkins.io](https://ci.jenkins.io/Plugins) to help maintain over 1500 Jenkins plugins. You can take a look at the [action](https://github.com/jenkinsci/checks-api-plugin/runs/1025532156) for this repository or other plugin repositories under [Jenkins organization](https://github.com/jenkinsci) for the results.
+
+## Embedded Features
+
+### Build Status Check
+
+![GitHub Status](docs/images/github-status.png)
+
+By listening to the Jenkins builds, this plugin will automatically publish statuses (pending, in progress, and completed) to different SCM platforms based on the remote repository the build is using.
+
+### Pipeline Usage
+
+Instead of depending on consumers plugins, the users can publish their checks directly in the pipeline script:
+
+```
+publishChecks name: 'example', title: 'Pipeline Check', summary: 'check through pipeline', text: 'you can publish checks in pipeline script', detailsURL: 'https://github.com/jenkinsci/checks-api-plugin#pipeline-usage'
+```
+
+## Guides
+
+- [Consumers Guide](docs/consumers-guide.md)
+
+## Contributing
+
+Refer to our [contribution guidelines](https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md)
+
+## Acknowledgements
+
+This plugin was started as a [Google Summer of Code 2020 project](https://summerofcode.withgoogle.com/projects/#5139745388101632), special thanks to the support from [Jenkins GSoC SIG](https://www.jenkins.io/sigs/gsoc/) and the entire community.
+
+
+## LICENSE
+
+Licensed under MIT, see [LICENSE](LICENSE)

docs/consumers-guide.md

@@ -0,0 +1,44 @@
+
+## Consumers Guide
+
+### A Simple Example
+
+Imagine that you want to publish a check with some details of a Jenkins build. 
+
+You need to first construct a `ChecksDetails` object:
+
+```
+ChecksDetails details = new ChecksDetailsBuilder()
+        .withName("Jenkins CI")
+        .withStatus(ChecksStatus.COMPLETED)
+        .withConclusion(ChecksConclusion.SUCCESS)
+        .withDetailsURL(DisplayURLProvider.get().getRunURL(run))
+        .withCompletedAt(LocalDateTime.now(ZoneOffset.UTC))
+        .build();
+```
+
+Then you can create a publisher based on a Jenkins `Run` to publish the check you just constructed:
+
+```
+ChecksPublisher publisher = ChecksPublisher.fromRun(run);
+publisher.publish(details);
+```
+
+The publisher returned is based on the implementations you installed on your Jenkins instance.
+
+### Checks Parameters
+
+The checks are highly customized by consumers due to a number of optional parameters provided.
+
+Consumers can set these parameters through the checks models:
+
+- `ChecksDetails`: the top-level model of a check, including all other models and some basic parameters like status and conclusion
+- `ChecksOutput`: the output of a check, providing some displayed details like title, summary, URL, and code annotations
+- `ChecksAnnotation`: a code annotation of a check, providing a specific comment for one or multiple lines of code;
+- `ChecksImage`: an image of a check, providing an intuitive graph for the build like issues trend, coverage chart, must be a public URL that SCM platforms can fetch from
+- `ChecksAction`: an action of a check, providing further actions to be performed by users, like rerun a Jenkins build
+
+### Checks Publishers
+
+The publishers are created through the static factory method (`fromRun` or `fromJob`) of `ChecksPublisherFactory`.
+The factory will iterate all available implementations of the `ChecksPublisher` in order to find the suitable publisher for the Jenkins `Run` or `Job`.