fabric 5.3.0-browser → 6.0.0-beta1

package/CONTRIBUTING.md

@@ -1,92 +1,260 @@
-# Contributing to Fabric
+# 🎉 Contributing to Fabric 🥳
 
-1. [Questions?!?](#questions)
-2. [Issue tracker](#issue-tracker)
-3. [Issue tracker guidelines](#issue-tracker-guidelines)
-4. [Pull requests](#pull-request)
-5. [Pull request guidelines](#pull-request-guidelines)
+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?!?
 
-To get your questions answered, please ask/search on [Fabric's google group], [StackOverflow] or on Fabric's IRC channel (irc://irc.freenode.net/#fabric.js).
-Please do not open an issue if you're not sure it's a bug or if it's not a feature/suggestion.
+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.
 
-For news about Fabric you can follow [@fabric.js], [@AndreaBogazzi], [@kangax], or [@kienzle_s] on Twitter.
-Demos and examples can be found on [jsfiddle], [codepen.io] and [fabricjs.com].
+To find an answer, first [search the repository][search_issues]. It contains a lot of useful threads.
 
-## Issue tracker
+Questions might inspire you to [improve the docs](#-improving-docs) 🌈 Please do 🌟.
 
-If you are sure that it's a bug in Fabric.js or a suggestion, open a new [issue] and try to answer the following questions:
+Demos and examples 🤓 can be found on [fabricjs.com][website], [`jsfiddle`][jsfiddles], [`codepen.io`][codepens] and more.
 
-- What did you do?
-- What did you expect to happen?
-- What happened instead?
+## 🏷️ Issue Tracker
 
-### Issue tracker guidelines
+- **Before You Begin** 🎬
+  - 📌 Make sure you didn't fall into a known [**GOTCHA**][gotchas].
+  - 🔎 [**Searching**][search_issues] 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][bug_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 🦋.
 
-- **Search:** Before opening a new issue please [search](https://github.com/fabricjs/fabric.js/search?q=&ref=cmdform&type=Issues) Fabric's existing issues.
+**These are minimal requirements. Without them issues shall be ⛔.**
 
-- **Title:** Choose an informative title.
+If it's not a bug **OR** if you're unsure, start a 🤠 [discussion][discussions].
 
-- **Description:** Use the questions above to describe the issue. Add logs, screenshots or videos if that makes sense.
+Check out [**Helping Out**](#%EF%B8%8F-helping-out).
 
-- **Test case:** Please post code to replicate the bug - best on [jsfiddle](http://jsfiddle.net). Ideally a failing test would be
-perfect, but even a simple script demonstrating the error would suffice. You could use [this jsfiddle template](http://jsfiddle.net/fabricjs/Da7SP/) as a
-starting point.
+---
 
-- **Fabric.js version:** Make sure to specify which version of Fabric.js you are using. The version can be found in [fabric.js file](https://github.com/fabricjs/fabric.js/blob/master/dist/fabric.js#L5) or just by executing `fabric.version` in the browser console.
+## 🔦 Fixing typos
 
-## Pull requests
+Typos are a nasty thing.\
+Though it may seem insignificant, typo fixes are appreciated!\
+It's a good and simple way to start contributing.
 
-We are very grateful for your pull requests! This is your chance to improve Fabric for everyone else.
+## 🔎 Improving Docs
 
-### Online one-click setup for making PRs
+Improving **DOCS** is **SUPER** important for everyone.\
+Even if it's a small fix it is valuable 💎... **don't hesitate**!
 
-Contribute to fabricjs using a fully featured online development environment that will automatically with a single click: clone the repo and install the dependencies.
+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](#-pull-requests)), are great ways to start contributing to fabric.
+
+- [Issues][issues]
+- [Discussions][discussions]
+
+### 🎮 Adding a DEMO
+
+Take a look at an existing [demo file][demo_file].\
+Create a new file in the same directory (`posts/demos/_posts`) and follow [**developing the website**](#fabricjscom-deprecated).
+
+### ~~`fabricjs.com`~~ (_deprecated_)
+
+To develop fabric's site you need to clone [`fabricjs.com`][website_repo] in the same parent folder of [`fabric.js`][repo], 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][jekyll] for further instructions or use [WSL][wsl].
+
+## 🐛 Fixing Bugs
+
+- Open an [issue](#-issue-tracker), if there isn't any, addressing the bug.
+- Fix the bug, see [Developing](#-developing-).
+- Add [tests](#-testing).
+- [PR](#-pull-requests)
+
+## 🚀 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
+
+- Read this section through.
+- Take a look at [**GOTCHAS**][gotchas]
+- Follow [Developing](#-developing-) and read [Testing](#-testing).
+
+### ✅ Guidelines
+
+- **Code Style** \
+  Fabric uses [`prettier`][prettier] to format files and [`eslint`][eslint] for linting (`npm run lint -- --fix`).\
+  To enjoy a seamless dev experience add the [`Prettier - Code formatter`][prettier_extension] extension via the extensions toolbar in VSCode.
+- **⛔ `dist`** \
+  Commit changes to [source files](src). Don't commit the generated [distribution files](dist).
+- **Tests** \
+  PRs must be backed with relevant tests, follow [TESTING](#-testing).
+- **Docs** \
+  Add relevant comments to your code if necessary using [JSDoc 3][jsdoc] and update relevant guides.\
+  The generated documentation can be found at [fabricjs.com][docs], see [DOCS](#-improving-docs).
+- **Changelog**\
+  Add a concise listing to the [**CHANGELOG**](CHANGELOG.md) 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
+
+[![🩺](../../actions/workflows/build.yml/badge.svg)](../../actions/workflows/build.yml)
+[![🧪](../../actions/workflows/tests.yml/badge.svg)](../../actions/workflows/tests.yml)
+[![CodeQL](../../actions/workflows/codeql-analysis.yml/badge.svg)](../../actions/workflows/codeql-analysis.yml)
+
+Test suites use [`QUnit`][qunit] for assertions and [`testem`][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:
+
+```bash
+
+npm run build -- -f -w
+
+```
+
+- run tests:
+
+```bash
+
+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
+1. 💾 Clone your 🍴 to your 💻
+1. Install dependencies 🕹️ `npm i --include=dev`
+1. Next Up [Prototyping](#-prototyping) & [Testing](#-testing)
+
+#### Online
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/)
 
-### Setting up a local environment
+Gitpod will start the [prototyping](#-prototyping) apps and expose them as endpoints.
+`A service is available on port ...` popups will show up.
+
+### 🧭 Prototyping
+
+[`.codesandbox/templates`](.codesandbox/templates) contains templates for **INSTANT** out-of-the-box prototyping **👍 Try it out**
+
+```bash
+
+npm run sandbox build next [/path/to/sandbox]
+> building next app at /path/to/sandbox
 
-Coming Soon!
+npm run sandbox start </path/to/sandbox>
+> starting dev server
 
-### Working on fabricjs.com
+npm run sandbox deploy </path/to/sandbox>
+> created codesandbox https://codesandbox.io/s/fgh476
 
-To develop fabric's site you need to clone [`fabricjs.com`](https://github.com/fabricjs/fabricjs.com) in the same parent folder of [`fabric.js`](https://github.com/fabricjs/fabric.js), so that `fabric.js` and `fabricjs.com` are siblings.
-To start the dev server run `npm start` inside the `fabricjs.com` directory (after installing dependecies).
-If you are working on windows, check out [`jekyll` docs](https://jekyllrb.com/docs/installation/) for futher instructions.
+npm run sandbox deploy -- --template node
+> created codesandbox https://codesandbox.io/s/fgh476
 
-**Adding a DEMO**:
-Take a look at an existing [demo file](https://github.com/fabricjs/fabricjs.com/blob/gh-pages/posts/demos/_posts/2020-2-15-custom-control-render.md).
-Create a new file in the same directory (`posts/demos/_posts`) and you're good to go.
+npm run sandbox -- --help
 
-### Pull request guidelines
+> Usage: fabric.js sandbox [options] [command]
 
-Here are a few notes you should take into account:
+> sandbox commands
 
-- **Code style, notes:** Make sure you have complied with the [guidelines](https://github.com/fabricjs/fabric.js/wiki/How-to-contribute-to-Fabric#code-style-notes)
+Options:
+  -h, --help                      display help for command
 
-- **Distribution files:** Do your changes only in the [source files](https://github.com/fabricjs/fabric.js/tree/master/src). Don't include the [distribution files](https://github.com/fabricjs/fabric.js/tree/master/dist) in your commit.
+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
 
-- **Add tests**: Tests are always a great addition - invest a little time and expand the [unit tests suite](https://github.com/fabricjs/fabric.js/tree/master/test/unit). More informations about [QUnit](http://qunitjs.com/) tests can be found in the [wiki](https://github.com/fabricjs/fabric.js/wiki/How-to-contribute-to-Fabric#testing-fabric).
+```
 
-- **Add documentation:** Fabric uses [JSDoc 3] for documentation. The generated documentation can be found at [fabricjs.com](http://fabricjs.com/docs).
+### 🔮 Symlinking
 
-- **Create topic branches.** Don't use your master branch for pull request. It's better to create a new branch for every pull request.
+Establish symlinking to work with a local version on separate projects.
 
-- **One pull request per feature/bug**. If you want to do more than one thing, send multiple pull requests.
+1. From `fabric.js` folder run `npm link` **OR** `yarn link`.
+1. From the project's folder run `npm link fabric` **OR** `yarn link fabric`.
 
-- **And there you go!** If you still have questions we're always happy to help. Also feel free to consult [wiki](https://github.com/fabricjs/fabric.js/wiki/How-to-contribute-to-Fabric).
+See [npm link][npm_link] **OR** [yarn link][yarn_link].\
+Don't forget to unlink the package once you're done.
 
-[Fabric's google group]: https://groups.google.com/forum/#!forum/fabricjs
-[stackoverflow]: http://stackoverflow.com/questions/tagged/fabricjs
-[@fabric.js]: https://twitter.com/fabricjs
-[@AndreaBogazzi]: https://twitter.com/AndreaBogazzi
-[@kangax]: https://twitter.com/kangax
-[@kienzle_s]: https://twitter.com/kienzle_s
-[jsfiddle]: http://jsfiddle.net/user/fabricjs/fiddles
-[codepen.io]: http://codepen.io/tag/fabricjs
-[fabricjs.com]: http://fabricjs.com/demos
-[fabricjs.com/docs]: http://fabricjs.com/docs
-[JSDoc 3]: http://usejsdoc.org/
-[issue]: https://github.com/kangax/fabric.js/issues
+[repo]: ../..
+[issues]: ../../issues
+[discussions]: ../../discussions
+[search_issues]: ../../search?type=Issues
+[bug_report]: ../../issues/new?template=bug_report.md
+[website_repo]: https://github.com/fabricjs/fabricjs.com
+[website]: http://fabricjs.com/
+[docs]: http://fabricjs.com/docs
+[demos]: http://fabricjs.com/demos/
+[gotchas]: http://fabricjs.com/fabric-gotchas
+[demo_file]: https://github.com/fabricjs/fabricjs.com/blob/gh-pages/posts/demos/_posts/2020-2-15-custom-control-render.md
+[jsfiddles]: https://jsfiddle.net/user/fabricjs/fiddles/
+[codepens]: https://codepen.io/tag/fabricjs
+[jekyll]: https://jekyllrb.com/docs/installation/
+[wsl]: https://learn.microsoft.com/en-us/windows/wsl/
+[prettier]: https://prettier.io/
+[prettier_extension]: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
+[eslint]: https://eslint.org/
+[jsdoc]: https://jsdoc.app/
+[qunit]: https://qunitjs.com/
+[testem]: https://github.com/testem/testem
+[npm_link]: https://docs.npmjs.com/cli/v8/commands/npm-link
+[yarn_link]: https://yarnpkg.com/cli/link