Skip to main content

Contributor Guideline

It's very nice to have your support. I can spend about 10h/week for this project, so your help is very important to make this framework better.

1. How can you get involved?#

To provide easy to use and scalable framework, there are many tasks you can help:

  • Report bug, open feature request to tell me how can i help you.
  • Modularize libraries with @cellularjs/di so it can integrate with CellularJS more easily.
  • Edit document, submit pull request resolving issues.
  • Create sample applications that combine CellularJS with current Node.js ecosystem.
  • ...
note

CellularJS use GitHub project to manage its tasks, you can see it here.

2. Setup project#

  • You need to have Node.js >= 16.
  • CellularJS use Yarn as package manager, let install it:
    npm install --global yarn
  • Fork CellularJS into your Github account.
  • Clone source from your fork:
    git clone https://github.com/{your_username}/cellularjs.gitcd cellularjs
  • Set CellularJS as upstream for synchronize code later:
    git remote add upstream https://github.com/cellularjs/cellularjs.git
  • Install packages with Yarn(Always use this command to update packages):
    yarn --frozen-lockfile

3. Workflow#

note

For changes that will break current behavior, please open new issue/feature request for discussion first.

3.1. Synchronize code with CellularJS#

At previous step, if you have setup upstream, now you can synchronize code with below command.

(If you have just setup this project, you may not need to synchronize code with CellularJS's master branch now.)

# Update local master with CellularJS master branchgit checkout mastergit pull --rebase upstream master
# Update your remote master branchgit push origin master# or, if you have rebased: git push origin master --force-with-lease (DO NOT use -f) 
# Back to your working branchgit checkout you_working_branch
# Update code with local master branchgit rebase -i master

3.2. Create working branch#

CellularJS use master as its main branch to develop upcoming version, you need to checkout from this branch to add new code.

Example:

git checkout mastergit checkout -b you_working_branch

3.3. Run test before commit#

After adding new code and appropriate tests, you need to run test before commit.

You need to build CellularJS packages, this is because a package can depend on others.

yarn build

Now you can run test:

# Run test cases of all packages without code coverage report.yarn cmd:test
# Or, run test cases of all packages with code coverage report.yarn cmd:coverage
tip

In develoment phase, you can run test of specific package like below example:

yarn cmd:test --scope @cellularjs/net

3.4. Commit code#

note

It will run eslint when you commit, please fix all style issues if you got some.

note

Please use squash to avoid redundant commits.

CellularJS use conventional commits to enforce commit rule, please have a look at the reference link for more information. Overall, standard commit will look like this:

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

Valid type:

  • chore: Update that make no production code change.
  • docs: Update document, JSDoc.
  • feat: New feature.
  • fix: Bug fix.
  • perf: improve performance.
  • test: Add/edit test.

Valid scope can be:

  • empty, when you don't update packages.
  • package name: di, net, cli, ...

Examples:

  • new feature: "feat(di): allow to import exported module automatically".
  • bug fix: "fix(net): ignore .d.ts file not *d.ts".
  • add test case: "test(di): add test case for unhappy path with getModuleMeta".
  • ...

3.5. Submit your pull request#

  • Again, make sure you add appropriate test and all tests are passed.
  • Make sure your code is synchronize code with CellularJS's master branch.
  • Push changes to your fork
  • Open a PR in CellularJS repository and wait for review(It may take up to 2 days for starting review).