diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a9fdc65564..3bb36006de4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,121 +1,202 @@ -# Contributing to Fabric +# ๐ŸŽ‰ Contributing to Fabric ๐Ÿฅณ -## 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?!? -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]. +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](https://github.com/fabricjs/fabric.js/search?q=&type=Issues), it contains a lot of useful threads.\ +Refer to `Fabric's google group`, `StackOverflow` and [`Fabric's IRC channel`](irc://irc.freenode.net/#fabric.js) as well.\ +See [Links](#-links). + +Questions might inspire you to [improve the docs](#-improving-docs) ๐ŸŒˆ Please do ๐ŸŒŸ. + +Demos and examples ๐Ÿค“ can be found on [fabricjs.com](http://fabricjs.com/demos/), `jsfiddle`, `codepen.io` and more. -## Issue tracker -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: +## ๐Ÿท๏ธ Issue Tracker -- What did you do? -- What did you expect to happen? -- What happened instead? +- **Before You Begin** ๐ŸŽฌ + - ๐Ÿ“Œ Make sure you didn't fall into a known [**GOTCHA**](http://fabricjs.com/fabric-gotchas) + - ๐Ÿ”Ž [**Searching**](https://github.com/fabricjs/fabric.js/search?q=&ref=cmdform&type=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 ๐Ÿฆ‰. +- The **Title** must be informative, short and ๐Ÿงฟ to the point. +- **Fill out the ๐Ÿ› report with care**, it is there for a reason. +- **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](https://github.com/fabricjs/fabric.js/issues/new?assignees=&labels=&template=bug_report.md) +- Specify which **version** of Fabric.js you are using. +- **Upgrade** to the latest version before proceeding, your ๐Ÿ› may have turned into a ๐Ÿฆ‹. -### Issue tracker guidelines +**These are minimal requirements. Without them issues shall be โ›”.** -If you think you found a bug in Fabric file an [issue](https://github.com/fabricjs/fabric.js/issues). +If it's not a bug **OR** if you're unsure, start a ๐Ÿค  [discussion](https://github.com/fabricjs/fabric.js/discussions) or create a post โœ‰๏ธ on [Fabric's google group](groups.google.com/forum/?fromgroups#!forum/fabricjs) where someone might clarify some of the things. -- **Gotchas**: Make sure you didn't fall into a known [fabric-gotcha](http://fabricjs.com/fabric-gotchas) -- **Search:** Before opening a new issue please take the time to [search](https://github.com/fabricjs/fabric.js/search?q=&ref=cmdform&type=Issues) Fabric's existing issues. This is vital to prevent spamming and to keep the community in a good state. -- **Title:** Choose an informative title. +## ๐Ÿšง๐ŸŽข Developing ๐Ÿ’กโœจ -- **Description:** Use the questions above to describe the issue. Add logs, screenshots or videos if that makes sense. +### Getting Started -- **Test case:** Make sure you create a minimal and immediate test case, demonstrating the bug, with relevant explanations. It should be extremely **easy** and **fast** for someone to understand your bug and reproduce it. Bug templates can be found within a [bug report](https://github.com/fabricjs/fabric.js/issues/new?assignees=&labels=&template=bug_report.md) +1. ๐Ÿด Fork the repository +1. ๐Ÿ’พ Clone your ๐Ÿด to your ๐Ÿ’ป +1. Install dependencies ๐Ÿ•น๏ธ `npm i --include=dev` +1. Next Up [Prototyping](#-prototyping) & [Testing](#-testing) -- **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. It is advised you upgrade to the latest version before proceeding. +### ๐Ÿงญ Prototyping +`.codesandbox/templates` contains templates for **INSTANT** out-of-the-box prototyping **๐Ÿ‘ Try it out** -**Without these requirements issues shall be closed.** +```bash -If you're unsure about something that is not a bug, it's best to start a [discussion](https://github.com/fabricjs/fabric.js/discussions) or create a post on [Fabric's google group](groups.google.com/forum/?fromgroups#!forum/fabricjs) where someone might clarify some of the things. +npm run sandbox build next [/path/to/sandbox] +> building next app at /path/to/sandbox -## Pull requests +npm run sandbox start +> starting dev server -We are very grateful for your pull requests! This is your chance to improve Fabric for everyone else. -Before you begin read this through and take a look at [fabric-gotchas](http://fabricjs.com/fabric-gotchas) +npm run sandbox deploy +> created codesandbox https://codesandbox.io/s/fgh476 -### Online one-click setup for making PRs +npm run sandbox deploy -- --template node +> created codesandbox https://codesandbox.io/s/fgh476 -Contribute to fabricjs using a fully featured online development environment that will automatically with a single click: clone the repo and install the dependencies. +npm run sandbox -- --help -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/) +> Usage: fabric.js sandbox [options] [command] -### Setting up a local environment +> sandbox commands -1. Clone your fork of `fabric.js` to your machine -1. Install dependencies: `npm i` +Options: + -h, --help display help for command -You can decide how you prefer to work: +Commands: + deploy [options] [path] deploy a sandbox to codesandbox + build