Version 6.2 Released!

Click to checkout the new features

Submitting A Pull Request

Working With GitHub

If you are thinking of adding a feature to Tabulator, then I would like to start of by saying a big THANK YOU. It is always great when a member of the community wants to help out.

Full details on how to use pull requests with GitHub can be found Here.

Before Sumbitting a Pull Request

Before you go to the effort of writing code for Tabulator and submitting a pull request, please make sure you follow these steps to make sure that your feature is needed in the table.

Check for existing Feature Requests or Bug Reports related to your contribution to make sure that no one else is working on the same issue.

If no issue exists, create a Feature Request to open discussion on your proposed contribution and get feedback from the community. This is especially important if you are working on a large addition, or change in core functionality as it is likely that any pull request enacting large scale changes will be rejected unlesss there is initial discussion on how it will affect existing Tabulator features.

Think about whether your pull request offers a feature that is useful to all of Tabulators users or is just to address a specific use case for your project. To avoid cluttering the code base, pull requests will not be considered for features that only address edge cases.

Does your usage case alter the default functionality of the table? Pull requests to add functionality must not change the current default user experience of the table (unless you are fixing a bug), if you are adding a new option to the table then the current mode of operation must remain the default.

Does your change work well with the other modules in the table? updates to Tabulator must be considered in the context of the table as a whole, an update must work as expected in any configuration of the table and should not break any existing functionality

Please make sure you fully understand the existing codebase before submitting a Pull Request. One of the most frequest issues we face with new pull requests is users fixing an issue for themselves but breaking other table functionality

DO NOT submit a PR that makes significant changes to library functionality or that goes against the roadmap without starting a Feature Request to talk about it first as it will likely be rejected

DO start small. Take time to get to know Tabulator before tackling big changes. Start out with bug fixes and small features first and work up to larger scale updates.

Writing Your Code

The Tabulator source comes with an ESLint configuration that should allow most modern IDE's (VSCode, Sublime Text, etc) to hint at the correct coding style for any additions this library. Please make sure you adhear to the requirments fo the ESLint config to make the PR process as smooth as possible:

In order to keep the Tabulator source code accessible to everyone, we ask that developers follow the following guidelines when creating their pull request:

In order to keep the codebase consistent and clean, please follow the existing coding style of Tabulator. Pull requests with extensive changes to the existing code style will NOT be accepted. for example:

  • no additional spaces are required around functions and parentheses
  • prefix function names with underscores if they are internal to modules and should be considered private
  • if statements must use curly braces unless they are ternary
  • functions on modules must be added to the prototype to improve efficiency

If you are writing code to extend an existing module, keep all code contained within that module. The point of abstracting code into these modules is to make it easier to maintain.

When calling functions on a module from outside the module, you should always call the modExists function on the table first to check that the module as been included. This is because modules are optional and may not always be available

Any functions that return row, column or cell objects, should call the GetComponent on them to get the Component Object and return this instead. This provides a safe public wrapper around internal table functionality in the process

TEST YOUR CODE before submitting your Pull Reqest. One of the most frequent issues we face with new pull requests is developers fixing an issue for themselves but breaking other table functionality

Make sure your update works on all Supported Browsers

Changes should ONLY be made to files in the /src folder. The /dist folder is automatically generated and any changes there will be automatically overwritten

Do not leave excessive comments in the code:

  • Your functions and variables should be named in a way that makes their purpose obvious without additional comments
  • Do not leave comments about why you have made changes, these should be included in your pull request details
  • Do not use the comments to leave your initials in the code. Your commit will be a record of your contribution, the codebase should not be polluted with personal tags

Do not call public API functions on the table when you are writing code internal to the table. Calling of internal table functionality should preferably happen through the internal event bus, or through direct method calls of other modules when necessary

Do not use query selectors in your code. Any elements added to the DOM should have the reference to the node stored in a variable, and that variable used to access the node at a later date. Tabulator has to handle 1000's of DOM elements very quickly and query selectors slow everything down. PR's using query selectors will automatically be rejected

Do not make changes to files in the /dist folder, this folder is automatically generated and any changes there will be automatically overwritten next time the source is updated. Any PR's with changes to these files will automatically be rejected

Submitting A Pull Request

When you are ready to submit your pull request, please consider the following:

Make the title short and descriptive so other users can find the it easily.

Tag the Feature Request or Bug Report related to the PR to add context to the submission and help other users join in the discussion.

Include as many details about the additions as possible, including a usage case and example code snippet so we can understand why the PR is needed and how it will be used by other users.

Make sure that you are submitting your code against the correct branch. Most PR's should be made against the master branch unless your are contributing a feature from the roadmap to a specific version.

Submitting a Pull Request is a collaborative process. Once you have submitted your pull request you should expect a dialog with the reviewer who will guide you through any changes that need to be made before the PR can be accepted and merged into the code base. If the overall concept of your PR has been approved it will be given the state of PR Needs Work until all outstanding points of the reviewer have been addressed.

Do not expect your code to be merged into the codebase straight away. In order to make sure that users are kept up to date with changes, PR's are only merged into the master branch when a new version of Tabulator is released and the documentation is updated. If your PR has been approved and is waiting for the next release it will be given the state of PR Awaiting Merge. Bug fixes are usually merged into patch releases which happen every week or two, feature updates will be included in minor releases which happen every 2 to 3 months.

Automated PR Validation

When you submit a pull request to make changes in Tabulator, there are automated GitHub actions that will automatically run validation checks against your code to ensure it meets the ESLint code formatting requirements before it will allow the PR to be merged.

If the linter picks up an issues with submitted code, you will see the failures listed in a report at the bottom of the Conversation tab of the PR. You will need to fix each of the issues before the PR is approved for merging.

failed pr report