Skip to content

Commit 2f01bf0

Browse files
authored
chore: add documentation around adding new dependencies (#19427)
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*
1 parent 7fcc0c0 commit 2f01bf0

File tree

2 files changed

+35
-0
lines changed

2 files changed

+35
-0
lines changed

.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
11

22
----
33

4+
### All Submissions:
5+
6+
* [ ] Have you followed the guidelines in our [Contributing guide?](../CONTRIBUTING.md)
7+
8+
### Adding new Unconventional Dependencies:
9+
10+
* [ ] This PR adds new unconventional dependencies following the process described [here](../CONTRIBUTING.md/#adding-new-unconventional-dependencies)
11+
412
*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

CONTRIBUTING.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,8 @@ $ yarn watch & # runs in the background
292292

293293
* Shout out to collaborators.
294294

295+
* Call out any new [unconventional dependencies](#adding-new-unconventional-dependencies) that are created as part of your PR.
296+
295297
* If not obvious (i.e. from unit tests), describe how you verified that your change works.
296298

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

317+
#### Adding new unconventional dependencies
318+
319+
**For the aws-cdk an unconventional dependency is defined as any dependency that is not managed via the module's
320+
`package.json` file.**
321+
322+
Sometimes constructs introduce new unconventional dependencies. Any new unconventional dependency that is introduced needs to have
323+
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).
324+
You can find the dependabot config file [here](./.github/dependabot.yml).
325+
326+
An example of this is the [@aws-cdk/lambda-layer-awscli](packages/@aws-cdk/lambda-layer-awscli) module.
327+
This module creates a lambda layer that bundles the AWS CLI. This is considered an unconventional
328+
dependency because the AWS CLI is bundled into the CDK as part of the build, and the version
329+
of the AWS CLI that is bundled is not managed by the `package.json` file.
330+
331+
In order to automatically update the version of the AWS CLI, a custom build process was
332+
created that takes upgrades into consideration. You can take a look at the files in
333+
[packages/@aws-cdk/lambda-layer-awscli/layer](packages/@aws-cdk/lambda-layer-awscli/layer)
334+
to see how the build works, but at a high level a [requirements.txt](packages/@aws-cdk/lambda-layer-awscli/layer/requirements.txt)
335+
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)
336+
so that dependabot will automatically upgrade the version as new versions are released.
337+
338+
**If you think your PR introduces a new unconventional dependency, make sure to call it
339+
out in the description so that we can discuss the best way to manage that dependency.**
340+
315341
### Step 5: Merge
316342

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

372+
346373
### API surface changes
347374

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

0 commit comments

Comments
 (0)