Skip to content

Latest commit

 

History

History
134 lines (95 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

134 lines (95 loc) · 4.23 KB

Contributing

You are more than welcome to contribute to the tools here!

As a starter, you can:

  1. File an issue in this repository with your ideas, bugs or suggestions. Please let the contributors know if you start working on a long-term project. It is hard to coordinate different efforts, if we are unaware of them.
  2. If there is enough consensus for the work, or the work is sufficiently small, you are ready to start working on it!
  3. Fork the repository to your own repository
  4. Follow the setting up a development environment instructions
  5. Make your changes
  6. Create a Pull Request (PR) from your fork to this repository
  7. Go through PR review(s) with the maintainers
  8. Eventually, merge the contribution 🎉

Setting up a development environment

Step 1: Get Node.js

We recommend to use nvm for managing your Node.js version. We recommend following the deeper shell integration section, to ensure that nvm is invoked automatically per directory.

nvm install
nvm use

This ensures that you will always be using the node version that is specified in the repository's .nvmrc file.

Step 2: Install pnpm

We use pnpm for package management.

We recommend that you install pnpm via corepack, which is node's built-in way of managing package managers:

corepack enable

This ensures that your pnpm version will be in sync with the one specified in the repository's package.json packageManager field.

Step 3: Install and Run Tests

# install dependencies for all packages
pnpm install

# run tests for all packages
pnpm test

You are set up! Follow "Linking local packages to your application", for how to develop against an existing application.

Linking local packages to an application

While developing library packages, it is useful to develop them locally, and link them against a target application.

"Linking", in this case, means using a locally-built version as a dependency in another application.

This section uses the following example:

  • The relevant package is @svg-use/core
  • The source repository path is /Users/user/svg-use
  • The target application path is /Users/user/my-app

Using the file: protocol

We recommend that you use the file: protocol to link the dependency to the target application.

The file: protocol ensures that peer dependencies are resolved according to the target application's node_modules, which is critical especially for react, which requires the same version across an application.

The file: protocol is available in pnpm, yarn and npm.

In your target application package.json, add:

{
  "dependencies": {
    "@svg-use/core": "file:/Users/user/svg-use/packages/core"
  }
}

Finally, install dependencies in the target application:

pnpm install

You are set up! Any changes you make to the relevant package will be reflected to the target application (after building the relevant package). You only need to link the package once.

Developing and re-building

Most of the time, when developing the relevant package, you would run a watcher that re-builds it automatically.

In the source repository, run the dev command for the relevant package, and its dependencies:

pnpm --filter "core..." run dev

(Note that --filter "core..." is pnpm's syntax for running a command in a workspace package, as well as its dependencies)

One-off builds

You can alternatively run a production build for the relevant package and its dependencies:

pnpm --filter "core..." run build