Thanks for considering contributing to @gsid/dnd! ❤️
Do not forget to read our git commit guidelines beforehand.
There are a few categories of contribution so we'll go through them individually.
If you think the docs could be improved - please feel free to raise a pull request!
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.
If you would like to see a feature added to the library, here is what you do:
- Have a read of
README.mdto 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. - Have a search through the open and closed issues to see if the feature you are requesting as already been requested.
- Have a clear and general purpose keyboard story for any feature request
- 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.
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 @gsid/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.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the change log. This project adheres to Semantic Versioning 2.0.
The commit message formatting can be added using a typical git workflow or through the use of a CLI
wizard (Commitizen). To use the wizard, run pnpm cz or git commit in your terminal after staging your changes in git.
The format of each commit must follow the Conventional Commits specification.
- 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.
This is a React project so getting familiar with React is a must!
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:reactbindings forreduxreselect: we usereselectheavily 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.
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 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
This codebase is using TypeScript. Changes will not be merged without correct typing. If you are not sure about a particular use case let TypeScript break the build and it can be discussed in the pull request.
The TypeScript documentation is great. Have a look at it.
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
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. @gsid/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-@gsid/dnddraws a fair amount of inspiration fromreact-dnd. Something to keep in mind is thatreact-dndis 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@gsid/dnd. Alex Reardon created a comparison blog that explains the differencesjQuery sortable- the king of drag and drop for a long time