Contributing to BalmJS

February 11, 2022 · View on GitHub

BalmJS is an open source project that accepts contributions from community members.

If you’ve never contributed to an open source project before, take a look at GitHub’s Contributing to Open Source on GitHub to learn some of the basics.

Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Issue Reporting Guidelines

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to the GitHub repository for that platform.

Even better: propose a fix with a pull request and link it to the issue!

Pull Request Guidelines

  • The main branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the main branch.

  • Checkout a topic branch from a base branch, e.g. dev, and merge back against that branch.

  • If adding a new feature:

    • Add accompanying test case.
    • Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it.

  • If fixing a bug:

    • If you are resolving a special issue, add (fix #xxxx[,#xxxx]) (#xxxx is the issue id) in your PR title for a better release log, e.g. update entities encoding/decoding (fix #1024).
    • Provide a detailed description of the bug in the PR. Live demo preferred.
    • Add appropriate test coverage if applicable.

  • It's OK to have multiple small commits as you work on the PR - GitHub can automatically squash them before merging.

  • Make sure tests pass!

  • Commit messages must follow the commit message convention. Commit messages are automatically validated before commit.

  • No need to worry about code style as long as you have installed the dev dependencies - modified files are automatically formatted with Prettier on commit.

Development Setup

You will need Node.js version 12+, and Yarn 1.x.

After cloning the repo, run:

$ yarn # install the dependencies of the project

A high level overview of tools used:

Scripts

yarn build

The build script builds all public packages.

yarn test

The test script simply calls the mocha binary, so all Mocha CLI Options can be used.

Project Structure

This repository employs a monorepo setup which hosts a number of associated packages under the packages directory:

  • balm-core: The BalmJS workflow compiler core package for global.

  • balm: The BalmJS workflow runtime core package for local.

Contributing Project Tests

test-workspace
├─┬ config
│ └─┬ awesome-project
│   └── index.js
├─┬ awesome-project
│ └── ...
├── src
├── balm.env.js
└── package.json

  • awesome-project: Create a test project (e.g. vue), please refer to src for project structure.

  • config/awesome-project/index.js: The configuration corresponding to your test project.

  • balm.env.js: update BALM_ROOT for your local development environment

  • update package.json scripts:

    • "awesome:dev": "balm --config config/awesome-project"
    • "awesome:prod": "balm -p --config config/awesome-project"

  • Let's enjoy!

NOTE: Before starting your project, remember to run yarn build in the repo root directory.

Financial Contribution

As a pure community-driven project without major corporate backing, we also welcome financial contributions via OpenCollective.