Skip to content

Commit 9a7b804

Browse files
pbrisbinpbrisbin
committed
First draft
Using documentation-driven development, author a README, DEVELOPERS file, and man-pages for the proposed operation of the reporter.
1 parent 4963c84 commit 9a7b804

10 files changed

+417
-0
lines changed

Diff for: ‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
man/*
2+
!man/*.md

Diff for: ‎DEVELOPERS.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
## Viewing Documentation Locally
2+
3+
```console
4+
make all
5+
man man/cc-test-reporter.1
6+
```
7+
8+
## Implementation Notes
9+
10+
The following are behaviors or details about the ruby-test-reporter that may or
11+
may not need to be preserved in the new reporter -- I'm hoping not.
12+
13+
- Token in Payload not HTTP header [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/formatter.rb#L66)
14+
- Custom SSL CA [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L97)
15+
- `/test_reports/batch`? [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L19)
16+
- Gzip [ref](https://github.com/codeclimate/ruby-test-reporter/blob/master/lib/code_climate/test_reporter/client.rb#L58)
17+
18+
## Coverage Payload
19+
20+
This is the payload currently expected by `codeclimate.com/test_reports`.
21+
22+
*TODO*: remove keys not actually used by our system.
23+
24+
```json
25+
{
26+
ci_service: {
27+
branch:,
28+
build_identifier:,
29+
build_url:,
30+
commit_sha:,
31+
committed_at:,
32+
name:,
33+
pull_request:,
34+
worker_id:
35+
},
36+
covered_percent:,
37+
covered_strength:,
38+
environment: {
39+
gem_version:,
40+
pwd:,
41+
rails_root:,
42+
simplecov_root:
43+
},
44+
git: {
45+
branch:,
46+
committed_at:,
47+
head:
48+
},
49+
line_counts: {
50+
covered:,
51+
missed:,
52+
total:
53+
},
54+
//partial:,
55+
//repo_token:,
56+
run_at:,
57+
source_files: [
58+
{
59+
blob_id:,
60+
coverage: [
61+
// hit count, or null for missed
62+
...,
63+
...,
64+
...,
65+
],
66+
covered_percent:,
67+
covered_strength:,
68+
line_counts: {
69+
covered:,
70+
missed:,
71+
total:
72+
},
73+
name: name
74+
}
75+
]
76+
}
77+
```

Diff for: ‎LICENSE

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Copyright 2017 Code Climate <[email protected]>
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of
4+
this software and associated documentation files (the "Software"), to deal in
5+
the Software without restriction, including without limitation the rights to
6+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
7+
the Software, and to permit persons to whom the Software is furnished to do so,
8+
subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
15+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
16+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
17+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
18+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Diff for: ‎Makefile

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
PANDOC = $(shell which pandoc)
2+
MAN_FILES = $(wildcard man/*.md)
3+
MAN_PAGES = $(patsubst man/%.md,man/%,$(MAN_FILES))
4+
5+
man/%: man/%.md
6+
$(PANDOC) -s -t man $< -o $@
7+
8+
all: $(MAN_PAGES)

Diff for: ‎README.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# cc-test-reporter
2+
3+
TODO: details
4+
5+
## Installation
6+
7+
```
8+
curl -L https://codeclimate.s3.amazonaws.com/test-reporter/test-reporter-latest > ./cc-test-reporter
9+
chmod +x ./cc-test-reporter
10+
sudo mv ./cc-test-reporter /usr/local/bin # anywhere in $PATH
11+
```
12+
13+
## Usage
14+
15+
See the [man-pages][man/].
16+
17+
## Client-Side Aggregation (i.e Parallel Test Coverage)
18+
19+
TODO: describe further
20+
21+
1. After each test:
22+
23+
```
24+
eval $(cc-test-reporter env)
25+
cc-test-reporter format-coverage --out "coverage/codeclimate.$N.json"
26+
aws s3 sync coverage/ "s3://my-bucket/coverage/$GIT_COMMIT_SHA"
27+
```
28+
29+
1. After all tests:
30+
31+
```
32+
eval $(cc-test-reporter env)
33+
aws s3 sync "s3://my-bucket/coverage/$GIT_COMMIT_SHA" coverage/
34+
cc-test-reporter upload-coverage
35+
```
36+
37+
## Copyright
38+
39+
See the [LICENSE][].

Diff for: ‎man/cc-test-reporter-coverage.1.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
% CC-TEST-REPORTER-COVERAGE(1) User Manuals
2+
% Code Climate <[email protected]>
3+
% February 2017
4+
5+
# PROLOG
6+
7+
This is a sub-command of **cc-test-reporter**(1).
8+
9+
# SYNOPSIS
10+
11+
**cc-test-reporter-coverage**
12+
13+
# DESCRIPTION
14+
15+
Format and upload coverage information from supported sources to Code Climate
16+
servers.
17+
18+
This is roughly equivalent to:
19+
20+
eval $(cc-test-reporter env)
21+
cc-test-reporter format-coverage
22+
cc-test-reporter upload-coverage
23+
24+
# ENVIRONMENT VARIABLES
25+
26+
*CC_TEST_REPORTER_TOKEN*
27+
28+
# SEE ALSO
29+
30+
**cc-test-reporter-env**(1),
31+
**cc-test-reporter-format-coverage**(1), and
32+
**cc-test-reporter-upload-coverage**(1).

Diff for: ‎man/cc-test-reporter-env.1.md

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
% CC-TEST-REPORTER-ENV(1) User Manuals
2+
% Code Climate <[email protected]>
3+
% February 2017
4+
5+
# PROLOG
6+
7+
This is a sub-command of **cc-test-reporter**(1).
8+
9+
# SYNOPSIS
10+
11+
**cc-test-reporter-env**
12+
13+
# DESCRIPTION
14+
15+
Infer and output information about the environment the reporter is running in.
16+
17+
# EXAMPLE OUTPUT
18+
19+
The output is formatted for use with **eval**(1):
20+
21+
GIT_BRANCH=master
22+
GIT_COMMIT_SHA=594a20638eb9a758e2481c9ad2bdae121a1e03ed
23+
GIT_COMMITTED_AT=1488138087
24+
CI_NAME=circle-ci
25+
CI_BUILD_ID=7
26+
CI_BUILD_URL=https://circleci.com/gh/foo/bar/7
27+
28+
# INFERENCE RULES
29+
30+
Any values set explicitly in the environment are output as-is. Unset values are
31+
inferred using the following rules. If no value can be inferred, an empty
32+
variable will be present in the output. Clients are expected to check for this
33+
and error accordingly if they require a value.
34+
35+
## GIT_BRANCH
36+
37+
If *./.git* exists, read **git rev-parse --abbrev-ref HEAD**. Otherwise, try the
38+
following environment variables in order:
39+
40+
APPVEYOR_REPO_BRANCH
41+
BRANCH_NAME
42+
BUILDKITE_BRANCH
43+
CIRCLE_BRANCH
44+
CI_BRANCH
45+
CI_BUILD_REF_NAME
46+
TRAVIS_BRANCH
47+
WERCKER_GIT_BRANCH
48+
49+
## GIT_COMMIT_SHA
50+
51+
If *./.git* exists, read **git log -1 --pretty=format'%H'**. Otherwise, try the
52+
following environment variables in order:
53+
54+
APPVEYOR_REPO_COMMIT
55+
BUILDKITE_COMMIT
56+
CIRCLE_SHA1
57+
CI_BUILD_REF
58+
CI_BUILD_SHA
59+
CI_COMMIT
60+
CI_COMMIT_ID
61+
GIT_COMMIT
62+
WERCKER_GIT_COMMIT
63+
64+
## GIT_COMMITTED_AT
65+
66+
If *./.git* exists, read **git log -1 --pretty=format:'%ct'**. Otherwise, try
67+
the following environment variables in order:
68+
69+
CI_COMMITED_AT [sic]
70+
71+
## CI_NAME
72+
73+
Chosen based on the presence (and possibly value) of one the following
74+
environment variables:
75+
76+
APPVEYOR
77+
BUILDKITE
78+
CIRCLECI
79+
CI_NAME
80+
GITLAB_CI
81+
JENKINS_URL
82+
SEMAPHORE
83+
TDDIUM
84+
TRAVIS
85+
WERCKER
86+
87+
## CI_BUILD_ID
88+
89+
Chosen from the first of:
90+
91+
APPVEYOR_BUILD_ID
92+
BUILDKITE_JOB_ID
93+
BUILD_NUMBER
94+
CIRCLE_BUILD_NUM
95+
CI_BUILD_ID
96+
CI_BUILD_NUMBER
97+
SEMAPHORE_BUILD_NUMBER
98+
TDDIUM_SESSION_ID
99+
TRAVIS_JOB_ID
100+
WERCKER_BUILD_ID
101+
102+
## CI_BUILD_URL
103+
104+
Chosen from the first of:
105+
106+
APPVEYOR_API_URL
107+
BUILDKITE_BUILD_URL
108+
BUILD_URL
109+
CIRCLE_BUILD_NUM
110+
CI_BUILD_URL
111+
WERCKER_BUILD_URL

Diff for: ‎man/cc-test-reporter-format-coverage.1.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
% CC-TEST-REPORTER-FORMAT-COVERAGE(1) User Manuals
2+
% Code Climate <[email protected]>
3+
% February 2017
4+
5+
# PROLOG
6+
7+
This is a sub-command of **cc-test-reporter**(1).
8+
9+
# SYNOPSIS
10+
11+
**cc-test-reporter-format-coverage** [--output=\<path>]
12+
13+
# DESCRIPTION
14+
15+
Locate, parse, and re-format supported coverage sources.
16+
17+
# OPTIONS
18+
19+
## -o, --output *PATH*
20+
21+
Output to *PATH*. If a directory is given, content will be written to
22+
*PATH*/codeclimate.json. If *-* is given, content will be written to *stdout*.
23+
Defaults to *coverage/*, a directory.
24+
25+
# SUPPORTED SOURCES
26+
27+
## coverage/.resultset.json *Ruby*
28+
29+
As generated by the **SimpleCov** library.
30+
31+
## lcov.info *JavaScript*, *Go*, *C/C++*
32+
33+
As generated by any gcov-compatible tool.
34+
35+
## .coverage *Python*
36+
37+
As generated by **coverage.py**.
38+
39+
## build/logs/clover.xml *PHP*
40+
41+
As generated by **phpunit --coverage-clover**.
42+
43+
# ENVIRONMENT VARIABLES
44+
45+
*GIT_BRANCH*, *GIT_COMMIT_SHA*, and *GIT_COMMITTED_AT* are required. *CI_NAME*,
46+
*CI_BUILD_ID*, and *CI_BUILD_URL* will be used if present.
47+
48+
See **cc-test-reporter-env**(1).

Diff for: ‎man/cc-test-reporter-upload-coverage.1.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
% CC-TEST-REPORTER-UPLOAD-COVERAGE(1) User Manuals
2+
% Code Climate <[email protected]>
3+
% February 2017
4+
5+
# PROLOG
6+
7+
This is a sub-command of **cc-test-reporter**(1).
8+
9+
# SYNOPSIS
10+
11+
**cc-test-reporter-upload-coverage** [--input=\<path>]
12+
13+
# DESCRIPTION
14+
15+
Aggregate and upload formatted coverage payloads to Code Climate servers.
16+
17+
# OPTIONS
18+
19+
## -i, --input *PATH*
20+
21+
Read payload(s) from *PATH*. If a directory is given, payloads will be read from
22+
*PATH*/\*.json. If *-* is given, a single payload will be expected on *stdin*.
23+
Defaults to *coverage/*, a directory.
24+
25+
# ENVIRONMENT VARIABLES
26+
27+
*CC_TEST_REPORTER_TOKEN* or *CODECLIMATE_REPO_TOKEN* (deprecated).
28+
29+
# SEE ALSO
30+
31+
**cc-test-reporter-format-coverage**(1).

0 commit comments

Comments
 (0)