Skip to content

Latest commit

 

History

History
203 lines (141 loc) · 6.85 KB

CONTRIBUTING.md

File metadata and controls

203 lines (141 loc) · 6.85 KB

Contributing to Presetter

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

The Essential

Presetter relies on typescript and other tools for building and testing too. Therefore, it's important that you have all the tools installed before making any change to the code. But setting up the code base is easy, just follow these steps:

  1. Clone this repo
  2. Run npm link

NOTE: By running npm link, it makes the presetter CLI available globally, so you easily run tests and lint your code during development.

Project Structure

This repo is a monorepo. It contains the code for presetter and a simple preset. Here's a quick guide to the content of the monorepo.

Package Description
presetter The core of presetter containing all the logic and the CLI utility
presetter-preset-essentials A battery-loaded preset for building presetter, containing typescript and more
presetter-preset-strict An extension of presetter-preset-essentials with stricter rules
presetter-preset-react An opinionated preset for building a React project
presetter-preset-rollup An advanced preset for setting up rollup for code bundling
presetter-preset-web An example pure bundle preset for building a web project

Development

We write code in test-driven development (TDD) approach.

All tests are hosted under the spec folder, with the same structure as the source folder so that tests are easy to be located. In general, each source file should have its own test file.

Requirement

Since presetter 2.0, we have migrated to npm workspace. This implies that you would need npm 7.20+ to start development. If your system doesn't have npm 7.20+, you can achieve it by using nvm with node 16.6+.

Code Standard

This project employs code standard rules exported from presetter-preset-essentials, which mostly follow the recommended rules from

Commit

To allow us to release in semantic versioning, we adopt the Conventional Commits standard for commit messages.

A commit message should be structured as follows:

<type>(<package>): <subject>
<BLANK LINE>
<body>

Example

feat(presetter): new awesome feature

BREAKING CHANGE: something will change the behavior

List of types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
  • revert: Reverts a previous commit

Pull Request Submission

This project follows GitHub's standard forking model. Please fork the project in order to submit pull requests.

Obviously, PRs must be mergeable, rebasing first against the latest master. The number of commits will ideally be limited in number, unless extra commits can better show a progression of features.

IMPORTANTLY, make sure the following are achieved:

  • commit messages must be worded clearly
  • the reason for any PR must be clearly stated by either linking to an issue or giving a full description of what it achieves.
  • all commits must follow the conventional commit standard
  • a test must shipped with any PR, if possible
  • 100% coverage must be maintained

Useful Commands

The following contains some useful commands you would need during development. BE AWARE that some of them are meant to run under individual package folder.

Running Unit Tests

To reduce computation consumption, it's recommended to perform unit tests within each package folder by running the following:

Run all tests

# Either under individual package folder or the project root for all packages
$ npm run test

Run all tests when there is any file changes

# Run watch only under individual package folder
$ npm run watch

Watch only some specific test files

# Run watch only under individual package folder
$ npm run watch -- spec/<file.spec.ts>

Coverage

Run the coverage script to make sure the coverage is 100% before committing, then open coverage/lcov-report/index.html located in each individual package folder in your browser.

# Either under individual package folder or the project root for all packages
$ npm run coverage

Building

To transpile typescript to javascript, run the following:

# Either under individual package folder or the project root for all packages
$ npm run build

Linting

To check the code standard and fix fixable issues automatically, run the following:

# You can run lint either under individual package folder or the project root for all packages
$ npm run lint

Local CLI Testing

If you want to test out presetter globally, you can build everything and make the CLI available globally by:

$ npm link

Release

We follow semantic versioning and a release can be triggered by running either the following:

# bump the version and release as canary
$ npm run next

# release as a stable version
$ npm run release

NOTE: Upon releasing, automatically a versioning tag is issued and the change logs got updated. When the commit is pushed to the origin, the automated CI/CD system will then publish the package to npm automatically without any manual intervention.