update docs, add info about speculative branch execution, add info… (#9)

update docs, add info about speculative branch execution, add info ab…

Author: krzkaczor

README.md

@@ -34,7 +34,8 @@ Expect more docs soon...
    1. Testing checks
 1. [How to build X?](how-to-build-X.md)
 1. [Client API reference](client-api.md)
-1. [Localmode](localmode.md)
+1. [Local mode](local-mode.md)
+1. [Supported CI providers](supported-ci.md)
 1. [Debugging](debugging.md)
 1. [Badges](badges.md)
 1. [FAQ](faq.md)

configuration.md

@@ -18,6 +18,10 @@ checks:
     files:
     - path: "./dist/**/*.d.ts"
     - path: "./dist/**/*.js"
+settings:
+  branches:
+    - dev
+    - master
 ```
 
 This is a preferable way of defining checks (plugins). It's fully declarative and using yml make it
@@ -26,6 +30,32 @@ very readable. It works only with external checks ie. checks that part of your p
 Resolution engine for check's names will first try to find: `@codechecks/NAME` and then NAME in node
 modules and pass options.
 
+### Settings
+
+Client will always try to load settings from `codechecks.yml/json` file
+
+#### Speculative branch execution
+
+This is a feature useful for CI systems that are not triggered by PR creation but rather commit
+push.
+
+Imagine a situation you create a new branch and push some changes. You are happy with these changes
+so you create a PR. Most of CI providers by this time already run whole CI pipeline for pushed
+commit — CI was triggered by pushing new commit. That's why when codechecks ran we didn't know
+anything about PR because it didn't exist then. That's why we will try to "guess" base branch for
+you. This is currently useful only with Circle CI.
+
+You can switch off this behaviour by specifying `speculativeBranchSelection: false` in yml.
+
+By default we will always try to point speculative PRs to `master` branch. If you use more
+complicated branching model you can specify them as following:
+
+```yml
+branches:
+  - dev
+  - master
+```
+
 ## codechecks.json
 
 <!-- prettier-ignore -->

getting-started.md

@@ -2,8 +2,8 @@
 
 Codechecks is a open source platform for code review automation. It allows to create reusable
 plugins (aka. "codechecks") that can track any metric of your code (like build-size, or test
-coverage) and it integrates directly with GitHub PR flow. A `codecheck` be even more complicated and
-perform for example visual regression between screenshots of the frontend app.
+coverage) and it integrates directly with GitHub PR flow. A `codecheck` can be even more complicated
+and perform for example visual regression between screenshots of the frontend app.
 
 If you want to use already created codecheck, you need to install our GitHub app, setup CI secret,
 drop `codechecks.yml` file into your repository and you're done!
@@ -18,7 +18,8 @@ with CC.
 1. Log into our [web application](https://app.codechecks.io/) using Github.
 2. Click "Add new project" button
 3. You will be redirected back into Github interface where you need to select appropriate
-   repositories.
+   repositories. Note: support for private repositories is in closed beta. Please send as an email
+   to [[email protected]](mailto:[email protected]) to enable them.
 4. Once done you should be able to see all repositories within our app (if not please refresh). Note
    that in the right top corner you can switch between orgs.
 5. Copy secret using "copy" button and paste it as secret environment inside your CI interface:
@@ -27,7 +28,7 @@ with CC.
 CC_SECRET=COPIED SECRET
 ```
 
-For now only CircleCI is supported.
+[List of supported CI providers](./supported-ci.md)
 
 In this mini tutorial we assume that you develop frontend app so we want to watch how build size is
 changing between PRs. Already existing codecheck does exactly this:
@@ -66,11 +67,11 @@ We can dry run our config locally. Just type `yarn codechecks`. You should see s
 
 Notice that each status of the file is "new" because this is the very first time we run codechecks.
 
-We are almost done, last thing is to actually run codechecks as part of your CI pipeline. So far we
-support only CircleCI (travis support is coming soon). Important bit here is that you need to build
-app before running codechecks (so we can measure it's size). You can see sample here:
+We are almost done, last thing is to actually run codechecks as part of your CI pipeline. Important
+bit here is that you need to build app before running codechecks (so we can measure it's size). You
+can see sample here:
 https://github.com/OasisDEX/eth2dai/blob/4bc1606dfbe0f002261b24fefc0a5c47c0cd950c/.circleci/config.yml#L72
-To run codechecks simple do `yarn codechecks`.
+To run codechecks simple do `npx codechecks` or `yarn codechecks`.
 
 Make sure that you added `CC_SECRET` environment variable to your CI secrets. That's it! Push your
 changes, create PR and see how we measure build size. Remember, this is one of the simplest

how-does-it-work.md

@@ -18,15 +18,15 @@ Another important task of API is communication with Github. Codechecks require i
 on repos that you're interested in. This allows us to provide feedback information using GitHub
 Checks API. Support for other services like BitBucket and GitLab is coming soon.
 
-### JS Client aka @codechecks/client
+### JS Client aka `@codechecks/client`
 
 Client (currently written in TypeScript) allows for easy communication with API. It provides
 execution context for plugins by parsing environment variables, getting more information about the
-project from API etc. In future there maybe another implementation, written in something other than
+project from API etc. In future there maybe another implementation, written in other language than
 TypeScript but it's out of scope for now and we threat JS client as the only official
 implementation.
 
 ### Particular checks ex. @codechecks/build-size-watcher
 
-JS client enables to write reusable "plugins" (we call them codechecks) in JS and distribute them
-directly as NPM packages.
+JS client enables to write reusable "plugins" (we call them simply codechecks) in JS and distribute
+them directly as NPM packages.

how-to-build-X.md

@@ -6,10 +6,10 @@ In this section we will provide high level overview how to build useful stuff us
 
 1. Measure size of files that you're interested in (just grab some lib from NPM or use `fs.stat` ).
    We treat that value as an artifact.
-1. Save value to Storage API for **current** commit.
-1. Get previously saved value for **base** branch from Storage API.
+1. Save value to Storage API for **current** commit - `saveValue` method.
+1. Get previously saved value for **base** branch from Storage API - `getValue` method.
 1. Compare these values to get information how build size changed.
-1. Use our Report API to report back to github result of comparison.
+1. Use our Report API to report back to github result of comparison - `report` method.
 
 This is a literally description of what
 [@codechcecks/build-size-watcher](https://github.com/codechecks/build-size-watcher) does.
@@ -18,12 +18,16 @@ This is a literally description of what
 
 1. Obtain screenshots of the current state of the app. Use one of many libraries to make screenshots
    of storybook or make screenshots during E2E tests.
-1. Save collection of screenshots for **current** commit using Storage API.
-1. Retrieve previously saved screenshots for **base** branch from the Storage API.
+1. Save directory with screenshots for **current** commit using Storage API — `saveDirectory`
+   method.
+1. Retrieve previously saved screenshots for **base** branch from the Storage API — `getDirectory`
+   method.
 1. Compare screenshots using one of many libraries available on NPM and create HTML report
    describing all changes etc.
-1. Upload the HTML report as normal artifact — artifacts are browserable by default.
-1. Obtain the URL to the uploaded HTML report and attach it to Github PR by using Report API.
+1. Upload the HTML report as normal artifact — artifacts are browserable by default —
+   `saveDirectory` method.
+1. Obtain the URL to the uploaded HTML report and attach it to Github PR by using Report API —
+   `getArtifactLink` method.
 
 Using similar logic you can implement code coverage tracking, performance tracking and basically
 whatever you want.

localmode.md renamed to local-mode.md

@@ -5,9 +5,11 @@ Not in any particular order.
 - [x] Forks supports
 - [x] Offline mode
 - [x] Webapp for displaying secrets
-- [x] Private repos support (in closed beta)
-- [ ] Speculative base branch selection when PR doesnt exist yet
-- [ ] Awesome Codechecks repo
+- [x] Private repos support (in closed beta send email to
+      [[email protected]](mailto:[email protected]))
+- [x] Speculative base branch selection when PR doesnt exist yet
+- [x] Travis CI support
+- [ ] Awesome Codechecks list
 - [ ] Codechecks ideas:
   - [ ] Visual Regression codecheck
   - [ ] Test coverage like codecov codecheck

roadmap.md

@@ -0,0 +1,7 @@
+# Supported CI providers
+
+- Circle CI
+- Travis CI
+
+Is your favorite CI provider missing? Just create an issue
+[here](https://github.com/codechecks/monorepo).