# 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:

- [Essentials: Getting Started](./essentials/getting-started.md)
- [Advanced: Architecture](./advanced/architecture.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 -->
