Skip to main content

Contributing to the Framework

This is a TypeScript project managed by the projen tool. To contribute to the framework sub project, you need to have the following prerequisites:

Prerequisites​

  • Node.js v20
  • Yarn
  • Docker running locally

Setup​

  1. Clone the repository:

    git clone https://github.com/awslabs/data-solutions-framework-on-aws.git

  2. Navigate to the repository directory:

    cd data-solutions-framework-on-aws

  3. Install the project dependencies:

    yarn install

  4. Build the project using projen:

    npx projen build

Now you're ready to start contributing to the framework sub project!

Making Changes​

  1. Create a new branch for your changes:

    git checkout -b feat/my-feature-branch

  2. Make your changes to the code in the framework directory.

  3. Build the project again to ensure everything compiles correctly:

    npx projen build

Testing changes​

  1. Validate the changes in an AWS account
    1. Use the following code in a file (Ex: mytest.e2e.test.ts) in the framework/test/e2e folder and update corresponding values.
DO NOT COMMIT THIS FILE

This file used to iteratively test the construct during development should not be committed to the repository. Only standard e2e tests should be committed.

    /**
     * Testing my changes
     *
     * @group mytests
     */

    import * as cdk from 'aws-cdk-lib';
    import { TestStack } from './test-stack';

    jest.setTimeout(10000000);

    // GIVEN
    const app = new cdk.App();
    const stack = new Stack(app, 'E2eStack');
    const testStack = new TestStack('E2eTestStack', app, stack);

    stack.node.setContext('@data-solutions-framework-on-aws/removeDataOnDestroy', true);

    // LOGIC TO TEST

    new cdk.CfnOutput(stack, 'MyOutput', {
      value: <OUTPUT_VALUE_TO_TEST>,
    });


    let deployResult: Record<string, string>;


    beforeAll(async() => {
      // WHEN
      deployResult = await testStack.deploy();

    }, 10000000);

    it('mytest', async () => {
      // THEN
      expect(deployResult.MyOutput).toContain('<VALUE_TO_TEST>');
    });

  1. Deploy the stack
cd framework
npx jest --group=mytests

  1. Iterate and re-deploy the stack

  2. Create/update unit tests. They are required to validate the constructs at the Cloudformation level. Unit tests check the CFN template is matching what is expected. Follow the example of the DataLakeStorage here

  3. Create/update cdk-nag tests. They are required to validate the CDK code follows AWS Well Architected rules. Follow the example of the DataLakeStorage here. Add exceptions to CDK-nag when:

    1. Errors or warnings are raised on constructs that are not in the scope of the test. For example when encapsulating another construct which is already tested via its own CDK-nag tests.
    2. CDK native resources (provided by CDK itself) are raising errors but it cannot be configured. For example, the CDK custom resource provider has limited configuration and it's not possible to customize the custom resource provider framework itself.
    3. There is no workaround to follow best practices. For example, IAM permissions contains wildcards and can't be scoped down because the resource ID is unknown.

  4. Create/update e2e tests. They are required to test the deployment of the construct in an AWS account. Follow the example of the DataLakeStorage here

  5. Commit your changes:

    git add .

    git commit -m "My awesome changes"

  6. Push your changes to the remote repository:

    git push origin my-feature-branch

  7. Open a pull request on GitHub for your changes to be reviewed and merged.