TrizTech/ohif-viewer
17
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: shift files around to match summary structure

Browse Source
This commit is contained in:
dannyrb committed 2019-12-07 00:12:08 -05:00
1 parent 9a71edda6a
commit 830cb82965
21 files changed
+51 -62
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/latest/development/continous-integration.md
+109
View File
@@ -0,0 +1,109 @@
# Continous Integration (CI)
This repository uses `CircleCI` and `Netlify` for continous integration.
## Deploy Previews
[Netlify Deploy previews][deploy-previews] are generated for every pull request.
They allow pull request authors and reviewers to "Preview" the OHIF Viewer as if
the changes had been merged.
Deploy previews can be configured by modifying the `netlify.toml` file in the
root of the repository. Some additional scripts/assets for netlify are included
in the root `.netlify` directory.
## Workflows
[CircleCI Workflows][circleci-workflows] are a set of rules for defining a
collection of jobs and their run order. They are self-documenting and their
configuration can be found in our CircleCI configuration file:
`.circleci/config.yml`.
### Workflow: PR_CHECKS
The PR_CHECKS workflow (Pull Request Checks) runs our automated unit and
end-to-end tests for every code check-in. These tests must all pass before code
can be merged to our `master` branch.
<div style="text-align: center;">
<a href="/assets/img/WORKFLOW_PR_CHECKS.png">
<img src="/assets/img/WORKFLOW_PR_CHECKS.png" alt="workflow diagram" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>Workflow diagram for PR_CHECKS</i></div>
</div>
### Workflow: PR_OPTIONAL_DOCKER_PUBLISH
The PR_OPTIONAL_DOCKER_PUBLISH workflow allows for "manual approval" to publish
the pull request as a tagged docker image. This is helpful when changes need to
be tested with the Google Adapter before merging to `master`.
<div style="text-align: center;">
<a href="/assets/img/WORKFLOW_PR_OPTIONAL_DOCKER_PUBLISH.png">
<img src="/assets/img/WORKFLOW_PR_OPTIONAL_DOCKER_PUBLISH.png" alt="workflow diagram" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>Workflow diagram for PR_WORKFLOW_PR_OPTIONAL_DOCKER_PUBLISH</i></div>
</div>
> NOTE: This workflow will fail unless it's for a branch on our `upstream`
> repository. If you need this functionality, but the branch is from a fork,
> merge the changes to a short-lived `feature/` branch on `upstream`
### Workflow: DEPLOY
The DEPLOY workflow deploys the OHIF Viewer when changes are merged to master.
It uses the Netlify CLI to deploy assets created as part of the repository's PWA
Build process (`yarn run build`). The workflow allows for "Manual Approval" to
promote the build to `STAGING` and `PRODUCTION` environments.
<div style="text-align: center;">
<a href="/assets/img/WORKFLOW_DEPLOY.png">
<img src="/assets/img/WORKFLOW_DEPLOY.png" alt="workflow diagram" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>Workflow diagram for WORKFLOW_DEPLOY</i></div>
</div>
| Environment | Description | URL |
| ----------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
| Development | Always reflects latest changes on `master` branch. | [Netlify][netlify-dev] / [OHIF][ohif-dev] |
| Staging | For manual testing before promotion to prod. Keeps development workflow unblocked. | [Netlify][netlify-stage] / [OHIF][ohif-stage] |
| Production | Stable, tested, updated less frequently. | [Netlify][netlify-prod] / [OHIF][ohif-prod] |
### Workflow: RELEASE
The RELEASE workflow publishes our `npm` packages, updated documentation, and
`docker` image when changes are merged to master. `Lerna` and "Semantic Commit
Syntax" are used to independently version and publish the many packages in our
monorepository. If a new version is cut/released, a Docker image is created.
Documentation is generated with `gitbook` and pushed to our `gh-pages` branch.
GitHub hosts the `gh-pages` branch with GitHub Pages.
- Platform Packages: https://github.com/ohif/viewers/#platform
- Extension Packages: https://github.com/ohif/viewers/#extensions
- Documentation: https://docs.ohif.org/
<div style="text-align: center;">
<a href="/assets/img/WORKFLOW_RELEASE.png">
<img src="/assets/img/WORKFLOW_RELEASE.png" alt="workflow diagram" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>Workflow diagram for WORKFLOW_RELEASE</i></div>
</div>
### HOTFIX
_Not yet implemented_
<!--
LINKS
-->
<!-- prettier-ignore-start -->
[deploy-previews]: https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
[circleci-workflows]: https://circleci.com/docs/2.0/workflows/
[netlify-dev]: https://ohif-dev.netlify.com
[netlify-stage]: https://ohif-stage.netlify.com
[netlify-prod]: https://ohif-prod.netlify.com
[ohif-dev]: https://viewer-dev.ohif.org
[ohif-stage]: https://viewer-stage.ohif.org
[ohif-prod]: https://viewer-prod.ohif.org
<!-- prettier-ignore-end -->
docs/latest/development/contributing.md
+146
View File
@@ -0,0 +1,146 @@
# Contributing
## How can I help?
Fork the repository, make your change and submit a pull request. If you would
like to discuss the changes you intend to make to clarify where or how they
should be implemented, please don't hesitate to create a new issue. At a
minimum, you may want to read the following documentation:
- [Getting Started](/development/getting-started.md)
- [Architecture](/architecture/index.md)
Pull requests that are:
- Small
- [Well tested](./testing.md)
- Decoupled
Are much more likely to get reviewed and merged in a timely manner.
## When changes impact multiple repositories
While this can be tricky, we've tried to reduce how often this situation crops
up this with our [recent switch to a monorepo][monorepo]. Our maintained
extensions, ui components, internationalization library, and business logic can
all be developed by simply running `yarn run dev` from the repository root.
Testing the viewer with locally developed, unpublished package changes from a
package outside of the monorepo is most common with extension development. Let's
demonstrate how to accomplish this with two commonly forked extension
dependencies:
### `cornerstone-tools`
On your local file system:
```bash
# code/my-projects/
.
├── cornerstonejs/cornerstone-tools
└── ohif/viewers
```
- Open a terminal/shell
- Navigate to `cornerstonejs/cornerstone-tools`
- `npm install`
- [`yarn link`](https://yarnpkg.com/en/docs/cli/link)
- `npm run dev`
- Open a new terminal/shell
- Navigate to `ohif/viewers`.
- `yarn install`
- [`yarn link cornerstone-tools`](https://yarnpkg.com/en/docs/cli/link)
- `yarn run dev`
As you make changed to `cornerstone-tools`, and it's output is rebuilt, you
should see the following behavior:
<div style="text-align: center;">
<a href="/assets/img/cornerstone-tools-link.gif">
<img src="/assets/img/cornerstone-tools-link.gif" alt="Example of linked cornerstone-tools package" style="margin: 0 auto; max-width: 500px;" />
</a>
<div><i>example of linked cornerstone-tools package</i></div>
</div>
If you wish to stop using your local package, run the following commands in the
`ohif/viewers` repository root:
- `yarn unlink cornerstone-tools`
- `yarn install --force`
### `react-vtkjs-viewport`
On your local file system:
```bash
# code/my-projects/
.
├── ohif/react-vtkjs-viewport
└── ohif/viewers
```
- Open a terminal/shell
- Navigate to `ohif/react-vtkjs-viewport`
- `yarn install`
- [`yarn link`](https://yarnpkg.com/en/docs/cli/link)
- `yarn run start`
- Open a new terminal/shell
- Navigate to `ohif/viewers`.
- `yarn install`
- [`yarn link react-vtkjs-viewport`](https://yarnpkg.com/en/docs/cli/link)
- `yarn run dev`
#### Other linkage notes
We're still working out some of the kinks with local package development as
there are a lot of factors that can influence the behavior of our development
server and bundler. If you encounter issues not addressed here, please don't
hesitate to reach out on GitHub.
## Any guidance on submitting changes?
While we do appreciate code contributions, triaging and integrating contributed
code changes can be very time consuming. Please consider the following tips when
working on your pull requests:
- Functionality is appropriate for the repository. Consider creating a GitHub
issue to discuss your suggested changes.
- The scope of the pull request is not too large. Please consider separate pull
requests for each feature as big pull requests are very time consuming to
understand.
We will provide feedback on your pull requests as soon as possible. Following
the tips above will help ensure your changes are reviewed.
## Testing contribution pull requests
OHIF uses [netlify](netlify.com) so that pull requests are autogenerated and
available for testing.
For example, [this url][example-url] allows you to test [pull request 237, the
request that created this FAQ entry,][pr-237] using data pulled from Amazon S3.
Replacing the number 237 in the link below with your pull request number should
let you test it as well and you can use this link for discussions on github
without requiring reviewers to download and build your branch.
```bash
https://deploy-preview-237--ohif.netlify.com/viewer/?url=https://s3.eu-central-1.amazonaws.com/ohif-viewer/sampleDICOM.json
```
If you have made a documentation change, a link like this will let you preview
the gitbook generated by the pull request:
```bash
https://deploy-preview-237--ohif.netlify.com/contributing.html
```
<!--
Links
-->
<!-- prettier-ignore-start -->
[example-url]: https://deploy-preview-237--ohif.netlify.com/viewer/?url=https://s3.eu-central-1.amazonaws.com/ohif-viewer/sampleDICOM.json
[pr-237]: https://github.com/OHIF/Viewers/pull/237
[monorepo]: https://github.com/OHIF/Viewers/issues/768
<!-- prettier-ignore-end -->
docs/latest/development/getting-started.md
+107
View File
@@ -0,0 +1,107 @@
# Getting Started
## Setup
### Fork & Clone
If you intend to contribute back changes, or if you would like to pull updates
we make to the OHIF Viewer, then follow these steps:
- [Fork][fork-a-repo] the [OHIF/Viewers][ohif-viewers-repo] repository
- [Create a local clone][clone-a-repo] of your fork
- `git clone https://github.com/YOUR-USERNAME/Viewers`
- Add OHIF/Viewers as a [remote repository][add-remote-repo] labled `upstream`
- Navigate to the cloned project's directory
- `git remote add upstream https://github.com/OHIF/Viewers.git`
With this setup, you can now [sync your fork][sync-changes] to keep it
up-to-date with the upstream (original) repository. This is called a "Triangular
Workflow" and is common for Open Source projects. The GitHub blog has a [good
graphic that illustrates this setup][triangular-workflow].
### Private
Alternatively, if you intend to use the OHIF Viewer as a starting point, and you
aren't as concerned with syncing updates, then follow these steps:
1. Navigate to the [OHIF/Viewers][ohif-viewers] repository
2. Click `Clone or download`, and then `Download ZIP`
3. Use the contents of the `.zip` file as a starting point for your viewer
> NOTE: It is still possible to sync changes using this approach. However,
> submitting pull requests for fixes and features are best done with the
> separate, forked repository setup described in "Fork & Clone"
## Developing
### Requirements
- [Node.js & NPM](https://nodejs.org/en/)
- [Yarn](https://yarnpkg.com/en/)
- Yarn workspaces should be enabled:
- `yarn config set workspaces-experimental true`
### Kick the tires
Navigate to the root of the project's directory in your terminal and run the
following commands:
```bash
# Restore dependencies
yarn install
# Start local development server
yarn run dev
```
You should see the following output:
```bash
@ohif/viewer: i ｢wds｣: Project is running at http://localhost:3000/
@ohif/viewer: i ｢wds｣: webpack output is served from /
@ohif/viewer: i ｢wds｣: Content not from webpack is served from D:\code\ohif\Viewers\platform\viewer
@ohif/viewer: i ｢wds｣: 404s will fallback to /index.html
# And a list of all generated files
```
### 🎉 Celebrate 🎉
<center>
<img alt="development server hosted app" src="/assets/img/loading-study.gif" />
<i>Our app, hosted by the development server</i>
</center>
### Building for Production
> More comprehensive guides for building and publishing can be found in our
> [deployment docs](./deployment/index.md)
```bash
# Build static assets to host a PWA
yarn run build
# Build packaged output (script-tag use)
yarn run build:package
```
## Troubleshooting
- If you receive a _"No Studies Found"_ message and do not see your studies, try
changing the Study Date filters to a wider range.
- If you see a 'Loading' message which never resolves, check your browser
JavaScript console inside the Developer Tools to identify any errors.
<!--
Links
-->
<!-- prettier-ignore-start -->
[fork-a-repo]: https://help.github.com/en/articles/fork-a-repo
[clone-a-repo]: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
[add-remote-repo]: https://help.github.com/en/articles/fork-a-repo#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository
[sync-changes]: https://help.github.com/en/articles/syncing-a-fork
[triangular-workflow]: https://github.blog/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/#improved-support-for-triangular-workflows
[ohif-viewers-repo]: https://github.com/OHIF/Viewers
[ohif-viewers]: https://github.com/OHIF/Viewers
<!-- prettier-ignore-end -->
docs/latest/development/testing.md
+145
View File
@@ -0,0 +1,145 @@
# Contributing: Tests
> Testing is an opinionated topic. Here is a rough overview of our testing
> philosiphy. See something you want to discuss or think should be changed? Open
> a PR and let's discuss.
You're an engineer. You know how to write code, and writing tests isn't all that
different. But do you know why we write tests? Do you know when to write one, or
what kind of test to write? How do you know if a test is a _"good"_ test? This
document's goal is to give you the tools you need to make those determinations.
Okay. So why do we write tests? To increase our... **CONFIDENCE**
- If I do a large refactor, does everything still work?
- If I changed some critical piece of code, is it safe to push to production?
Gaining the confidence we need to answer these questions after every change is
costly. Good tests allow us to answer them without manual regression testing.
What and how we choose to test to increase that confidence is nuanced.
## Kinds of Tests
Test's buy us confidence, but not all tests are created equal. Each kind of test
has a different cost to write and maintain. An expensive test is worth it if it
gives us confidence that a payment is processed, but it may not be the best
choice for asserting an element's border color.
| Test Type | Example | Speed | Cost |
| ----------- | ------------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------ |
| Static | `addNums(1, '2')` called with `string`, expected `int`. | :rocket: Instant | :money_with_wings: |
| Unit | `addNums(1, 2)` returns expected result `3` | :airplane: Fast | :money_with_wings::money_with_wings: |
| Integration | Clicking "Sign In", navigates to the dashboard (mocked network requests) | :running: Okay | :money_with_wings::money_with_wings::money_with_wings: |
| End-to-end | Clicking "Sign In", navigates to the dashboard (no mocks) | :turtle: Slow | :money_with_wings::money_with_wings::money_with_wings::money_with_wings: |
- :rocket: Speed: How quickly tests run
- :money_with_wings: Cost: Time to write, and to debug when broken (more points
of failure)
### Static Code Analysis
Modern tooling gives us this "for free". It can catch invalid regular
expressions, unused variables, and guarantee we're calling methods/functions
with the expected paramater types.
Example Tooling:
- [ESLint][eslint-rules]
- [TypeScript][typescript-docs] or [Flow][flow-org]
### Unit Tests
The building blocks of our libraries and applications. For these, you'll often
be testing a single function or method. Conceptually, this equates to:
_Pure Function Test:_
- If I call `sum(2, 2)`, I expect the output to be `4`
_Side Effect Test:_
- If I call `resetViewport(viewport)`, I expect `cornerstone.reset` to be called
with `viewport`
#### When to use
Anything that is exposed as public API should have unit tests.
#### When to avoid
You're actually testing implementation details. You're testing implementation
details if:
- Your test does something that the consumer of your code would never do.
- IE. Using a private function
- A refactor can break your tests
### Integration Tests
We write integration tests to gain confidence that several units work together.
Generally, we want to mock as little as possible for these tests. In practice,
this means only mocking network requests.
#### When to use
...
### End-to-End Tests
These are the most expensive tests to write and maintain. Largely because, when
they fail, they have the largest number of potential points of failure. So why
do we write them? Because they also buy us the most confidence.
#### When to use
Mission critical features and functionality, or to cover a large breadth of
functionality until unit tests catch up. Unsure if we should have a test for
feature `X` or scenario `Y`? Open an issue and let's discuss.
## Summary
- Does your test increase confidence?
- Does the test type chosen balance the cost-to-confidence ratio?
## Further Reading
### General
- [Assert(js) Conf 2018 Talks][assert-js-talks]
- [Write tests. Not too many. Mostly integration.][kent-talk] - Kent C. Dodds
- [I see your point, but…][gleb-talk] - Gleb Bahmutov
- [Static vs Unit vs Integration vs E2E Testing][kent-blog] - Kent C. Dodds
(Blog)
### End-to-end Testing w/ Cypress
- [Getting Started](https://docs.cypress.io/guides/overview/why-cypress.html)
- Be sure to check out `Getting Started` and `Core Concepts`
- [Best Practices](https://docs.cypress.io/guides/references/best-practices.html)
- [Example Recipes](https://docs.cypress.io/examples/examples/recipes.html)
## Testing Dorito
[![testing dorito][testing-dorito-img]][testing-dorito]
<!--
Links
-->
<!-- prettier-ignore-start -->
[eslint-rules]: https://eslint.org/docs/rules/
[typescript-docs]: https://www.typescriptlang.org/docs/home.html
[flow-org]: https://flow.org/
<!-- Talks -->
[assert-js-talks]: https://www.youtube.com/playlist?list=PLZ66c9_z3umNSrKSb5cmpxdXZcIPNvKGw
[kent-talk]: https://www.youtube.com/watch?list=PLV5CVI1eNcJgNqzNwcs4UKrlJdhfDjshf
[gleb-talk]: https://www.youtube.com/watch?v=5FnalKRjpZk
[kent-blog]: https://kentcdodds.com/blog/unit-vs-integration-vs-e2e-tests
<!-- Images -->
[testing-trophy]: https://twitter.com/kentcdodds/status/960723172591992832?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E960723172591992832&ref_url=https%3A%2F%2Fkentcdodds.com%2Fblog%2Fwrite-tests
[aaron-square]: https://twitter.com/Carofine247/status/966727489274961920
[gleb-pyramid]: https://twitter.com/Carofine247/status/966764532046684160/photo/3
[testing-pyramid]: https://dojo.ministryoftesting.com/dojo/lessons/the-mobile-test-pyramid
[testing-dorito]: https://twitter.com/denvercoder/status/960752578198843392
[testing-dorito-img]: https://pbs.twimg.com/media/DVVHXycUMAAcN-F?format=jpg&name=4096x4096
<!-- prettier-ignore-end -->