Skip to content

Commit 6d372ab

Browse files
authored
docs: add clause about internal to guidelines (#3044)
1 parent f6b8794 commit 6d372ab

File tree

1 file changed

+1
-0
lines changed

1 file changed

+1
-0
lines changed

DEVELOPMENT_GUIDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ Integration tests are covered in detail in the [INTEGRATION_TESTS.md file](INTEG
168168
For new properties of SAM resources, use [`Property`](https://github.com/aws/serverless-application-model/blob/c5830b63857f52e540fec13b29f029458edc539a/samtranslator/model/__init__.py#L36-L45) or [`PassThroughProperty`](https://github.com/aws/serverless-application-model/blob/dd79f535500158baa8e367f081d6a12113497e45/samtranslator/model/__init__.py#L48-L56) instead of [`PropertyType`](https://github.com/aws/serverless-application-model/blob/c39c2807bbf327255de8abed8b8150b18c60f053/samtranslator/model/__init__.py#L13-L33). This avoids [sneaky bugs](https://github.com/aws/serverless-application-model/pull/2495#discussion_r976715242) and ensures valid templates do not cause transform failures.
169169

170170
For new properties of CloudFormation resources, use [`GeneratedProperty`](https://github.com/aws/serverless-application-model/blob/79452f69bc1fcf918b8625c2f9005c74ab874801/samtranslator/model/__init__.py#L74-L82). It performs no runtime validation, reducing the risk of valid values causing transform failures.
171+
7. **Write all new code under [`samtranslator/internal`](https://github.com/aws/serverless-application-model/tree/develop/samtranslator/internal) if possible.** This ensures we don't increase our "public" library interface and cause unnecessary breakages to consumers. While Python doesn't have private access modifiers, we assume anything [by convention private](https://peps.python.org/pep-0008/#descriptive-naming-styles) or under `internal` to be internal code, not bound by typical expectations of backward compatibility.
171172

172173
Code conventions
173174
----------------

0 commit comments

Comments
 (0)