Permalink
Browse files

First draft

Using documentation-driven development, author a README, DEVELOPERS file, and
man-pages for the proposed operation of the reporter.
  • Loading branch information...
pbrisbin committed Feb 26, 2017
1 parent 4963c84 commit 9a7b80478ff12ff05a5d1f9be1cb070803891881
@@ -0,0 +1,2 @@
man/*
!man/*.md
@@ -0,0 +1,77 @@
## Viewing Documentation Locally

```console
make all
man man/cc-test-reporter.1
```

## Implementation Notes

The following are behaviors or details about the ruby-test-reporter that may or
may not need to be preserved in the new reporter -- I'm hoping not.

- Token in Payload not HTTP header [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/formatter.rb#L66)
- Custom SSL CA [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L97)
- `/test_reports/batch`? [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L19)
- Gzip [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L58)

## Coverage Payload

This is the payload currently expected by `codeclimate.com/test_reports`.

*TODO*: remove keys not actually used by our system.

```json
{
ci_service: {
branch:,
build_identifier:,
build_url:,
commit_sha:,
committed_at:,
name:,
pull_request:,
worker_id:
},
covered_percent:,
covered_strength:,
environment: {
gem_version:,
pwd:,
rails_root:,
simplecov_root:
},
git: {
branch:,
committed_at:,
head:
},
line_counts: {
covered:,
missed:,
total:
},
//partial:,
//repo_token:,
run_at:,
source_files: [
{
blob_id:,
coverage: [
// hit count, or null for missed
...,
...,
...,
],
covered_percent:,
covered_strength:,
line_counts: {
covered:,
missed:,
total:
},
name: name
}
]
}
```
18 LICENSE
@@ -0,0 +1,18 @@
Copyright 2017 Code Climate <hello@codeclimate.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,8 @@
PANDOC = $(shell which pandoc)
MAN_FILES = $(wildcard man/*.md)
MAN_PAGES = $(patsubst man/%.md,man/%,$(MAN_FILES))

man/%: man/%.md
$(PANDOC) -s -t man $< -o $@

all: $(MAN_PAGES)
@@ -0,0 +1,39 @@
# cc-test-reporter

TODO: details

## Installation

```
curl -L https://codeclimate.s3.amazonaws.com/test-reporter/test-reporter-latest > ./cc-test-reporter
chmod +x ./cc-test-reporter
sudo mv ./cc-test-reporter /usr/local/bin # anywhere in $PATH
```

## Usage

See the [man-pages][man/].

## Client-Side Aggregation (i.e Parallel Test Coverage)

TODO: describe further

1. After each test:

```
eval $(cc-test-reporter env)
cc-test-reporter format-coverage --out "coverage/codeclimate.$N.json"
aws s3 sync coverage/ "s3://my-bucket/coverage/$GIT_COMMIT_SHA"
```

1. After all tests:

```
eval $(cc-test-reporter env)
aws s3 sync "s3://my-bucket/coverage/$GIT_COMMIT_SHA" coverage/
cc-test-reporter upload-coverage
```

## Copyright

See the [LICENSE][].
@@ -0,0 +1,32 @@
% CC-TEST-REPORTER-COVERAGE(1) User Manuals
% Code Climate <hello@codeclimate.com>
% February 2017

# PROLOG

This is a sub-command of **cc-test-reporter**(1).

# SYNOPSIS

**cc-test-reporter-coverage**

# DESCRIPTION

Format and upload coverage information from supported sources to Code Climate
servers.

This is roughly equivalent to:

eval $(cc-test-reporter env)
cc-test-reporter format-coverage
cc-test-reporter upload-coverage

# ENVIRONMENT VARIABLES

*CC_TEST_REPORTER_TOKEN*

# SEE ALSO

**cc-test-reporter-env**(1),
**cc-test-reporter-format-coverage**(1), and
**cc-test-reporter-upload-coverage**(1).
@@ -0,0 +1,111 @@
% CC-TEST-REPORTER-ENV(1) User Manuals
% Code Climate <hello@codeclimate.com>
% February 2017

# PROLOG

This is a sub-command of **cc-test-reporter**(1).

# SYNOPSIS

**cc-test-reporter-env**

# DESCRIPTION

Infer and output information about the environment the reporter is running in.

# EXAMPLE OUTPUT

The output is formatted for use with **eval**(1):

GIT_BRANCH=master
GIT_COMMIT_SHA=594a20638eb9a758e2481c9ad2bdae121a1e03ed
GIT_COMMITTED_AT=1488138087
CI_NAME=circle-ci
CI_BUILD_ID=7
CI_BUILD_URL=https://circleci.com/gh/foo/bar/7

# INFERENCE RULES

Any values set explicitly in the environment are output as-is. Unset values are
inferred using the following rules. If no value can be inferred, an empty
variable will be present in the output. Clients are expected to check for this
and error accordingly if they require a value.

## GIT_BRANCH

If *./.git* exists, read **git rev-parse --abbrev-ref HEAD**. Otherwise, try the
following environment variables in order:

APPVEYOR_REPO_BRANCH
BRANCH_NAME
BUILDKITE_BRANCH
CIRCLE_BRANCH
CI_BRANCH
CI_BUILD_REF_NAME
TRAVIS_BRANCH
WERCKER_GIT_BRANCH

## GIT_COMMIT_SHA

If *./.git* exists, read **git log -1 --pretty=format'%H'**. Otherwise, try the
following environment variables in order:

APPVEYOR_REPO_COMMIT
BUILDKITE_COMMIT
CIRCLE_SHA1
CI_BUILD_REF
CI_BUILD_SHA
CI_COMMIT
CI_COMMIT_ID
GIT_COMMIT
WERCKER_GIT_COMMIT

## GIT_COMMITTED_AT

If *./.git* exists, read **git log -1 --pretty=format:'%ct'**. Otherwise, try
the following environment variables in order:

CI_COMMITED_AT [sic]

## CI_NAME

Chosen based on the presence (and possibly value) of one the following
environment variables:

APPVEYOR
BUILDKITE
CIRCLECI
CI_NAME
GITLAB_CI
JENKINS_URL
SEMAPHORE
TDDIUM
TRAVIS
WERCKER

## CI_BUILD_ID

Chosen from the first of:

APPVEYOR_BUILD_ID
BUILDKITE_JOB_ID
BUILD_NUMBER
CIRCLE_BUILD_NUM
CI_BUILD_ID
CI_BUILD_NUMBER
SEMAPHORE_BUILD_NUMBER
TDDIUM_SESSION_ID
TRAVIS_JOB_ID
WERCKER_BUILD_ID

## CI_BUILD_URL

Chosen from the first of:

APPVEYOR_API_URL
BUILDKITE_BUILD_URL
BUILD_URL
CIRCLE_BUILD_NUM
CI_BUILD_URL
WERCKER_BUILD_URL
@@ -0,0 +1,48 @@
% CC-TEST-REPORTER-FORMAT-COVERAGE(1) User Manuals
% Code Climate <hello@codeclimate.com>
% February 2017

# PROLOG

This is a sub-command of **cc-test-reporter**(1).

# SYNOPSIS

**cc-test-reporter-format-coverage** [--output=\<path>]

# DESCRIPTION

Locate, parse, and re-format supported coverage sources.

# OPTIONS

## -o, --output *PATH*

Output to *PATH*. If a directory is given, content will be written to
*PATH*/codeclimate.json. If *-* is given, content will be written to *stdout*.
Defaults to *coverage/*, a directory.

# SUPPORTED SOURCES

## coverage/.resultset.json *Ruby*

As generated by the **SimpleCov** library.

## lcov.info *JavaScript*, *Go*, *C/C++*

As generated by any gcov-compatible tool.

## .coverage *Python*

As generated by **coverage.py**.

## build/logs/clover.xml *PHP*

As generated by **phpunit --coverage-clover**.

# ENVIRONMENT VARIABLES

*GIT_BRANCH*, *GIT_COMMIT_SHA*, and *GIT_COMMITTED_AT* are required. *CI_NAME*,
*CI_BUILD_ID*, and *CI_BUILD_URL* will be used if present.

See **cc-test-reporter-env**(1).
@@ -0,0 +1,31 @@
% CC-TEST-REPORTER-UPLOAD-COVERAGE(1) User Manuals
% Code Climate <hello@codeclimate.com>
% February 2017

# PROLOG

This is a sub-command of **cc-test-reporter**(1).

# SYNOPSIS

**cc-test-reporter-upload-coverage** [--input=\<path>]

# DESCRIPTION

Aggregate and upload formatted coverage payloads to Code Climate servers.

# OPTIONS

## -i, --input *PATH*

Read payload(s) from *PATH*. If a directory is given, payloads will be read from
*PATH*/\*.json. If *-* is given, a single payload will be expected on *stdin*.
Defaults to *coverage/*, a directory.

# ENVIRONMENT VARIABLES

*CC_TEST_REPORTER_TOKEN* or *CODECLIMATE_REPO_TOKEN* (deprecated).

# SEE ALSO

**cc-test-reporter-format-coverage**(1).
Oops, something went wrong.

0 comments on commit 9a7b804

Please sign in to comment.