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:
- Code of Conduct
- Issue Reporting Guidelines
- Pull Request Guidelines
- Development Setup
- Project Structure
- Contributing Project Tests
- Financial Contribution
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!
-
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 themain
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.
- If you are resolving a special issue, add
-
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.
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:
- TypeScript as the development language
- Babel for bundling
- Mocha for unit testing
- Prettier for code formatting
The build
script builds all public packages.
The test
script simply calls the mocha
binary, so all Mocha CLI Options can be used.
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.
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 tosrc
for project structure. -
config/awesome-project/index.js
: The configuration corresponding to your test project. -
balm.env.js
: updateBALM_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.
As a pure community-driven project without major corporate backing, we also welcome financial contributions via OpenCollective.