Skip to content
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.

Sign up for GitHub

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

docs: create v2 upgrading guide skeleton #22696

Merged
merged 3 commits into from
Dec 20, 2024
Merged

docs: create v2 upgrading guide skeleton #22696

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cde85b5
docs: create v2 upgrading guide
julienrbrt Nov 29, 2024
64cc446
updates
julienrbrt Dec 20, 2024
25d623a
remove todos, keep clean point to pr
julienrbrt Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions UPGRADING_v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Upgrading Cosmos SDK v2.x.y

This guide provides instructions for upgrading to specific versions of Cosmos SDK.
Note, always read the **SimApp** section for more information on application wiring updates.

## Upgrading from v0.52.x to v2.0.0

First and foremost, v2 uses [depinject](./depinject/README.md) to wire the module and application dependencies. This guides assumes you have already made your modules depinject compatible, and that you made use of depinject in your application.

### Modules

* sdk.Context to core service migration: https://hackmd.io/@julienrbrt/S16-_Vq50
* AnteHandler to TxValidator
* Optional migration from grpc services to handlers
* [Documentation]: Module configuration #22371
julienrbrt marked this conversation as resolved.
Show resolved Hide resolved

### Server

TODOs:

* Telemetry server is another port (1328)
* New REST server for querying modules (8080) -> Use post and type_url (docs at server/v2/api/rest/README.md)
* gRPC: new service to query the modules gRPC messages, without going via module services
* gRPC: external gRPC services no more registered in the application router (e.g. nodeservice, cmtservice, authtx service)
Copy link
Contributor

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

Format and expand TODOs section

The TODOs section needs proper formatting and more detailed explanations.

Apply these changes:

-TODOs:
-
-* Telemetry server is another port (1328)
-* New REST server for querying modules (8080) -> Use post and type_url (docs at server/v2/api/rest/README.md)
-* gRPC: new service to query the modules gRPC messages, without going via module services
-* gRPC: external gRPC services no more registered in the application router (e.g. nodeservice, cmtservice, authtx service)
+### Breaking Changes
+
+#### Telemetry Server
+* The telemetry server now runs on a dedicated port (1328)
+* Migration required: Update your monitoring configuration to use the new port
+
+#### REST Server
+* New dedicated REST server for module queries runs on port 8080
+* Uses POST method with type_url for queries
+* Refer to detailed documentation at `server/v2/api/rest/README.md`
+
+#### gRPC Changes
+* New service implementation for module gRPC message queries
+* External gRPC services (nodeservice, cmtservice, authtx service) are no longer registered in the application router
+* Migration required: Update your service discovery and client configurations
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
TODOs:
* Telemetry server is another port (1328)
* New REST server for querying modules (8080) -> Use post and type_url (docs at server/v2/api/rest/README.md)
* gRPC: new service to query the modules gRPC messages, without going via module services
* gRPC: external gRPC services no more registered in the application router (e.g. nodeservice, cmtservice, authtx service)
### Breaking Changes
#### Telemetry Server
* The telemetry server now runs on a dedicated port (1328)
* Migration required: Update your monitoring configuration to use the new port
#### REST Server
* New dedicated REST server for module queries runs on port 8080
* Uses POST method with type_url for queries
* Refer to detailed documentation at `server/v2/api/rest/README.md`
#### gRPC Changes
* New service implementation for module gRPC message queries
* External gRPC services (nodeservice, cmtservice, authtx service) are no longer registered in the application router
* Migration required: Update your service discovery and client configurations


### SimApp

With the migration to server/v2 and runtime/v2 some changes are required in the `root.go` and `app.go` of your application.

#### `app.go`

#### `root.go`
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Add content to empty sections

The app.go and root.go sections are empty but crucial for the upgrade process.

Would you like me to help draft the content for these sections? They should include:

  • Required changes to application initialization
  • New dependency injection setup
  • Configuration changes


## Upgrading from v0.50.x to v2.0.0

Upgrading directly from v0.50.x to v2.0.0 is supported.
Modules should be updated to support all the latest changes in the SDK.

Read the module section from the v0.52 [UPGRADING.md](UPGRADING.md) file for more information.
Then simply follow the instructions from the [v0.52 section](#upgrading-from-v052x-to-v200) from this file.
Comment on lines +49 to +50
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Fix broken link and enhance migration path

The link fragment is incorrect and the migration path needs more detail.

-Read the module section from the v0.52 [UPGRADING.md](UPGRADING.md) file for more information.
-Then simply follow the instructions from the [v0.52 section](#upgrading-from-v052x-to-v200) from this file.
+1. First, read the module section from the v0.52 [UPGRADING.md](UPGRADING.md) file
+2. Then follow the instructions in the [v0.52.x to v2.0.0 section](#upgrading-from-v052x-to-v200) above
+
+### Migration Checklist
+- [ ] Update module dependencies to v0.52.x compatible versions
+- [ ] Apply all breaking changes from v0.52.x
+- [ ] Follow the v2.0.0 upgrade steps above
+- [ ] Test thoroughly with the new architecture
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Read the module section from the v0.52 [UPGRADING.md](UPGRADING.md) file for more information.
Then simply follow the instructions from the [v0.52 section](#upgrading-from-v052x-to-v200) from this file.
1. First, read the module section from the v0.52 [UPGRADING.md](UPGRADING.md) file
2. Then follow the instructions in the [v0.52.x to v2.0.0 section](#upgrading-from-v052x-to-v200) above
### Migration Checklist
- [ ] Update module dependencies to v0.52.x compatible versions
- [ ] Apply all breaking changes from v0.52.x
- [ ] Follow the v2.0.0 upgrade steps above
- [ ] Test thoroughly with the new architecture
🧰 Tools
🪛 Markdownlint (0.37.0)

62-62: null
Link fragments should be valid

(MD051, link-fragments)

Loading