# Developing BeRun

Developing and contributing to BeRun, its core presets, and middleware is done through our monorepo located at
https://github.com/bestyled/berun. The code is broken up into a couple different sections:
packages and documentation.

_Note: In this guide, commands executable from the command line are prepended with `❯`. Lines not starting
with this symbol show sample console output from running the previous command._

## Requirements

Developing for berun requires:

- Node.js v8.3+
- Yarn v1.2.1+, installation instructions at https://yarnpkg.com/en/docs/install
- git, GitHub account

## Getting started

The first step to start developing berun is
[forking the repository to your own GitHub account](https://help.github.com/articles/fork-a-repo/).

<a href="https://github.com/bestyled/berun/fork" target="_blank">Fork bestyled/berun on GitHub</a>

Once that is done, you can clone your copy of the repository on your computer, replacing `USER` with the username
of the account you forked the repository to:

```bash
❯ git clone git@github.com:USER/berun.git
❯ cd berun
```

Upon cloning, you should install dependencies:

```bash
❯ yarn
```

This uses the yarn workspaces feature to create symlinks between the various packages, simplifying local development.

## Development commands

The package.json for berun defines several commands to assist in the development and deployment process.

---

`link:all`

Runs `yarn link` against all packages in the berun monorepo. This allows you to run `yarn link <package>`
anywhere on your system for berun packages, making testing of the packages simpler in local projects.

```bash
❯ yarn link:all

# Elsewhere on your system
❯ yarn link @berun/preset-react
```

---

`test`

Runs the unit test suite against all packages in the monorepo. For the most part
the intent of the unit tests is to ensure that packages do not throw errors
when being required or used as middleware by BeRun. These tests typically
do not ensure that their middleware produces the expected output, instead
leaving this functionality for integration tests via `test:create-project`.

---

`test:create-project`

Runs the integration test suite by determining correct output of the
`create-project` CLI tool and ensuring that package.json scripts do not throw.
This test requires a local [verdaccio](https://www.verdaccio.org/) instance
to be running, and this is ensured in CI via the
`scripts/test-create-project-ci.sh` script. Typically this command is only used
in CI, with the unit tests being run locally via `yarn test`. If you do run
this command locally by setting up verdaccio locally as well, ensure that
you revert back any changes you make to your local registry when finished with:

```bash
yarn config set registry https://registry.yarnpkg.com
``` 

---

`changelog`

Generates a changelog for the `bestyled/berun` GitHub repository. This changelog is output to a
`CHANGELOG.md` file in the root of the repository.

```bash
❯ yarn changelog
```

---

`docs:bootstrap`

Installs the Python dependencies required to build the documentation. You may wish to active a virtualenv first.

```bash
❯ yarn docs:bootstrap
```

---

`docs:serve`

Starts a local development server which builds the documentation in `docs` and serves it on port 8000.

```bash
❯ yarn docs:serve
```

## Making changes

When you make changes to berun, you should make them in a branch separate from `master`. Start from the
master branch and create a new branch for your changes.

_Example: You want to create a core preset for JavaScript Standard Style. You need a new branch for this work._

```bash
❯ git checkout -b standard-style
Switched to a new branch 'standard-style'
```

While making changes, be sure to test your code out for expected operation. If possible or applicable, write a
test that can verify these changes in the future.

## Submitting a pull request

Once you are satisfied with your changes, you should commit them and submit a pull request. Use `git add`
in order to add files that should be committed. Give your changes a descriptive but not overly verbose message.

```bash
❯ git add .
❯ git commit -m "Feature: Adding new core preset for JavaScript Standard Style"
❯ git push origin standard-style
```

Now if you open the GitHub page for your repository, GitHub should display a button to open a pull request for
the branch and commit you just pushed. When filling out the details of the pull request, try to be as descriptive
as possible, following our detailed [contribution guidelines](./index.md).

### Congrats!

You just made a contribution to BeRun! We are so happy to have your help! 🎉

## Receiving updates

If you need to update your local copy of berun to be in sync with the main berun repository, you
will want to fetch upstream changes. Add the main berun repo as an upstream to your local copy, then fetch
the latest changes from the master branch.

```bash
❯ git checkout master
❯ git remote add upstream https://github.com/bestyled/berun.git
❯ git pull upstream master
```
