Please install following development prerequisites. You also need a GitHub account for contribution.

• Git
• Node.js
• pnpm

Forking a repository allows you to work with HonKit codebase without special permission to the HonKit repository itself.

1. Navigate to HonKit repository

2. In the top-right corner of the page, click Fork button

3. Create a clone of the fork locally in your terminal:

   $ git clone --recursive https://github.com/YOUR_ACCOUNT/honkit YOUR_FORKED_REPOSITORY

See Fork A Repo: GitHub Help for further detail.

After getting your clone, you can start playing with HonKit.

1. Change directory to your clone:

   $ cd YOUR_FORKED_REPOSITORY

2. Install dependencies and build packages:

   $ pnpm install

3. Run build:

   $ pnpm run build

Under the hood, HonKit uses pnpm workspaces to manage multiple packages:

• packages/*
• packages/@honkit/*
• examples/*

If you are new to pnpm workspaces, it seems to add another layer of complexity, but it's simpler than you think; you can edit codes, run tests, commit changes, etc. as usual in most cases.

Note that pnpm install also builds a codebase, you can manually build by running pnpm run build.

Before adding changes to your clone, please create a new branch (typically called feature branch). Changes made to feature branch don't affect or corrupt master branch so you will feel safe. In Git, creating a branch is easy and fast:

$ git checkout -b your-new-feature

You have your feature branch with working HonKit then it's time to start making changes! Edit codes with text editor of your choice and add commits as you work on. Please don't forget to add or modify test cases and documents according to your changes.

This repository uses Prettier for code formatter. We use lint-staged and husky to make coding style consistent before commit, but if you have your own Git hooks locally, these setup doesn't work. In such case, please run Prettier manually as below after making changes.

• Run Prettier to reformat code:

  $ pnpm format

We use Angular Convention for commit message.

In order to make repository history clean, please use the following guideline as possible as you can. It also enables us creating comprehensive changelog semi-automatically.

                      component        commit title
       commit type       /                /
               \        |                |
                feat(rule-context): add template url parameter to events
                (a blank line)
       body ->  The `src` (i.e. the url of the template to load) is now provided to the
                `$includeContentRequested`, `$includeContentLoaded` and `$includeContentError`
                events.

referenced  ->  Closes #8453
issues          Ref. #8454

• commit type:
  • docs: create or update document
  • feat: add new feature
  • fix: fix a bug
  • style: change formatting
  • perf: performance related change
  • test: update on tests
  • chore: housekeeping
  • refactor: refactoring related change
• component: package or file name
• commit title:
  • Limit to 50 characters including commit type and component (as possible as you can)
  • Do not capitalize first character
  • Do not end with a period
  • Use imperative mood, in present tense; commit title should always be able to complete the following sentence:
    • If applied, this commit will commit title here
• body:
  • Separate from subject with a blank line
  • Wrap texts at 72 characters
  • Explain what and why, not how
  • GitHub flavored Markdown is ok to use
  • Start with BREAKING CHANGE: when you made significant change in the commit (see versioning section below).

Example commit message:

test(formatter): check types while testing

- Add strict type check option to `ts-node` to make sure future
  interface changes will be took into account while running test.
- Update test case for interface changes made at #430.

Closes #448.

Please see Commit Message Format and How to Write a Git Commit Message for detail.

We have some type of tests. You should run at least unit test before submitting a pull request.

All tests should be run at the top directory of your fork.

Run tests for all packages:

$ pnpm test

While developing, it would be good to run package level unit test since it will run faster:

$ cd packages/PACKAGE
$ pnpm test

After finishing your changes and unit tests or documentation test ran fine, you can push your feature branch to GitHub. Please see GitHub Help for detail but typically, run git push at your terminal.

$ git push origin feature-branch

Then follow another GitHub Help to create a pull request.

Once a pull request has been created, it will initiate continuous integration builds and we can work on your changes. You can push additional commits to your fork according to feedback.

After all participants on pull request are satisfied to the changes, we will merge your code into the HonKit master branch. Yay!

HonKit has a continuous benchmark:

• https://honkit.github.io/honkit/dev/bench/

A Maintainer releases a new version of HonKit by following way.

1. Checkout release branch

# checkout release branch like "release/2019-10-10"
git checkout -b "release/$(date '+%Y-%m-%d')"

2. Version up and Update CHANGELOG via versionup script

npm run versionup:* script update version and generate CHANGELOG.md

# bump version and update changelog
npm run versionup
## Also, available npm run versionup:{patch,minor,major}
# push the changes to release branch
git push origin HEAD -u

3. Create a Pull Request and Review the release

Create a Pull Request from the release branch, and we will review it.

📝 GitHub Release page use this pull request.

• Pull Request's title = Release title
• Pull Request's body = Release body

4. Merge the Pull Request

Finally, GitHub Actions(CI) publish it to npm and dockerhub automatically.