---
name: Contributing
---

# Contributing

### So, you want to contribute to BeRun?

Thank you for wanting to help out with BeRun! We are very happy that you want to contribute, and have put together
this guide to help you get started. We want to do our best to help you make successful contributions and be part of our
community.

### Participation Conduct

In order to ensure everyone has a fair, pleasant, and inclusive experience contributing to BeRun, we ask that you
abide by our [community participation guidelines](./code-of-conduct.md), based on the
[Contributor Covenant](https://www.contributor-covenant.org/). Please read and understand it for everyone's benefit.

Following these guidelines helps to communicate that you respect the time of the developers managing
and developing BeRun. In return, we will show you respect in addressing your issue, assessing changes,
and helping you finalize your pull requests.

### What we need

There is always room for improvement and expansion in BeRun. Some things that could always help:

- Triaging and fixing bugs
- Adding tests to BeRun which can help ensure it functions properly with new contributions
- Keeping core presets up to date with the best webpack and Babel options
- Expanding documentation, writing tutorials, and creating example projects
- Something else, of course!

### What we probably don't need

While we are happy to review **any** contribution, there are some things that are best left as an external project:

- _Additional presets_. While berun does contain a number of core presets, we created and maintain these because
they were core to most of the projects we personally work on. If there are more presets you believe should be maintained
by the core, then feel free to raise an issue and we can discuss! Most likely though, additional presets can be
externally maintained and published to npm. It still has the same reach potential as bringing it into the core, without
raising the maintenance burden for BeRun unnecessarily.
- _Scaffolding and boilerplates._ The goal of BeRun is to remove over-reliance on boilerplates, instead opting to
push users into consuming presets. BeRun itself will not add commands to scaffold out new projects or create
boilerplate repositories. We do keep a collection of examples-as-documentation for getting started with BeRun
presets, but do not wish to govern project structure more than necessary. These types of projects can be maintained
externally.

## Support

BeRun team members and contributors are here to help you! Should you need assistance or have questions in using
BeRun or its core presets, please consider asking on our Spectrum channel, Stack Overflow, or other channel rather than
filing issues. We would prefer to keep our GitHub issues clear for bugs, feature requests, discussions, and
relevant information related to its development.

## Guidelines

- Please make a good-faith effort to ensure that code that goes into berun follows the existing patterns and
quality that is already present in the repository.
- Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get
community feedback.
- Strive for code to be readable. Prefer following functional programming paradigms over object-oriented ones where
possible.
- Keep feature versions as small as possible, preferably one new feature per version.

## Getting started

Most contributions will involve working with the berun codebase. Please refer to the [development
documentation](./development.md) for technical details on getting started.

## Filing bugs and issues

When filing an issue, try to answer these questions:

- What version of BeRun are you using?
- Are you trying to use any presets? If so, which ones, and what versions?
- Are you using the Yarn client or the npm client? What version?
- What version of Node.js are you using?
- What operating system are you using?
- What did you do?
- What did you expect to happen?
- What actually happened, contrary to your expectations?

## Feature Requests or Enhancements

Please file an issue describing your request in detail:

- What is the goal of the change?
- What are the pros and cons of the change?
- Could this dramatically improve the experience of our users?

Please be open to discussion, and we will respect your time by fairly evaluating your request. In the event that your
request is deemed to not be acceptable to move forward, please understand that isn't a criticism of you as a person,
but rather that the idea in its present form may not be right at this time. We respect you and your ideas, and will
always encourage contributors to continue to make proposals.

## Code review process

Code is reviewed by BeRun team members for quality, conformance to existing patterns, and functionality.
