src/site/sphinx/contribution.rst
How to contribute
Please report any issue to the GitHub Issue Tracker <https://github.com/JSQLParser/JSqlParser/issues>_:
Before reporting any issues, please verify your statement using JSQLFormatter Online <http://jsqlformatter.manticore-projects.com>_.
JSQLParser is a demand-driven software library, where many contributors have shared solutions for their own needs. Requests for new features have a good chance to get implemented when
The team around JSQLParser warmly welcomes Code Contributions and Pull Requests. Please follow the guidance below and do not hesitate to ask us for assistance.
When starting afresh, clone JSQLParser from the GitHub repository:
.. code-block:: Bash
git clone https://github.com/JSQLParser/JSqlParser.git cd JSqlParser git branch <new-branch>
When having a local repository already, then pull/merge from the GitHub repository:
.. code-block:: Bash
cd JSqlParser git pull origin master git branch <new-branch>
The JSQLParser is generated by JavaCC based on the provided Grammar. The Grammar defines how a SQL Text is read and translated into Java Objects. Thus any contribution will depend on the following steps:
Edit the JavaCC Grammar at src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt
Add or edit the Java Classes at src/main/java/net/sf/jsqlparser to facilitate this Grammar.
When have added new Java Classes, amend the Visitors, the Visitor Adaptors, the De-Parsers and the Validators.
Provide Java Unit Tests at src/test/java/net/sf/jsqlparser to test the new feature
assertSqlCanBeParsedAndDeparsed()Add the description of the new feature to the README.md file, section Extensions.
Build the package with Gradle and ensure, all checks do pass (PMD and CheckStyle and Code Formatting).
.. tab:: Gradle
.. code-block:: shell
:caption: Gradle `check` Task
gradle check
.. tab:: Maven
.. code-block:: shell
:caption: Maven `verify` Task
mvn verify
Verify the performance and avoid any deterioration
.. code-block:: shell
:caption: Gradle check Task
gradle jmh
.. code-block:: text :caption: JMH performance results
Benchmark (version) Mode Cnt Score Error Units
JSQLParserBenchmark.parseSQLStatements latest avgt 30 83.504 ± 1.557 ms/op
JSQLParserBenchmark.parseSQLStatements 5.2 avgt 30 400.876 ± 8.291 ms/op
JSQLParserBenchmark.parseSQLStatements 5.1 avgt 30 85.731 ± 1.288 ms/op
Create your GitHub Pull Request <https://www.youtube.com/watch?v=nCKdihvneS0>_
Since JSQLParser is built by JavaCC from a Token based Grammar, Reserved Keywords need a special treatment. All Tokens of the Grammar would become Reserved Keywords -- unless explicitly allowed as identifiers.
The Grammar uses a NonReservedWord() BNF production with inline token declarations, bracketed by MIN_NON_RESERVED_WORD and MAX_NON_RESERVED_WORD sentinel tokens. JavaCC assigns consecutive token kind values to the inline declarations, which enables an efficient O(1) range check in isIdentifierAhead() to determine whether a token can be used as an unquoted identifier.
.. code-block:: sql :caption: Non-reserved keyword example
-- <K_OVERLAPS:"OVERLAPS"> is defined as a non-reserved keyword inside the NonReservedWord() production
-- It can be used for Column, Table and Alias names without quoting
SELECT Overlaps( overlaps ) AS overlaps
FROM overlaps.overlaps overlaps
WHERE overlaps = 'overlaps'
AND (CURRENT_TIME, INTERVAL '1' HOUR) OVERLAPS (CURRENT_TIME, INTERVAL -'1' HOUR)
;
When adding a new keyword token to the Grammar:
1) If the keyword should be usable as an unquoted identifier (the common case), add its inline token declaration to the ``NonReservedWord()`` production. It will automatically be placed between the sentinel tokens and recognised by the range check.
2) If the keyword must be reserved (e. |_| g. core SQL syntax like ``SELECT``, ``FROM``, ``WHERE``), add it to the ``Reserved SQL Keywords`` TOKEN block **after** the ``MAX_NON_RESERVED_WORD`` sentinel.
3) Verify that existing tests pass and that the keyword can be used as a ``Schema``, ``Table``, ``Column``, ``Function`` or ``Alias`` name where expected.
.. code-block:: Bash
cd JSqlParser git add -A git commit -m <title> -m <description> git push –set-upstream origin <new-branch>
Follow the advice on Meaningful Commit Messages <https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/>_ and consider using Commitizen <https://commitizen-tools.github.io/commitizen/>_ when describing your commits.
Please consider using Conventional Commits and structure your commit message as follows:
.. code-block:: text :caption: Conventional Commit Message Structure
<type>[optional scope]: <description>
[optional body]
[BREAKING CHANGE: <change_description>]
[optional footer(s)]
.. list-table:: Commit Message Types :widths: 15 85 :header-rows: 1
Please visit Better Programming <https://betterprogramming.pub/write-better-git-commit-messages-to-increase-your-productivity-89fa773e8375>_ for more information and guidance.