Skip to content

docs(v2): Create upgrade guide and versioning policy #1856

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 28 commits into
base: v2
Choose a base branch
from

Conversation

phipag
Copy link
Contributor

@phipag phipag commented May 21, 2025

Issue #, if available: #1804

Description of changes:

Rendered preview: https://dealn7fl31ram.cloudfront.net/upgrade/

This documentation update contains smaller fixes and a comprehensive upgrade from v1 to v2. This will be treated as a living document and will be updated as breaking changes happen during developer preview.

Checklist

@phipag phipag self-assigned this May 21, 2025
@phipag phipag added documentation Improvements or additions to documentation v2 Version 2 labels May 21, 2025
@dreamorosi dreamorosi self-requested a review May 21, 2025 15:50
Copy link

@leandrodamascena leandrodamascena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @phipag! What an amazing job! I just left 2 comments.

dreamorosi and others added 3 commits May 22, 2025 22:07
Co-authored-by: Stefano Vozza <[email protected]>
Co-authored-by: Stefano Vozza <[email protected]>
Co-authored-by: Stefano Vozza <[email protected]>
Copy link

@@ -1,10 +1,11 @@
site_name: Powertools for AWS Lambda (Java) Preview
site_description: Powertools for AWS Lambda (Java) Preview
site_author: Amazon Web Services
site_url: https://docs.powertools.aws.dev/lambda-java/
site_url: https://docs.powertools.aws.dev/lambda/java/preview/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the /preview suffix?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should handle versioning differently and keep the base url intact (SEO and all that stuff).

In a nutshell, we need to add a versions.json file like this one with the two versions in this case that we want to show and mkdocs should pick it up.

For now latest would be whatever is on alias v1 and next (or something else) would be preview. Closer to v2 release we can swap them and rename v1 as legacy or just v1 but the base url always stays the same.

MKdocs also has the ability to automatically add a top-banner that informs readers they're not on the latest version.

Copy link

@dreamorosi dreamorosi requested a review from svozza May 22, 2025 20:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation size/XL v2 Version 2
Projects
Status: Pending review
Development

Successfully merging this pull request may close these issues.

4 participants