atlassian-webresource-webpack-plugin/CONTRIBUTING.md

Auto-generates web-resource definitions from your webpacked code, for usage in an Atlassian product or plugin.

# Contributing

Contributions to this plugin are most welcome, and come in many forms --
from making a suggestion of how to improve the functionality or usability of the plugin,
to reporting buggy behaviour, through to writing use case tests, or making changes to the plugin code.

## Making a request

You can raise feature requests, bug reports, or proposals for changes on
[the Atlassian Ecosystem issue tracker][self-issues].

Bug reports and feature requests are more likely to be worked on when the problem that
it solves is clearly explained. Code examples of what the expected outcomes are make it
significantly easier for developers to establish the right context.

Ultimately, any information that helps a developer know they're actually solving a problem is valued.

## Developing the plugin

### Setup

Ensure your development environment meets the following requirements:

- [node](https://nodejs.org/) version should be 6 or above
  (follow the [Node installation instructions][needs-node]; check with `node -v`)
- [yarn](https://yarnpkg.com/) should be installed globally
  (follow the [Yarn installation instructions][needs-yarn]; check with `yarn --version`)
- [this repository][self] should be cloned on to your development machine.

### Building

At present, this plugin is written in standard EcmaScript 2016 as understood by the supported Node versions.
There is no compilation step, so there is no need to build / watch the plugin's source as it is changed.

### Testing

To run the plugin's tests, run `yarn test`.

To check whether the code adheres to the styleguide and steers clear of common errors, run `yarn lint`.

### Writing tests

We keep tests in this repository in two sub-folders:

- `test/unit` -- the tests that exercise individual source modules' APIs and behaviours.
- `test/use-cases` -- houses multiple folders, each demonstrating how the plugin is expected to work from an
  author's perspective.

We request that any contribution have an accompanying use-case test that demonstrates how the change
is expected to work.

#### Testing technologies in use

This repository currently uses [Jest][jest] for all its test code.

#### Writing use-case tests

Each use-case test exists to demonstrate a valid way of writing a webpack config file that makes
use of this plugin. Each use-case folder is divided in to:

- `webpack.config.js` file,
- `*.test.js` file containing your test assertions,
- `src/` directory, containing simple demo code to be compiled, and
- `target/` directory is expected to be generated by running webpack.

A use-case test file should first run webpack, push the output in to a `target/` directory,
then read the output generated by the webpack build, and finally run assertions that the
shape of the output is as expected.

Think of each use-case test as a usage guide example, which you
could show someone if they asked "how do I achieve X?" or "how can I do Y?".
As such, when writing these kinds of tests, the most important parts are the
content of the `webpack.config.js` file, followed by the `src/` directory.

### Getting your change published

The maintainers accept pull requests to [this repository][self].
A pull request is more likely to be accepted when:

- It references an issue from [the issue tracker][self-issues].
- It explains how this contribution improves the plugin (i.e., who the change helps, then why and how it helps).
- It has tests. For new features or changes to plugin behaviour, use-case tests are preferred.
- Its changes are lint-free -- you can check this by running `yarn lint`.
- It adds a short line or two to the changelog under the "unreleased" heading, describing what changed.

[self]: https://bitbucket.org/atlassianlabs/fe-server/
[self-issues]: https://ecosystem.atlassian.net/jira/software/c/projects/SPFE/issues/
[needs-node]: https://docs.npmjs.com/getting-started/installing-node
[needs-yarn]: https://yarnpkg.com/lang/en/docs/install/
[jest]: https://jestjs.io/