RFC: Powertools libraries naming convention

[saragerion]

Key information

• RFC PR: (leave this empty)
• Related issue(s), if known: n/a
• Area: all
• Meet tenets: Yes
• Approved by:
• Reviewed by:

Summary

The goal of this RFC is to have a unique, standardised and easy to understand naming convention for each Powertools library in all places, including across different languages.

Motivation

Currently, in our documentation the library is referred in different ways:

• AWS Lambda Powertools (TypeScript)
• Lambda Powertools TypeScript
• AWS Lambda Powertools TypeScript
• AWS Lambda Powertools for TypeScript

.

TypeScript is used here as example, but the same applies to Python, Java, and other upcoming languages.

As the number of languages supported by the AWS Lambda Powertools grows, there is an opportunity to make the name of the project clearer and consistent among different languages/runtime.
The conversation among maintainers about the library's naming convention was generated by this comment in this HN thread.

Proposal

The library name of a specific language is "AWS Lambda Powertools for [Language]":

• AWS Lambda Powertools for Python
• AWS Lambda Powertools for Java
• AWS Lambda Powertools for TypeScript

As consequence, all the versions below should be changed accordingly to the new one:

• AWS Lambda Powertools (TypeScript)
• Lambda Powertools TypeScript
• AWS Lambda Powertools TypeScript

If this feature should be available in other runtimes (e.g. Java), how would this look like to ensure consistency?

User Experience

Customers should not be impacted as this does only affect the documentation.

Drawbacks

N/A

Rationale and alternatives

The maintainers have considered also these versions (TypeScript as example):

• AWS Lambda Powertools TypeScript
• AWS Lambda Powertools (TypeScript)
  But AWS Lambda Powertools for TypeScript was the winner.

• What other designs have been considered? Why not them?
• What is the impact of not doing this?

Unresolved questions

Impacted repositories

https://github.com/awslabs/aws-lambda-powertools-python
https://github.com/awslabs/aws-lambda-powertools-java
https://github.com/awslabs/aws-lambda-powertools-typescript
https://github.com/aws-samples/aws-lambda-powertools-examples

[dreamorosi]

Would this change affect also the name of the actual repos on GitHub? I.e. https://github.com/awslabs/aws-lambda-powertools-typescript would become https://github.com/awslabs/aws-lambda-powertools-for-typescript?

Other than that 100% in favor with standardising the names using your proposal.

[sliedig]

@dreamorosi No, the repo names stay the same

[heitorlessa]

@saragerion thank you for kicking this off! We've got all leads vote so we can go ahead and implement the new convention - AWS Lambda Powertools for .

[heitorlessa]

@pankajagrawal16 I missed your vote at the top but I know you are in agreement too - please let us know otherwise.

[michaelbrewer]

I worked on a PR to try this before to be AWS Lambda Powertools (<Language>) for all versions, but this seems to be another version of that.

[heitorlessa]

Yes @michaelbrewer, this is what all maintainers across all languages have agreed.

---

@saragerion @sliedig @dreamorosi @pankajagrawal16 @am29d @mploski @flochaz as I make several changes in the Python docs, package metadata, etc., I noticed we should have an exception: a shorter name after the long name has been used, just like we have in some AWS Services official branding.

I'd suggest subsequent references can optionally use AWS Lambda Powertools.

A few examples where we already used AWS Lambda Powertools for Python multiple times in the same doc, but use the shorter version to remain on brand and not further prolong longer sentences, code snippets titles, banners with limited space:

Refactoring with AWS Lambda Powertools Logger (code snippet)

Let's include AWS Lambda Powertools as a dependency in requirement.txt

As we already have AWS Lambda Powertools as a dependency, we can simply import Logger

Let's explore how we can instrument our code with AWS X-Ray SDK{target="_blank"}, and then simplify it with AWS Lambda Powertools Tracer{target="_blank"} feature.

[michaelbrewer]

Cool. Just wondering, as I made PRs earlier to correct this. Good that you have internally agreed on new names.

[saragerion]

Note, after further internal discussion among maintainers, we have agreed that the "short" version of the library can be just "Powertools".
We will make this decision explicit in the homepage of the documentation, the second time that the name it's referenced.
Example for Typescript:

The AWS Lambda Powertools for TypeScript utilities (which from here will be referred as Powertools) ...

[michaelbrewer]

My recommendation is limit the use of "AWS Lambda Powertools For XXXX" to the main titles only and use the short name "AWS Lambda Powertools" for the rest of the docs or when referencing the collective.

Once within the main docs, I don't see the need to use the fully qualified name, and just use "AWS Lambda Powertools", at this point you know you are within the scope of that language.

The main package name does not need to change as it is implicit (pip (python) version is for python).

The repo name is already explicit ie: "aws-lambda-powertools-xxxx", and renaming would break any existing clones of the repo.