Skip to content

Latest commit

聽

History

History
141 lines (95 loc) 路 6.96 KB

CONTRIBUTING.md

File metadata and controls

141 lines (95 loc) 路 6.96 KB
Raw

Thanks for showing interest to contribute to Panda CSS 馃挅, you rock!

When it comes to open source, there are different ways you can contribute, all of which are valuable. Here's a few guidelines that should help you as you prepare your contribution.

Setup the Project

The following steps will get you up and running to contribute to Panda CSS:

  1. Fork the repo (click the Fork button at the top right of this page)

  2. Clone your fork locally

git clone https://github.com/<your_github_username>/panda.git
cd panda
  1. Setup all the dependencies and packages by running pnpm install. This command will install dependencies.

If you run into any issues during this step, kindly reach out to the Panda CSS team here: Panda Discord

Development

To improve our development process, we've set up tooling and systems. Panda CSS uses a monorepo structure with the following structure:

Directory Structure

Package Description
cli CLI package installed by the end user
core Contains core features of Panda (utility, recipes, etc)
config Contains functions for reading and merging the panda config
extractor Contains code for fast AST parsing and scanning
generator Contains codegen artifacts (js, css, jsx)
parser Contains code for parsing a source code
is-valid-prop Contains code for checking if a prop is a valid css prop
node Contains the Node.js API of Panda's features
token-dictionary Contains code used to process tokens and semantic tokens
shared Contains shared TS

Tooling

  • PNPM to manage packages and dependencies
  • Tsup to bundle packages
  • Vitest for testing, mostly using snapshots
  • Changeset for changes documentation, changelog generation, and release management.

Commands

pnpm install: bootstraps the entire project, symlinks all dependencies for cross-component development and builds all components.

pnpm dev: starts tsup with watch mode for all packages.

pnpm build: run build for all packages.

pnpm test: run test for all packages.

pnpm release: publish changed packages.

Think you found a bug?

Please conform to the issue template and provide a clear path to reproduction with a code example. The best way to show a bug is by sending a minimal reproduction as a GitHub repo, CodeSandbox, or StackBlitz.

You may wish to use this starter template to help you get going: https://github.com/astahmer/panda-vite-template

Proposing new or changed API?

Please provide thoughtful comments and some sample API code. Proposals that don't line up with our roadmap or don't have a thoughtful explanation will be closed. You can check the existing proposals and our official roadmap here: https://panda-css.canny.io/

Making a Pull Request?

Pull requests need only the 馃憤 of two or more collaborators to be merged; when the PR author is a collaborator, that counts as one.

Commit Convention

Before you create a Pull Request, please check whether your commits comply with the commit conventions used in this repository.

When you create a commit we kindly ask you to follow the convention category(scope or module): message in your commit message while using one of the following categories:

  • feat / feature: all changes that introduce completely new code or new features
  • fix: changes that fix a bug (ideally you will additionally reference an issue if present)
  • refactor: any code related change that is not a fix nor a feature
  • docs: changing existing or creating new documentation (i.e. README, docs for usage of a lib or cli usage)
  • build: all changes regarding the build of the software, changes to dependencies or the addition of new dependencies
  • test: all changes regarding tests (adding new tests or changing existing ones)
  • ci: all changes regarding the configuration of continuous integration (i.e. github actions, ci system)
  • chore: all changes to the repository that do not fit into any of the above categories

If you are interested in the detailed specification you can visit https://www.conventionalcommits.org/ or check out the Angular Commit Message Guidelines.

Steps to PR

  1. Fork of the panda repository and clone your fork

  2. Create a new branch out of the main branch. We follow the convention [type/scope]. For example fix/accordion-hook or docs/menu-typo. type can be either docs, fix, feat, build, or any other conventional commit type. scope is just a short id that describes the scope of work.

  3. Make and commit your changes following the commit convention. As you develop, you can run pnpm pkg <module> build and pnpm pkg <module> test to make sure everything works as expected. Please note that you might have to run pnpm boot first in order to build all dependencies.

  4. Run pnpm changeset to create a detailed description of your changes. This will be used to generate a changelog when we publish an update. Learn more about Changeset. Please note that you might have to run git fetch origin main:master (where origin will be your fork on GitHub) before pnpm changeset works.

  5. Also, if you provide jsx snippets to the changeset, please turn off the live preview by doing the following at the beginning of the snippet: ```jsx live=false

If you made minor changes like CI config, prettier, etc, you can run pnpm changeset add --empty to generate an empty changeset file to document your changes.

Tests

All commits that fix bugs or add features need a test.

Want to write a blog post or tutorial

That would be amazing! Reach out to the core team here: https://discord.gg/VQrkpsgSx7. We would love to support you any way we can.

Want to help improve the docs?

Our docsite lives in the monorepo.

License

By contributing your code to the panda GitHub repository, you agree to license your contribution under the MIT license.