Skip to content

Latest commit

 

History

History
260 lines (182 loc) · 9.66 KB

CONTRIBUTING.md

File metadata and controls

260 lines (182 loc) · 9.66 KB
Raw

🎉 Contributing to Fabric 🥳

This guide covers all you need to know from the start, for a first time contributor, advancing to the more advanced topics as you continue reading.

🧐 Questions?!?

Questions are legit but that doesn't make them bug reports...
Please refer to available resources (read below) and refrain from opening an issue in such a case.

To find an answer, first search the repository. It contains a lot of useful threads.

Questions might inspire you to improve the docs 🌈 Please do 🌟.

Demos and examples 🤓 can be found on fabricjs.com, jsfiddle, codepen.io and more.

🏷️ Issue Tracker

  • Before You Begin 🎬
    • 📌 Make sure you didn't fall into a known GOTCHA.
    • 🔎 Searching for existing issues and discussions is 🔋 VITAL in order to keep the community in a good state, prevent spamming 👎 and become a skilled fabric dev 🦉.
  • Fill out the 🐛 report with care, it is there for a reason.
  • The Title must be informative, short and 🧿 to the point.
  • Description
    • Describe the issue making sure you are very clear.
    • Add (📎) logs, screenshots or videos if that makes sense.
    • Make an effort explaining yourself!
    • A good description has been read at least 3 times before submitting.
  • Test Case
    • Create a minimal and immediate test case, reproducing the bug.
    • Add relevant explanations.
    • It should be extremely easy for someone to understand your bug and fast to reproduce it. Don't leave it to us to do your part.
    • Bug templates can be found within a bug report.
  • Specify which version of Fabric.js you are using.
  • Upgrade to the latest version before proceeding, your 🐛 may have turned into a 🦋.

These are minimal requirements. Without them issues shall be ⛔.

If it's not a bug OR if you're unsure, start a 🤠 discussion.

Check out Helping Out.

🔦 Fixing typos

Typos are a nasty thing.
Though it may seem insignificant, typo fixes are appreciated!
It's a good and simple way to start contributing.

🔎 Improving Docs

Improving DOCS is SUPER important for everyone.
Even if it's a small fix it is valuable 💎... don't hesitate!

We plan on building a brand new website, stay tuned.

❤️ Helping Out

Answering questions and addressing issues, as well as fixing and adding types (see Pull Requests), are great ways to start contributing to fabric.

🎮 Adding a DEMO

Take a look at an existing demo file.
Create a new file in the same directory (posts/demos/_posts) and follow developing the website.

fabricjs.com (deprecated)

To develop fabric's site you need to clone fabricjs.com in the same parent folder of fabric.js, so that fabric.js and fabricjs.com are siblings.

To start the dev server run npm start:dev inside the fabricjs.com directory (after installing dependencies).

If you are working on windows, check out jekyll docs for further instructions or use WSL.

🐛 Fixing Bugs

🚀 Pull Requests

Fabric is an open source project 🦄 and as such depends on the genuine effort of individuals and the community as a whole. Join Us to make Fabric better 🌺 .

Getting Started

✅ Guidelines

  • Code Style
    Fabric uses prettier to format files and eslint for linting (npm run lint -- --fix).
    To enjoy a seamless dev experience add the Prettier - Code formatter extension via the extensions toolbar in VSCode.
  • ⛔ dist
    Commit changes to source files. Don't commit the generated distribution files.
  • Tests
    PRs must be backed with relevant tests, follow TESTING.
  • Docs
    Add relevant comments to your code if necessary using JSDoc 3 and update relevant guides.
    The generated documentation can be found at fabricjs.com, see DOCS.
  • Changelog
    Add a concise listing to the CHANGELOG describing what has changed.
  • 1️⃣ PR per feature/bug
    Create a new branch for every pull request.
    If you want to do more than one thing, create multiple pull requests 💪.
  • And there you go!
    If you still have questions we're always happy to help.

After you open a PR a maintainer will review it. It is more than likely you will be requested to change stuff and refine your work before it is merged into the repo.

🧪 Testing

🩺 🧪 CodeQL

Test suites use QUnit for assertions and testem for serving

  • unit tests: test logic and state
  • visual tests: test visual outcome against image refs located at /test/visual/golden

Getting Started

  • build and watch for changes:
npm run build -- -f -w
  • run tests:
npm test -- -a -d
> Running all tests in debug mode (read more in the help section)

npm test -- -s visual --dev -l -c chrome
> Running live visual tests on chrome (navigate to see)

npm test -- --help

> Usage: fabric.js test [options]

> run test suite

Options:
  -s, --suite <suite...>      test suite to run (choices: "unit", "visual")
  -f, --file <file>           run a specific test file
  --filter <filter>           filter tests by name
  -a, --all                   run all tests (default: false)
  -d, --debug                 debug visual tests by overriding refs (golden images) in case of visual changes (default:
                              false)
  -r, --recreate              recreate visual refs (golden images) (default: false)
  -v, --verbose               log passing tests (default: false)
  -l, --launch                launch tests in the browser (default: false)
  --dev                       runs testem in `dev` mode, without a `ci` flag (default: false)
  -c, --context <context...>  context to test in (choices: "chrome", "firefox", "node", default: "node")
  -p, --port
  -o, --out <out>             path to report test results to
  --clear-cache               clear CLI test cache (default: false)
  -h, --help                  display help for command

🚧🎢 Developing 💡✨

Setting Up Locally

  1. 🍴 Fork the repository
  2. 💾 Clone your 🍴 to your 💻
  3. Install dependencies 🕹️ npm i --include=dev
  4. Next Up Prototyping & Testing

Online

Open in Gitpod

Gitpod will start the prototyping apps and expose them as endpoints. A service is available on port ... popups will show up.

🧭 Prototyping

.codesandbox/templates contains templates for INSTANT out-of-the-box prototyping 👍 Try it out

npm run sandbox build next [/path/to/sandbox]
> building next app at /path/to/sandbox

npm run sandbox start </path/to/sandbox>
> starting dev server

npm run sandbox deploy </path/to/sandbox>
> created codesandbox https://codesandbox.io/s/fgh476

npm run sandbox deploy -- --template node
> created codesandbox https://codesandbox.io/s/fgh476

npm run sandbox -- --help

> Usage: fabric.js sandbox [options] [command]

> sandbox commands

Options:
  -h, --help                      display help for command

Commands:
  deploy [options] [path]         deploy a sandbox to codesandbox
  build <template> [destination]  build and start a sandbox
  start <path>                    start a sandbox
  help [command]                  display help for command

🔮 Symlinking

Establish symlinking to work with a local version on separate projects.

  1. From fabric.js folder run npm link OR yarn link.
  2. From the project's folder run npm link fabric OR yarn link fabric.

See npm link OR yarn link.
Don't forget to unlink the package once you're done.