It is essential to the development of PixiJS React that the community is empowered to make changes and get them into the library. Here are some guidelines to make that process silky smooth for all involved.
Pixi React follows semantic versioning. We release patch versions for bugfixes, minor versions for new features, and major versions for any breaking changes. When we make breaking changes, we also introduce deprecation warnings in a minor version so that our users learn about the upcoming changes and migrate their code in advance.
To report a bug, request a feature, or even ask a question, make use of the GitHub Issues section for PixiJS React. When submitting an issue please take the following steps:
-
Search for existing issues. Your question or bug may have already been answered or fixed, be sure to search the issues first before putting in a duplicate issue.
-
Create an isolated and reproducible test case. If you are reporting a bug, make sure you also have a minimal, runnable, code example that reproduces the problem you have.
-
Include a live example. After narrowing your code down to only the problem areas, make use of CodeSandbox, jsFiddle, jsBin, or a link to your live site so that we can view a live example of the problem.
-
Share as much information as possible. Include browser version affected, your OS, version of the library, steps to reproduce, etc. "X isn't working!!!1!" will probably just be closed.
NOTE: if you are looking for support, please visit the Discord.
To setup for making changes you will need to take a few steps, we've outlined them below:
-
Ensure you have node.js installed. You can download node.js from nodejs.org. Because pixi uses modern JS features, you will need a modern version of node. We recommend using the version defined in our
.nvmrc
file, which is generally the latest LTS version. You can also usenvm
to manage multiple versions of node installed on your development machine. -
Fork the pixi-react repository, if you are unsure how to do this GitHub has a guides for the command line and for the GitHub Client.
-
Next, run
npm install
from within your clone of your fork. That will install dependencies necessary to build PixiJS React. -
Pixi React is set up as a monorepo, with separate packages for:
- The main library -
packages/react
- The "animated" library, for working with
react-spring
-packages/animated
- Their "legacy" counterparts for compatibility with
pixi.js-legacy
-packages/react-legacy
andpackages/animated-legacy
- The sourcecode for the docs website, built with docusaurus -
packages/docs
Once you have node.js, the repository, and have installed dependencies are you almost ready to make your change. The only other thing before you start is to checkout the correct branch. Which branch you should make your change to (and send a PR to) depends on the type of change you are making.
Here is our branch breakdown:
master
- Make your change to themaster
branch if it is a bugfix with the current version or a backwards-compatible feature.v6.x
,v6.8.x
,v6.7.x
, etc - Make your change to legacy branches (or tags) to patch old releases if your fix only applies to older versions.
Your change should be made directly to the branch in your fork, or to a branch in your fork made off of one of the above branches.
You can test your change by using the automated tests packaged with PixiJS React. You can run these tests by running npm test
from the command line, either from the project root to test all packages or from within an individual package to test only
that package. If you fix a bug please add a test that will catch that bug if it ever happens again. This prevents regressions
from sneaking in.
Commands:
- Run
npm run build
from the project root to build all packages. - Run
npm run lint
from the project root to lint the whole project. - Run
npm run test
from the project root to test all packages. - Run
npm run test:watch
from within an individual package to run tests for that package as you make edits to code.
You can use the docs
package as a way to test Pixi React features are working as expected. From within the docs
package:
- Run
npm run start
to open a browser with a live reloading local version of the docs, navigate through the sections to see live code examples of specific Pixi React components and features. - For now, when making code edits to different packages, you need to manually rebuild them for changes to be reflected in the
docs
- runnpm run build
again to do so.
After you have made and tested your change, commit and push it to your fork. Then, open a Pull Request
from your fork to the main PixiJS React repository on the branch you used in the Making a Change
section of this document.
We use eslint
along with a custom configuration @pixi/eslint-config
for code
formatting and linting. Run npm run lint --fix
after making any changes to the code.
Our linter will catch most issues that may exist in your code. You can check the status of your code styling by simply
running npm run lint
.
- Use 4 spaces for tabs, never tab characters.
- No trailing whitespace, blank lines should have no whitespace.
- Always favor strict equals
===
unless you need to use type coercion. - Follow conventions already in the code, and listen to eslint.
- Ensure changes are eslint validated. After making a change be sure to run the build process to ensure that you didn't break anything.
Code of Conduct is adapted from Contributor Covenant, version 1.4