****************************** How to contribute ****************************** Error Reports ============================== Please report any issue to the `GitHub Issue Tracker `_: 1) Provide the **Sample SQL** (shortened and simplified, properly formatted) 2) State the exact **Version of JSQLParser** 3) State the **RDBMS** in use and point on the applicable Grammar specification 4) Please write in **English** and post **Plain Text only** (avoiding screen shots or bitmap pictures). Before reporting any issues, please verify your statement using `JSQLFormatter Online `_. Feature Requests ============================== 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 1) the request is about a commonly used feature for one of the major RDBMS 2) or the request is backed by a sponsor or a bounty, which may attract developers to spend their time on it. Implementing new Features ============================== 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. Create a new Git Branch ------------------------------ When starting afresh, clone `JSQLParser` from the `GitHub` repository: .. code-block:: Bash git clone https://github.com/JSQLParser/JSqlParser.git cd JSqlParser git 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 Amend the Code ------------------------------ 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: 1) Edit the ``JavaCC`` Grammar at ``src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt`` 2) Add or edit the Java Classes at ``src/main/java/net/sf/jsqlparser`` to facilitate this Grammar. 3) When have added new Java Classes, amend the Visitors, the Visitor Adaptors, the De-Parsers and the Validators. 4) Provide Java Unit Tests at ``src/test/java/net/sf/jsqlparser`` to test the new feature * The test should call at least one time the method ``assertSqlCanBeParsedAndDeparsed()`` * The test should ensure complete coverage of the new Java Classes. * The complete test suite must succeed. 5) Add the description of the new feature to the ``README.md`` file, section `Extensions`. 6) 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 7) 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 8) Create your `GitHub Pull Request `_ Manage Reserved Keywords ------------------------------ 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 -- 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. Commit a Pull Request --------------------------------- .. code-block:: Bash cd JSqlParser git add -A git commit -m -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 * - Type - Description * - **feat** - introduce a new feature * - **fix** - patches a bug in your codebase (bugfix or hotfix) * - **build** - changes that affect the build system or external dependencies * - **chore** - updates dependencies and does not relate to fix or feat and does not modify src or test files. * - **ci** - changes that affect the continuous integration process * - **docs** - updates the documentation or introduce documentation * - **style** - updates the formatting of code; remove white spaces, add missing spaces, remove unnecessary newlines * - **refactor** - reactors code segments to optimize readability without changing behavior * - **perf** - improve performance * - **test** - add/remove/update tests * - **revert** - reverts one or many previous commits Please visit `Better Programming <https://betterprogramming.pub/write-better-git-commit-messages-to-increase-your-productivity-89fa773e8375>`_ for more information and guidance.