CONTRIBUTING.md

Contributing

Adding a new service

If the jslib-aws does not support the service you need yet, the best way to get it to help is by contributing to it.

Useful information

1. The project uses the TypeScript language. TypeScript is a superset of the Javascript language and essentially adds static typing and functional constructs to the language. It compiles into Javascript, which is then used by the k6 runtime.
2. The project files should be formatted using the Prettier tool. The project has a .prettierrc.json file containing the tool's configuration.
3. The project uses webpack to produce build files. Because k6 does not have native support typescript, and its Javascript runtime does not support the import statement, the project uses webpack to produce a file containing all the code that k6 scripts can use. The project has a webpack.config.js file containing the tool's configuration. Each service is built into its dedicated file, and an overarching aws.js contains them for convenience.
4. To allow easier testing, files in the src directory are organized in a public/private structure. Files at the root of the folder are the public files; they import the content of the internal (private) directory and explicitly export the symbols that should be made available to the user. The internal files are the ones that contain the actual implementation of the service. The internal files are not exported and are not meant to be used directly by the user.
5. The project is tested in an end2end fashion using the k6 tool. The tests live in the tests directory. The tests are written in Javascript and use the k6 chai js jslib to test the functionality of the library. The npm test command runs the test suites. The tests run in a docker container, and the docker-compose.yml file contains the configuration for the container. The docker-compose setup spins up a localstack setup, which emulates AWS locally, and the test script performs its assertions against it directly.

Conventions

1. The project uses the kebab-case naming convention for files and directories.
2. The project uses the pascal-case naming convention for classes, interfaces, and types.
3. Service client class names should be of the form ServiceNameClient, where ServiceName is the name of the service, in pascal-case, or all capitalized if it is an acronym (as in: KMSClient, S3Client, SQSClient, etc.).

How to add a new service

1. Create a new file in the src/internal directory. The file's name should be the service's name in kebab-case. For example, if you want to add support for the AWS Systems Manager service, the file should be named systems-manager.ts.
2. The file should expose a service client class following the above conventions. The class should inherit from AWSClient, and its constructor should take an AWSConfig object as its only argument.
3. For each service operation (action) the author wishes to implement, the service class should implement a dedicated public method.
4. Most service operations require signing requests using the AWS V4 signature process. The SignatureV4 construct exposed in the src/internal/signature.ts file allows signing requests to AWS services easily. Checkout the existing service implementations for examples of how to use it: in S3Client, and in SecretsManagerService for instance.
5. Tests verifying that the service class works as expected should be added in the tests/internal directory. The dedicated test file should follow the same naming convention as the service class file, except it should have the .js extension. For example, if the service class file is named systems-manager.ts, the test file should be called systems-manager.js.
6. Test files should consists in a k6 script using the k6 chai js library, and exporting a single {serviceName}TestSuite(data) function. This function should consist of a set of describe statements containing the actual test assertions, as demonstrated in the existing s3 test suite. The test suite should be imported and called in the tests/internal/index.js test script, which is the entry point for the test suite.
7. If the tests depend on a specific pre-existing state of the localstack setup, you can add a dedicated script in the tests/internal/localstack_init folder. Localstack will execute all the commands present in this script during its setup phase.
8. The npm test command runs the test suite. This command will build the project and run the tests against the spun-up localstack docker container. The docker-compose.yml file contains the configuration for the container.
9. Once the tests pass, the src/index.ts file should export the service class in the src/index.ts file so the user can use it.
10. To get the build system to produce a dedicated

Publishing a new version

Expectations

1. The service should have tests.
2. The service should have documentation.
3. The service should be re-exported in the src/index.ts file.
4. The service should be exposed in the aws.js file in the build directory when running the npm run webpack command.
5. The service should produce a dedicated {service-name}.js file in the build directory when running the npm run webpack command.
6. The service should produce source map files for the dedicated {service-name}.js file and the aws.js file in the build directory when running the npm run webpack command.

Steps

Prepare a version PR

In a PR:

1. Bump the version in the package.json file.
2. Run the npm update command to update the package-lock.json file.
3. Run the npm run webpack command to ensure the build system produces the latest distributable files.

Create a tag and GitHub version

1. Tag the latest main branch's commit with the new version, following the semantic versioning convention, prefixed with a v character, as in: v0.7.1.
2. Create a dedicated GitHub version:
   1. Pointing to the tag created above
   2. Using the same name as the tag created above
   3. Including the build files included in the commit tagged above

Publishing the new version

1. Open a PR on the jslib repository using the build/ directory files following the new version instructions.
2. Make sure the k6 documentation website is updated to include the new version of the library:
   1. The documented API should reflect the new version.
   2. All the links to the library should point to the new version.