Skip to content

Latest commit

 

History

History
141 lines (98 loc) · 6.6 KB

CONTRIBUTING.md

File metadata and controls

141 lines (98 loc) · 6.6 KB

Contributing

Welcome and thank you for your interest in contributing to Sql Script DOM! Before contributing to this project, please review this document for policies and procedures which will ease the contribution and review process for everyone.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Issues and Feature Requests

Before filing an issue, please make sure that the issue has not been submitted before in our public repository Sql Script DOM.

To report a new issue please add the bug tag and use the enhancement tag for new feature proposals.

Bugs

Please create an issue per bug and include the version of Sql Script DOM where you are experiencing the issue, the steps to repro the bug, include error messages if applicable, and add a description of the expected result versus the actual result.

Feature Requests

Please create an issue per feature request and describe the current and desired behavior. If you have a proposed solution, please include it in the issue as well as whether you'd like to contribute the change.

Contributing Code

Contributor License Agreement

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g. status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Getting Started

Windows

  1. Download .NET SDKS from https://dotnet.microsoft.com/download/visual-studio-sdks

    • .NET Framework SDK (4.6.2 or higher)
    • .NET 6 SDK (see global.json for latest version)

  2. Install Visual Studio 2022 or newer. (Optional)

  3. Install the SlnGen tool. (Optional Visual Studio generator)

    dotnet tool install --global Microsoft.VisualStudio.SlnGen.Tool

  4. Run DisableStrongName script as administrator: disableStrongName.ps1 This step only needs to be done once.

  5. Clone the repository

        git clone https://github.com/microsoft/SqlScriptDOM

macOS/Linux

  1. Download .NET SDKS from https://dotnet.microsoft.com/download/visual-studio-sdks

  2. Install the Java runtime (JRE)

  3. Install PowerShell Core

  4. Clone the repository

        git clone https://github.com/microsoft/SqlScriptDOM

Building

Navigate to the root of the source code:

cd SqlScriptDOM

Optional, Windows-only - Generate and open Visual Studio solution. This step is not required to build the project.

slngen

Restore project dependencies:

dotnet restore

To build:

dotnet build

Running the tests

You can run tests directly in Visual Studio Text Explorer or by using the dotnet test command.

Example: To run all priority 0 tests

dotnet test --filter Priority=0

Pull Request Process

Before sending a Pull Request, please do the following:

  1. Ensure builds are still successful and tests, including any added or updated tests, pass prior to submitting the pull request.
  2. Update any documentation, user and contributor, that is impacted by your changes.
  3. Include your change description in CHANGELOG.md file as part of pull request.
  4. You may merge the pull request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.

Helpful notes for SQLDOM extensions

  1. For changing the DOM classes, modify the XML file (the C# code is generated based on this during the build process) $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\Parser\TSql\Ast.xml. Change Ast.xml to put the class pieces on their appropriate statements.

    1. The build process is defined in $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\SqlScriptDom.props (Target Name="CreateAST")
    2. The generated files are dropped in $(EnlistmentRoot)\obj\<x64|x86>\<Debug|Release>\SqlScriptDom.csproj\

  2. For changing the parser, modify the .g file here: $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\Parser\TSql\TSql<#>.g where # is the version (ie - 100, 120, 130). This will usually be the latest number if adding new grammar. Change the Tsql(xxx).g file to parse the new syntax.

    1. The build process is defined in $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\SqlScriptDom.props (Target Name="CreateAST")
    2. The generated files are dropped in $(EnlistmentRoot)\obj\x86|x64\Debug|Release\sqlscriptdom.csproj\

  3. For changing the ScriptGenerator, modify the appropriate file (i.e. Visitor that accepts the modified DOM class) in here: $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\ScriptDom\SqlServer\ScriptGenerator.

    1. To add a new ScriptGenerator, you need to add the file to $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\SqlScriptDom.props
    2. Change The visitors SqlScriptGenerator.X to use the new piece from AST.XML
    3. If you're adding syntax that's Azure-only or Standalone-only, implement appropriate Versioning Visitor for your constructs.

  4. When adding/removing new files please add/remove an entry to/from $(EnlistmentRoot)\Source\SqlDom\SqlScriptDom\SqlScriptDom.csproj

  5. To extend the tests do the following:

    1. Baselines# needs to be updated or added with the appropriate .sql file as expected results.
    2. The Only#SyntaxTests.cs needs to be extended or added to specify the appropriate TestScripts script.
    3. Positive tests go in Only#SyntaxTests.cs if adding new grammar.
    4. Create a \TestScripts script that is the input for the test. (This is what is run and is checked against the .sql files in Baselines#)
    5. Negative tests go in ParserErrorsTests.cs.