Skip to content

Latest commit

 

History

History
180 lines (123 loc) · 5.42 KB

CONTRIBUTING.md

File metadata and controls

180 lines (123 loc) · 5.42 KB

Contributing to Xception

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

Xception relies on typescript and other tools for building and testing. Therefore, it's important that you have all the toolsets 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 install

Testing Xception in other projects

If you want to test any changes to Xception in your project before committing it, you can follow the steps:

  1. Run npm link under the Xception folder
  2. Install the development version of Xception in your project via npm link xception
  3. Make changes to Xception and see the effect by running npm run build to transpile the typescript code into javascript

NOTE: By running npm link, it makes the Xception available globally to other projects.

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.

Code Standard

This project employs code standard rules exported from presetter-preset, 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>: <subject>
<BLANK LINE>
<body>

Example

feat: new awesome feature

BREAKING CHANGE: something will change the behaviour

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
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

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 Testing

If you want to test Xception in your local projects, you can build the library and make it available locally by running:

$ npm link

Release

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

# 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.