Skip to content

Latest commit

 

History

History
365 lines (236 loc) · 12.7 KB

CONTRIBUTING.md

File metadata and controls

365 lines (236 loc) · 12.7 KB
Raw

Contributing to Qwik

Thank you for taking an interest in contributing to Qwik! We appreciate you! 🫶🏽

Below are the guidelines on how to help in the best possible way.

Submitting an Issue

Before creating a new issue, please search through open issues using the GitHub issue search bar. You might find the solution to your problem, or can verify that it is an already known issue.

We want a bug-free and best-performing project. That's why we take all reported issues to heart. But please be aware that if we can't reproduce the problem, we won't have a way of locating and adequately fixing it.

Therefore, to solve the problem in the best possible way, please create a minimal repository that reproduces the problem with the least possible code explaining and demonstrating the error.

Without enough information to reproduce the issue, we will close it because we can't recreate and solve it.

Triaging Issues

If you're interested in helping out with triaging issues, please follow the Triaging Guide.

Submitting a Pull Request (PR)

Branch Organization

We adopt trunk-based development therefore all Pull Requests are made against the main branch because we do not use separate branches for development or for the versions we release.

Good first issue

The issues marked with Good first issue are a good starting point to familiarize yourself with the project.

Before solving the problem, please check with the maintainers that the issue is still relevant. Feel free to leave a comment on the issue to show your intention to work on it and prevent other people from unintentionally duplicating your effort.

Sending a Pull Request

Before submitting a pull request, consider the following guidelines:

  • Fork the repository into your own account.
  • In your forked repository, create a new branch: git checkout -b my-branch main
  • Make your changes/fixes.
  • Run pnpm fmt to lint the code.
  • Add a changeset with pnpm change if needed (follow this tutorial)
  • Push your branch to GitHub: git push origin my-branch
  • In GitHub, send a pull request to QwikDev:main.

If you aren't sure your PR is ready, open it as a draft to make it clear to the maintainer.

⚠ Troubleshooting PR build issues on CI

Every PR is being automatically merged with main before the CI Github actions run. That's why if the CI checks aren't passing your PR branch is probably not up to date.

For non documentation PRs please do the following:

  1. Merge main into your PR branch
  2. Run pnpm api.update
  3. Run pnpm build.local or pnpm build.full if you made a change to the Rust code
  4. Commit and push any changes as a result of the above steps

Local development

This is the best approach because all required dependencies will be installed in the docker container for you and won't affect your personal configuration in any way.

Prerequisites

You need to have these tools up and running in your local machine:

and either Docker or Nix.

Steps

If you want to use Docker:

Alternatively you can use devcontainers/cli:

  • Install devcontainers following their documentation.
  • In your terminal navigate to the Qwik's project root directory.
  • Then run devcontainer up --workspace-folder .. This command will start a Docker container with all required environment dependencies.

If you want to use Nix:

  • Install Nix on your machine and enable flakes. The DetSys installer makes that easy.
  • run nix develop in the project root.

Nix+Direnv (optional):

You can additionally use direnv to automatically load the dev environment when you enter the project directory.

Using development container without Dev Containers and VSCode

If you would like to make use of the development container solution, but don't use VSCode or Dev Containers, you still can do so, by following steps:

  • Build development container locally: cd .devcontainer; docker build -t qwik-container .
  • Run development container from Qwik project root, binding the directory to container: cd ..; docker run --rm -d --name qwik-container -p 3300:3300 -p 9229:9299 -v $PWD:/home/circleci/project -t qwik-container

Docker command does:

  • Create a new container that is removed once stopped,
  • In daemon mode,
  • With name qwik-container,
  • That exposes the ports 3300 and 9229, and
  • Binds qwik project directory to container working directory.

Podman extras

This section is highly influenced by SO answer: https://serverfault.com/a/1075838/352338 If you use Podman instead of Docker as your containers engine, then you need to know the following:

  • Container runs as user circleci with UID 1001 and GID 1002.
  • As you are accustomed to using Podman, you will need to append :Z to volumes | -v parameter so the command becomes:
$ subuid_size=65536
$ subgid_size=65536
$ container_uid=1001
$ container_gid=1002
$ podman run --rm \
    --user $container_uid:$container_gid \
    --uidmap=0:1:$container_uid \
    --uidmap=$((container_uid + 1)):$((container_uid + 1)):$((subuid_size - $container_uid)) \
    --uidmap=$container_uid:0:1 \
    --gidmap=0:1:$container_gid \
    --gidmap=$((container_gid + 1)):$((container_gid + 1)):$((subgid_size - $container_gid)) \
    --gidmap=$container_gid:0:1 \
    -d --name qwik-container \
    -p 3300:3300 -p 9229:9299 \
    -v .:/home/circleci/project:Z \
    -t qwik-container

Alternative way

If you're not able to use the dev container, follow these instructions:

Installation

These are for a full build that includes Rust binaries.

  1. Make sure Rust is installed.
  2. Install wasm-pack with cargo install wasm-pack .
  3. Node version >= 18.
  4. Make sure you have pnpm installed.
  5. run pnpm install

On Windows, Rust requires C++ build tools. You can also select Desktop development with C++ while installing Visual Studio.

Alternatively, if Rust is not available you can run pnpm build.platform.copy to download bindings from CDN

Development

To build Qwik for local development, install the dev dependencies using pnpm and then do an initial build:

pnpm install && pnpm build.local

Fast build

It will build only Qwik and Qwik City.

pnpm build.core

Custom build

E.g. to build only the react integration:

pnpm build --qwikreact

Run without arguments for all supported flags. Notable:

  • --tsm: typecheck
  • --build: Qwik (you'll probably also need --api)
  • --qwikcity: Qwik City (you'll probably also need --api)
  • --qwikreact: Qwik React
  • --qwiklabs: Qwik Labs
  • --eslint: Eslint plugin

Full build without Rust

It will build everything except Rust prerequisites and the optimizer binaries.

pnpm build.local

Full build

It will build everything, including Rust packages and WASM.

First build might be very slow.

  • Builds each submodule
  • Generates bundled .d.ts files for each submodule with API Extractor
  • Checks the public API hasn't changed
  • Builds a minified core.min.mjs file
  • Generates the publishing package.json
pnpm build.full

The build output will be written to packages/qwik/dist, which will be the directory that is published to @builder.io/qwik.

Run in your own app:

Say you made changes to the repo. After you finished you'd need to run the build command (pnpm build.full/pnpm build).

To use your build in your project, follow these steps:

  1. Inside the root of the qwik project run:

    pnpm link.dist

    or

    pnpm link.dist.npm

    or

    pnpm link.dist.yarn

  2. Inside the root of your project run:

     pnpm install
 pnpm link --global @builder.io/qwik @builder.io/qwik-city

    or

    npm install
npm link @builder.io/qwik @builder.io/qwik-city

    or

     yarn install
 yarn link @builder.io/qwik @builder.io/qwik-city

If you can't use package linking (npm link) just copy the contents of packages/qwik/dist into your projects' node_modules/@builder.io/qwik folder, and/or the contents of packages/qwik-city/lib into your projects' node_modules/@builder.io/qwik-city folder.

Test against the docs site:

  1. At the root of the Qwik repo folder run:
pnpm install
  1. Run the docs site:
pnpm docs.dev

To open the test apps for debugging run:

pnpm serve

Unit Tests Only

Unit tests use vitest

pnpm test.unit

E2E Tests Only

E2E tests use Playwright.

To run the Playwright tests headless, from start to finish, run:

pnpm test.e2e.chromium

Finally, you can use pnpm --filter command to run packages' commands, for example:

pnpm --filter qwik-docs start

More commands can be found in each package's package.json scripts section.

Updating dependencies

To update all dependencies, run:

pnpm deps

This will show an interactive UI to update all dependencies. Be careful about performing major updates, especially for the docs site, since not all functionality has test coverage there.

Starter CLI create-qwik

Pull Request

Adding a changeset:

Whenever you make a change that requires documentation or a new release, you should add a changeset. This will help us to keep track of changes and generate meaningful release notes and changelog files.

You create a new changeset file by running:

pnpm change

For your convenience, we prepared a video tutorial that covers the process of adding a changeset:

📽 TUTORIAL: Adding a changeset

Pre-submit hooks

The project has pre-submit hooks, which ensure that your code is correctly formatted. You can run them manually like so:

pnpm lint

Some issues can be fixed automatically by using:

pnpm fmt

Releasing (core-team)

  1. Run pnpm release.prepare, which will test, lint and build.
  2. Use the interactive UI to select the next version, which will update the package.json version property, add the git change, and start a commit message.
  3. Create a PR with the package.json change to merge to main.
  4. After the package.json with the updated version is in main, click the Run Workflow button from the "Qwik CI" GitHub Action workflow.
  5. Select the NPM dist-tag that should be used for this version, then click "Run Workflow".
  6. The GitHub Action will dispatch the workflow to build @builder.io/qwik, @builder.io/qwik-city and each of their submodules, build WASM and native bindings, and validate the package before publishing to NPM.
  7. If the build is successful and all tests and validation passes, the workflow will automatically publish to NPM, commit a git tag to the repo, and create a GitHub release.
  8. ⚡️