CONTRIBUTING.md

Contributing

Thanks for considering contributing to react-beautiful-dnd! ❤️

There are a few categories of contribution so we'll go through them individually.

Documentation

If you think the docs could be improved - please feel free to raise a pull request!

Bug

If you spot a bug you are welcome to raise it on our issue page. You are also welcome to take a crack at fixing it if you like! When you create an issue you will be prompted with the details we would like you to provide.

Feature request

If you would like to see a feature added to the library, here is what you do:

1. Have a read of README.md to understand the motivations of this library. It is fairly opinionated and is not intended to be a universal drag and drop library. As such, it will not support every drag and drop interaction.
2. Have a search through the open and closed issues to see if the feature you are requesting as already been requested.
3. Have a clear and general purpose keyboard story for any feature request
4. Please create an issue to discuss it.

Please do not raise a pull request directly. There may be reasons why we will not add every feature to this library.

Large contributions

If you are interested in making a large contribution to this library there is some recommended reading / training we suggest. There is a large amount of different libraries, techniques and tools used in react-beautiful-dnd and we have created a list with resources about them. Not everything in the list will be applicable to everyone. But it is a great reference and starting point for those who do not know where to start.

The online courses listed are no free - feel free to seek out alternatives if you want to. We recommend the egghead.io courses because they are quite comprehensive.

General knowledge

• You Don't Know JS: This is an amazing resource that I recommend all the time. It is great for having a deeper understanding of the JavaScript language.

Technologies

React

This is a React project so getting familiar with React is a must!

• react
• An intro to using React

Redux

This project uses redux for its state management. If you have not used redux before it is worth getting familiar with it.

• redux: the library itself has really great docs
• Getting Started with Redux: the whole course
• Building React Applications with Idiomatic Redux: no need to do the lessons on react router or data fetching
• react-redux: react bindings for redux
• reselect: we use reselect heavily to ensure that state selectors are as fast as they can be. Please have a read of its main page, especially the sharing Selectors with Props Across Multiple Components section.

Testing

We test our application very thoroughly. Changes will not be accepted without tests

• jest: We use the jest test runner. It is worth getting familiar with it
• Test JavaScript with Jest
• React Testing Cookbook

Performance

Performance is critical to this project. Please get familiar with React performance considerations. Changes that break core performance characteristics will not be accepted.

• Performance optimisations for React applications
• Performance optimisations for React applications round 2
• React performance tools
• React performance documentation
• React is slow, React is fast

Flow

This codebase is typed with flow. Changes will not be merged without correct flow typing. If you are not sure about a particular use case let flow break the build and it can be discussed in the pull request.

• flow: the flow docs are great
• Up and Running with Facebook Flow for Typed JavaScript: a small primer for running flow

Drag and drop problem space

HTML5 drag and drop

How this library performs dragging is an implementation detail. The api is what users interact with. That said, this library does not use the html5 drag and drop api. The main reason is that html5 drag and drop does not allow the level of control we need to create our powerful and beautiful experiences. I could go into detail but this is not the right forum.

Here is some general reading about html5 drag and drop. It is worth having a read to get familiar with its ideas and api

• HTML5 drag and drop api
• HTML5 Rocks - dnd basics
• The HTML5 drag and drop disaster
• HTML5 drag and drop browser inconsistencies

Prior work

It is worth looking at other libraries out there to see how they do drag and drop. Things to look at is their philosophy and api. react-beautiful-dnd is an opinionated, higher level abstraction than most drag and drop libraries. We do not need to support every use case. We need to find the right level of control while still maintaining a beautiful experience for the user, flexibility of use and a clean, powerful api.

• react-dnd - react-beautiful-dnd draws a fair amount of inspiration from react-dnd. Something to keep in mind is that react-dnd is designed to provide a set of drag and drop primitives which is a different set of goals to this project.
• react-sortable-hoc - on the surface this library looks similar to react-beautiful-dnd. I created a comparison blog that explains the differences
• jQuery sortable - the king of drag and drop for a long time