Skip to content

Commit

Permalink
chore: add documentation around adding new dependencies (#19427)
Browse files Browse the repository at this point in the history
This adds a new section to the contributing guide that details how to
introduce an "unconventional" dependency. It also adds a new section to
the PR template that asks the submitter to verify whether their PR adds
any dependencies.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
corymhall committed Mar 18, 2022
1 parent 7fcc0c0 commit 2f01bf0
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 0 deletions.
8 changes: 8 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,12 @@

----

### All Submissions:

* [ ] Have you followed the guidelines in our [Contributing guide?](../CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](../CONTRIBUTING.md/#adding-new-unconventional-dependencies)

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
27 changes: 27 additions & 0 deletions CONTRIBUTING.md
Expand Up @@ -292,6 +292,8 @@ $ yarn watch & # runs in the background

* Shout out to collaborators.

* Call out any new [unconventional dependencies](#adding-new-unconventional-dependencies) that are created as part of your PR.

* If not obvious (i.e. from unit tests), describe how you verified that your change works.

* If this PR includes breaking changes, they must be listed at the end in the following format
Expand All @@ -312,6 +314,30 @@ $ yarn watch & # runs in the background
* Make sure to update the PR title/description if things change. The PR title/description are going to be used as the
commit title/message and will appear in the CHANGELOG, so maintain them all the way throughout the process.

#### Adding new unconventional dependencies

**For the aws-cdk an unconventional dependency is defined as any dependency that is not managed via the module's
`package.json` file.**

Sometimes constructs introduce new unconventional dependencies. Any new unconventional dependency that is introduced needs to have
an auto upgrade process in place. The recommended way to update dependencies is through [dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates).
You can find the dependabot config file [here](./.github/dependabot.yml).

An example of this is the [@aws-cdk/lambda-layer-awscli](packages/@aws-cdk/lambda-layer-awscli) module.
This module creates a lambda layer that bundles the AWS CLI. This is considered an unconventional
dependency because the AWS CLI is bundled into the CDK as part of the build, and the version
of the AWS CLI that is bundled is not managed by the `package.json` file.

In order to automatically update the version of the AWS CLI, a custom build process was
created that takes upgrades into consideration. You can take a look at the files in
[packages/@aws-cdk/lambda-layer-awscli/layer](packages/@aws-cdk/lambda-layer-awscli/layer)
to see how the build works, but at a high level a [requirements.txt](packages/@aws-cdk/lambda-layer-awscli/layer/requirements.txt)
file was created to manage the version. This file was then added to [dependabot.yml](https://github.com/aws/aws-cdk/blob/ab57eb6d1ed69b40ed6ec774853c275785acace8/.github/dependabot.yml#L14-L20)
so that dependabot will automatically upgrade the version as new versions are released.

**If you think your PR introduces a new unconventional dependency, make sure to call it
out in the description so that we can discuss the best way to manage that dependency.**

### Step 5: Merge

* Make sure your PR builds successfully (we have CodeBuild setup to automatically build all PRs).
Expand Down Expand Up @@ -343,6 +369,7 @@ Breaking changes come in two flavors:
* API surface changes
* Behavior changes


### API surface changes

This encompasses any changes that affect the shape of the API. Changes that
Expand Down

0 comments on commit 2f01bf0

Please sign in to comment.