Skip to content

Contributing

Jump to bottom
Charles Gagnon edited this page Dec 11, 2023 · 16 revisions

Contributor Guide

The instructions below will help you set up your development environment to contribute to this repository. Make sure you've already cloned the repo. 😄

Ways to Contribute

Interested in contributing to the mssql project? There are plenty of ways to contribute, all of which help make the project better.

Set up Node, npm and gulp

Node and npm

Windows and Mac OSX: Download and install node from nodejs.org

Linux: Install using package manager

From a terminal ensure at least :

  • node >=10 and <=18
  • npm >= 6
$ node -v && npm -v
v10.16.3
6.9.0

Note: To get npm version 3.8.2, you may need to update npm after installing node. To do that:

[sudo] npm install npm -g

Gulp

Install gulp command line tools

[sudo] npm install gulpjs/gulp-cli -g

From the root of the repo, install all of the build dependencies:

[sudo] yarn

Install the Visual Studio Code Extension Manager (VSCE)

Before packaging via gulp, ensure that you have the "vsce" tool installed globally. Otherwise, the package step will fail. This is not needed if you are just building and/or running tests.

From the root of the repo, run:

[sudo] npm install vsce -g

Localization

To add any strings that you would like to be translated by the team, add strings to the XLF files found in localization\xliff\enu following the string format already found in the files.

Update the localizedPackage.json.enu.xlf file if you want to add localized strings to package.json and run the build task, this will generate a package.nls.json file where you can refer to specific strings in package.json via this format:

%string.key%

Update the constants/localizedConstants.enu.xlf file if you want to add localized strings to any of the code found in the src folder and run the build task, this will generate a localizedConstants.ts file.

To use the strings, make sure the localizedConstants file is imported in the file you want to localize, then you can refer to specific strings by using the format:

LocalizedConstants.stringKey

Strings with parameters will require a utils file import in the same file, and be formatted as:

utils.formatString(LocalizedConstants.stringKey, parameter1, parameter2);

Push any changes you made to the XLF files as well as the generated package.nls.json file into our branch so that our localization team will translate the strings, these will be merged in by our team once the translated resources have been generated and pushed in.

Build

To build the extension, run the following from the root of the repo:

gulp build

This command will create the out\src and out\test folders at the root of the repository.

Tests

Tests should be run with changes. Before you run tests, make sure you have built the extension. Run the following from the root of the repo:

gulp test

To run the tests within Visual Studio Code, change the debug profile to "Launch Tests" and press F5.

Package

The package command will package the extension into a Visual Studio extension installer (.vsix file). It will also transpile the TypeScript into the out\src and out\test folders.

From the root of the repo run one of these tasks

gulp package:offline
gulp package:online

The offline package will create the VSIX with the service dependencies bundled in for offline install. The online package will create the VSIX without the service dependencies - they will be downloaded when the extension is activated.

Contribution License Agreement

In order to contribute, you will need to sign a Contributor License Agreement. All you need to do is to submit a pull request, then the PR will get appropriately labeled (e.g. cla-required, cla-norequired, cla-signed, cla-already-signed). If you already signed the agreement we will continue with reviewing the PR, otherwise system will tell you how you can sign the CLA. Once you sign the CLA all future PR's will be labeled as cla-signed.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Submitting Pull Requests

We welcome pull requests! Fork this repo and send us your contributions. Go here to get familiar with GitHub pull requests.

Before submitting your request, ensure that both gulp build and gulp test succeed.

Creating a release

Releases are created automatically as part of the daily build. If for some reason you need to create your own pre-release build you can do so by going to the releases page and clicking the "draft new release" button. Ensure that you properly bump the version number from the previous release and insert that as the tag (example: previous v0.1.4-alpha.5 goes to v0.1.4-alpha.6) and make sure the branch is targeted at dev. The body will auto fill to be the commit measure for the most recent commit. Ensure you upload all the vsix files that are generated by the build system, including the online version (see previous releases for examples).

Alternatively you can run the "AutomatedReleases" powershell script located on the build machine which will do all this for you (this is what the build machine is running).

If you wish to create a non-prerelease release, follow the same steps but instead of pointing the branch at dev, point it at master instead and instead of bumping the prerelease number, bump the major/minor/patch number instead (e.g: a new patch update, previous: v0.1.4-alpha5 goes to v0.1.5). There is currently no script it perform this.

Table of Contents

Clone this wiki locally