feat: show github-annotation format

[goatwu1993]

Implement GitHub Anntation format
https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-a-notice-message

motivation: use this package in GitHub action and warn uncovered code

command:

pycobertura show --format github-annotation tests/cobertura.xml

::error file=search/BinarySearch.java,line=24,endLine=24,title=pycobertura::not covered
::error file=search/LinearSearch.java,line=19,endLine=24,title=pycobertura::not covered

[aconrad]

@goatwu1993 thanks for this! Can you paste a few example outputs in the PR description?

[goatwu1993]

@aconrad I have updated the description. Not sure if that's what you wanted though.

I opened a repo and a PR for testing/demo usage.

PR:

https://github.com/goatwu1993/pycobertura-test/pull/4/files

Screenshot:

p.s: Big thanks to this repo. I use it on a daily basis for work projects.

[aconrad]

This is great, thanks! Could you write a paragraph in the README about this feature? Explain how it works with examples, screenshots, and how to submit the generated report to Github? Can you also add a note under CHANGES file under the Unreleased paragraph? Please follow the formatting of other release notes. Thanks!

[goatwu1993]

@aconrad would you prefer

1. pycobertura show --format github tests/cobertura.xml
   or
2. pycobertura show --format github-annotation tests/cobertura.xml

[aconrad]

@aconrad would you prefer

1. pycobertura show --format github tests/cobertura.xml
   or
2. pycobertura show --format github-annotation tests/cobertura.xml

The second works better for the long term. It's more explicit/self-explanatory. Thanks for asking!

[goatwu1993]

@aconrad ready for review again

[aconrad]

The PR looks great, @goatwu1993! I left a comment about the annotation error level being too intrusive. I could either go with a less intrusive level message or make it required so it puts the annotation level decision on the user.

[goatwu1993]

@aconrad Should I implement the options in CLI as well?

[aconrad]

@aconrad Should I implement the options in CLI as well?

I was just looking over that actually. Yeah, we should be able to pass options via the CLI.

pycobertura show --format github-annotations --title=foo --message="please cover" --level=error

But I'm also wondering how to make options specific to an argument. title, message, and level would only apply when format == "github-annotations". We'd have to read the Click documentation to see if it supports that. I don't believe we have an existing use-case for it.

[goatwu1993]

hmm, need more time to read some click document...

[aconrad]

hmm, need more time to read some click document...

We might just need to accept all options regardless of the format, sift through them, and direct the expected ones to the formatters.

[goatwu1993]

@aconrad 3cdc956
option is named annotation-xxx instead of github-annotation-xxx cause other CI may use this options as well (e.g, Azure devops has similar mechanism as well)

[aconrad]

@aconrad 3cdc956 option is named annotation-xxx instead of github-annotation-xxx cause other CI may use this options as well (e.g, Azure devops has similar mechanism as well)

Thanks. I'm not sure I understand. Are you saying that the options --github-annotation-xxx provided to pycobertura can cause conflicts in other CI environments? How so? Can you point me to some docs? I would rather not have pycobertura's design decisions be driven by unrelated 3rd party tools, if possible.

[goatwu1993]

no. I'm just saying these options may be not specific to GitHub Annotation reporter. There are numerous log format and some may take use of these options as well.

[aconrad]

Thank you for your work on this PR, much appreciated!

[aconrad]

Released in v3.1.0