Thank you for your interest in contributing to our project. We greatly value feedback and contributions from our community!
Reviewing this document will maximize your success in working with the codebase and sending pull requests.
If you're looking for ideas about where to contribute, consider good first issue issues.
To develop this project, install these dependencies:
- Visual Studio Code
- NodeJS and NPM
- NodeJS Version: 12.x
- NPM version: 7.x or higher
- Typescript
- Git
- (optional) Set
git blame
to ignore noise-commits:git config blame.ignoreRevsFile .git-blame-ignore-revs
- (optional) Set
- AWS
git secrets
- (optional) AWS SAM CLI
- (optional) Docker
Then clone the repository and install NPM packages:
cd ~/repos
git clone git@github.com:aws/aws-toolkit-vscode.git
cd aws-toolkit-vscode
npm install
You can run the extension from Visual Studio Code:
- Select the Run panel from the sidebar.
- From the dropdown at the top of the Run pane, choose
Extension
. - Press
F5
to launch a new instance of Visual Studio Code with the extension installed and the debugger attached.
When you launch the extension or run tests from Visual Studio Code, it will automatically build the extension and watch for changes.
You can also use these NPM tasks (see npm run
for the full list):
- To build once:
npm run compile
- To build and watch for file changes:
npm run watch
- To build a release artifact (VSIX):
npm run package
- This uses webpack which may exhaust the default Node heap size on Linux.
To fix this set
--max-old-space-size
:export NODE_OPTIONS=--max-old-space-size=8192
- This uses webpack which may exhaust the default Node heap size on Linux.
To fix this set
- To build a "debug" VSIX artifact (faster and does not minify):
npm run package -- --debug
See CODE_GUIDELINES.md for coding conventions.
-
VSCode extensions have a 100MB file size limit.
-
src/testFixtures/
is excluded in.vscode/settings.json
, to prevent VSCode from treating its files as project files. -
VSCode extension examples: https://github.com/microsoft/vscode-extension-samples
-
Tests
- Use
function ()
andasync function ()
syntax fordescribe()
andit()
callbacks instead of arrow functions. - Do NOT include any
await
functions indescribe()
blocks directly (usage inbefore
,beforeEach
,after
,afterEach
, andit
blocks is fine).await
indescribe()
causes the framework to always evaluate thedescribe
block and can cause issues with either tests not running or always running (if other tests are marked with.only
)- Tests that require a premade value from a Promise should initialize the value as a
let
and make theawait
ed assignment inbefore()
.
- Use
-
How to debug unresolved promise rejections:
- Declare a global unhandledRejection handler.
process.on('unhandledRejection', e => { getLogger('channel').error( localize( 'AWS.channel.aws.toolkit.activation.error', 'Error Activating {0} Toolkit: {1}', getIdeProperties().company, (e as Error).message ) ) if (e !== undefined) { throw e } })
- Put a breakpoint on it.
- Run all tests.
- Declare a global unhandledRejection handler.
See TESTPLAN.md to understand the project's test structure, mechanics and philosophy.
You can run tests directly from Visual Studio Code:
- Select
View > Debug
, or select the Debug pane from the sidebar. - From the dropdown at the top of the Debug pane, select the
Extension Tests
configuration. - Press
F5
to run tests with the debugger attached.
You can also run tests from the command line:
npm run test
npm run integrationTest
Tests will write logs to ./.test-reports/testLog.log
.
To run a single test in VSCode, do any one of:
-
Run the Extension Tests (current file) launch-config.
-
Use Mocha's it.only() or
describe.only()
. -
Run in your terminal:
- Unix/macOS/POSIX shell:
NO_COVERAGE=true TEST_FILE=src/test/foo.test npm run test
- Powershell:
$Env:NO_COVERAGE = "true"; $Env:TEST_FILE = "src/test/foo.test"; npm run test
- Unix/macOS/POSIX shell:
-
To run all tests in a particular subdirectory, you can edit
src/test/index.ts:rootTestsPath
to point to a subdirectory:rootTestsPath: __dirname + '/shared/sam/debugger/'
You can find the coverage report at ./coverage/index.html
after running the tests.
Before sending a pull request:
- Check that you are working against the latest source on the
master
branch. - Check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
- Open an issue to discuss any significant work.
To send a pull request:
- Fork the repository.
- Modify the source; focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
- Ensure local tests pass.
- Commit to your fork using clear commit messages.
- Once you are done with your change, run
npm run newChange
, follow the prompts, then commit the changelog item to your fork. - Send us a pull request, answering any default questions in the pull request interface.
- Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides additional document on forking a repository and creating a pull request.
Generally, your pull request description should be a copy-paste of your commit message(s). If your PR description provides insight not found in a commit message, ask why. Source control (Git) is our source-of-truth, not GitHub.
Quick summary of commit message guidelines:
-
Subject: single line up to 50-72 characters
- Imperative voice ("Fix bug", not "Fixed"/"Fixes"/"Fixing").
-
Body: for non-trivial or uncommon changes, explain your motivation for the change and contrast your implementation with previous behavior.
- Often you can save a lot of words by using this simple template:
Problem: … Solution: …
- Often you can save a lot of words by using this simple template:
A good commit message has a short subject line and unlimited detail in the body. Good explanations are acts of creativity. The "tiny subject line" constraint reminds you to clarify the essence of the commit, and makes the log easy for humans to scan. The commit log is an artifact that will live longer than any code in the codebase.
Consider prefixing the subject with a topic: this again helps humans (and
scripts) scan and omit ranges of the history at a glance. For example if I'm
looking for a code change, I can eliminate all of the doc:
and test:
commits when inspecting this commit log:
doc: update README.md
test: Deploy wizard
SAM debug: fix bug in foo
doc: explain SAM debug architecture
Lambda: add button to thing
Each commit and pull request is processed by an automated system which runs all tests and provides the build result via the Details link as shown below.
Besides the typical develop/test/run cycle describe above, there are some tools for special cases such as build tasks, generating telemetry, generating SDKs, etc.
When the AWS SDK does not (yet) support a service but you have an API
model file (*.api.json
), use generateServiceClient.ts
to generate
a TypeScript *.d.ts
file and pass that to the AWS JS SDK to create
requests just from the model/types.
-
Add an entry to the list in
generateServiceClient.ts
:diff --git a/build-scripts/generateServiceClient.ts b/build-scripts/generateServiceClient.ts index 8bb278972d29..6c6914ec8812 100644 --- a/build-scripts/generateServiceClient.ts +++ b/build-scripts/generateServiceClient.ts @@ -199,6 +199,10 @@ ${fileContents} ;(async () => { const serviceClientDefinitions: ServiceClientDefinition[] = [ + { + serviceJsonPath: 'src/shared/foo.api.json', + serviceName: 'ClientFoo' + }, { serviceJsonPath: 'src/shared/telemetry/service-2.json', serviceName: 'ClientTelemetry',
-
Run the script:
./node_modules/.bin/ts-node ./build-scripts/generateServiceClient.ts
-
The script produces a
*.d.ts
file (used only for IDE code-completion, not required to actually make requests):src/shared/foo.d.ts
-
To make requests with the SDK, pass the
*.api.json
service model toext.sdkClientBuilder.createAndConfigureServiceClient
as a genericService
withapiConfig=require('foo.api.json')
.// Import the `*.d.ts` file for code-completion convenience. import * as ClientFoo from '../shared/clientfoo' // The AWS JS SDK uses this to dynamically build service requests. import apiConfig = require('../shared/foo.api.json') ... const c = await ext.sdkClientBuilder.createAwsService( opts => new Service(opts), { apiConfig: apiConfig, region: 'us-west-2', credentials: credentials, correctClockSkew: true, endpoint: 'foo-beta.aws.dev', }) as ClientFoo const req = c.getThing({ id: 'asdf' }) req.send(function (err, data) { ... });
If you are contribuing visual assets from other open source repos, the source repo must have a compatible license (such as MIT), and we need to document the source of the images. Follow these steps:
-
Use a separate location in this repo for every repo where images are sourced from, in the form
third-party/resources/from-<BRIEF_REPO_NAME>
. -
Copy the source repo's licence into this destination location's LICENSE.txt file
-
Create a README.md in the destination location, and type in a copyright attribution:
The AWS Toolkit for VS Code includes the following third-party software/licensing: Icons contained in this folder and subfolders are from <SOURCE_REPO_NAME>: <SOURCE_REPO_URL> <PASTE_SOURCE_LICENSE_HERE>
-
Copy the SVG file(s) into a suitable place within the destination location, for example
.../dark/xyz.svg
and.../light/xyz.svg
-
Add an entry to
third-party/README.md
summarizing the new destination location, where the asserts were sourced from, and a brief rationale.
PR #227 shows an example.
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via the vulnerability reporting page. Please do not create a public issue.
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.