Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
244 lines (183 loc) · 7.4 KB

CONTRIBUTING.md

File metadata and controls

244 lines (183 loc) · 7.4 KB

Contributing to Kadena.js

Table Of Contents

  • Development
  • Tests
  • Making a Pull Request
  • Conventions
  • Publishing Packages

Do you want to file a bug? Please open a new issue.

Development

Install Node.js if you haven't already.

As an external contributor, you will need to fork the repo before you can contribute. Then you can clone the repository and install dependencies:

git clone git@github.com:kadena-community/kadena.js.git
cd kadena.js
pnpm install
pnpm build

Troubleshooting

Running into issues? Please see if the issue has a solution in Troubleshooting.

Switch branches

Depending on the changes, you may need to invoke the following commands when switching branches to keep everything in check:

pnpm install
pnpm build --filter <package name>

Tests

pnpm test               # Run all tests, or inside package directory
pnpm run test --watch   # Keep running tests during development

Making a Pull Request

Before making a pull request, please discuss your ideas first. This will optimize your time and the review process.

Conventions

Git/GitHub

Changelogs

Add a Changelog

When wrapping up a PR you should add one or more changelog entries:

pnpm changeset

Decide for each package wether the changes are relevant to the consumer of the package(s) and how their version should be bumped (patch, minor or major). You can edit the created Markdown file in the .changeset folder. Use none to not bump the version at all.

Recommended reading: Introducing Changesets: Simplify Project Versioning with Semantic Releases

Authoring Changelogs

To keep everything clear for ourselves and our end users, we have a "changelog etiquette". Only include changes that affect the consumer of your package/app/product. It's not a commit log. Write descriptions that are understandable from the consumers' perspective:

  • Start descriptions with action verbs like "Add", "Remove", "Deprecate", "Fix", "Improve", "Update".
  • Avoid the term "bug", use "issue" instead.
  • Add GitHub issue numbers when fixing those.
  • When referring to public API changes, use backticks and parentheses for code like function names and classes (e.g. createClient(), new TransactionBuilder(), hash).
  • Upgrades should be documented with old and new version numbers.
  • Avoid trailing periods (unless in a description below the commit title).

Examples:

  • Deprecate the doSomething() API function.
  • Use doSomethingBetter() instead.
  • Fix issue where ExampleWidget API did not handle dates correctly (fix #81)
  • Improve the diagnostic logging when running in advanced mode.
  • Upgrade from react@15 to react@16-beta release of the flexible panels feature

(Credits: rushjs.io/pages/best_practices/change_logs)

If you don't see a need for authoring changelogs for your package (e.g. a PoC or packages without consumers), add it to .changeset/config.json#ignore.

Code

This repository uses a combination of TypeScript, ESLint and Prettier to adhere to coding standards. We try to automate and auto-fix as much as possible using the following commands:

pnpm build
pnpm lint
pnpm format

Note that lint and format are separated tasks (read more at linting vs formatting).

Run from root to apply to all packages, use --filter for a selection, and run from any package folder to apply it only there.

See Filters for more details.

For everything else, please discuss.

Workflow

You are expected to install your own workflow the way you like it. For example, some developers like to auto-format code "on save", others before they commit or push their changes. That's why this repository does not auto-install Git hooks.

Publishing Packages

To publish a new version of updated packages, please make sure you:

  • are part of the @kadena npm organization
  • have push rights to this repository's main branch
  • are on a clean main branch

We're using Changesets for our release process. The default process is enabled by merging the latest open pull request titled "[ci] Release".

The manual process in How do I run the version and publish commands? is repeated here:

  1. Check out and pull main
  2. Update changelogs and bump versions
  3. Create a new branch and open a "version bump" PR
  4. Merge PR to main
  5. Build and publish from main
git checkout main
git pull
git checkout -b chore/release-packages
pnpm changeset version
git commit -m "Update changelogs and bump versions"
git push

Create a pull request and get it merged to main. Then we can publish:

git checkout main
git pull
pnpm turbo build lint test --force
pnpm changeset publish # Use your npm OTP token
git push --tags

Publishing Apps

Apps are published manually. To publish a new version of an app, please make a PR to the relevant release/<app-name> branch, where <app-name> is the short app name (without @kadena/).

Regular release

For regular releases make a PR from main -> release/<app-name>.

Hotfix

Create a hotfix from the release/<app-name> branch and publish it to the release branch

  1. Checkout branch release/<app-name>.
  2. Create a new branch a-branch from release/<app-name>. 
    git checkout -b a-branch
  3. Make the necessary changes.
  4. Push the branch to the remote. 
    git push origin a-branch
  5. Create a PR from a-branch -> release/<app-name>.
  6. Get a review on the PR.
  7. Merge the PR.
  8. Create a new PR from release/<app-name> -> main to keep the main branch up.
  9. Get a review on the PR.
  10. Merge the PR

Vercel configuration is setup so it'll ONLY release the app when it's pushed to release/<app-name>.

How does it work?

  • We've protected the release/* branches so no one can push directly to them.
  • We modified Vercel config for each app to only deploy when the branch is release/<app-name>.
  • When a PR is merged to release/<app-name>, Vercel will automatically deploy the app