Skip to content

Latest commit

 

History

History
132 lines (82 loc) · 5.16 KB

CONTRIBUTING.md

File metadata and controls

132 lines (82 loc) · 5.16 KB
Raw

Contributing to Linaria

Code of Conduct

We want this community to be friendly and respectful to each other. Please read the full text so that you can understand what actions will and will not be tolerated.

Our Development Process

The core team works directly on GitHub and all work is public.

Development workflow

Working on your first pull request? You can learn how from this free series: How to Contribute to an Open Source Project on GitHub.

  1. Fork the repo and create your branch from master (a guide on how to fork a repository).

  2. Linaria uses Pnpm for running development scripts. If you haven't already done so, please install Pnpm.

  3. Run pnpm bootstrap to setup the development environment.

  4. When working on the code, you can use the watch mode to watch and compiles changed files:

    pnpm watch

  5. If you've added code that should be tested, add tests.

  6. You can test the changes you are making in our website located under the website/ folder in the repo.

  7. If you've changed APIs, remember to update the documentation under docs/.

Working on the website

If you are making changes to the website, test the website folder and run the server to check if your changes are being displayed accurately. To run the development server with live reloading, run:

pnpm website start

Commit message convention

We follow the conventional commits specification for our commit messages:

  • fix: bug fixes, e.g. fix wrong classname generated by babel plugin.
  • feat: new features, e.g. add support for a config file.
  • refactor: code refactor, e.g. split the babel plugin into multiple visitors.
  • docs: changes into documentation, e.g. add usage example for styled tag.
  • test: adding or updating tests, eg unit, snapshot testing.
  • chore: tooling changes, e.g. change the eslint config.
  • BREAKING CHANGE: for changes that break existing usage, e.g. change the API or behaviour.

Our pre-commit hooks verify that your commit message matches this format when committing. If you are working on some in progress commits and don't care about the pre-commit hook, pass the --no-verify (-n) flag to git when committing (e.g. git commit -n -m "wip").

Linting and tests

We use eslint with prettier for linting and formatting the code, and jest for testing. Our pre-commit hooks verify that the linter and tests pass when commiting. You can also run the following commands manually:

  • pnpm typecheck: run tests for typescript definitions.
  • pnpm lint: lint files with eslint and prettier.
  • pnpm test: run unit tests with jest.

Sending a pull request

When you're sending a pull request:

  • Prefer small pull requests focused on one change.
  • Verify that eslint and all tests are passing.
  • Run pnpm changeset to generate a changeset.
  • Preview the documentation to make sure it looks good.
  • Follow the pull request template when opening a pull request.

How to try a development build of Linaria in a project

To link linaria on the command line to local copy in a development build:

cd /path/to/your/linaria_clone/
yarn
yarn link
cd /path/to/test_project/
yarn link linaria

To unlink it:

yarn unlink linaria

Debugging and deep dive into babel plugin

To understand what is actually going in under the hood of Linaria we recommend to first read the top-level How it works. Then you can run Linaria in debug mode for a specific file from you project and see step-by-step logs informing what is happening.

DEBUG=linaria* LINARIA_LOG=debug npx babel -d dist PATH_TO_COMPONENT

In example we use npx to run babel, but you can also put this script into package.json with removed npx to run it.

You will see how the babel part of Linaria work, result JS file will be stored in dist directory. You will not see the resulting CSS file, because this is the role of next layer - bundlers (CSS content is stored in babel metadata to be consumed by bundler).

Publishing a release

We use release-it to automate our release. If you have publish access to the NPM package, run the following from the master branch to publish a new release:

yarn release

NOTE: You must have a GITHUB_TOKEN environment variable available. You can create a GitHub access token with the "repo" access here.

Reporting New Issues

The best way to get your bug fixed is to provide a reduced test case. Please provide a public repository with a runnable example.

How to Get in Touch

  • Callstack Open Source Discord - #linaria.

Code Conventions

We use Prettier with ESLint integration for linting and formatting. To fix any auto-fixable lint or matting errors, run:

pnpm lint -- --fix

License

By contributing to Linaria, you agree that your contributions will be licensed under its MIT license.