From 7143b22b12dc8ed1e7d0c81e27ba9f501c5926f5 Mon Sep 17 00:00:00 2001 From: Chaoyi Yuan Date: Mon, 15 May 2023 14:24:30 +0800 Subject: [PATCH 1/2] docs: port John's changes --- .../core/v3Migration/upgradeReport.md | 57 +++++++++---------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/packages/fx-core/templates/core/v3Migration/upgradeReport.md b/packages/fx-core/templates/core/v3Migration/upgradeReport.md index cdf74cdf9c..468dbeaf98 100644 --- a/packages/fx-core/templates/core/v3Migration/upgradeReport.md +++ b/packages/fx-core/templates/core/v3Migration/upgradeReport.md @@ -1,50 +1,49 @@ -# Upgrade Summary +# Review project upgrade and changes -Congratulations! You can continue your development now. Your project has been upgraded to work with the latest Teams Toolkit. +Your project was automatically upgraded to work with this version of Teams Toolkit. The upgrade is one-way, and you will not be able to use the version of Teams Toolkit in which it was originally created unless you [roll back the changes](#how-to-roll-back-after-the-upgrade). -Most of existing features behave similar with previous Teams Toolkit. You can visit https://aka.ms/teamsfx-v5.0-guide to learn the new features. And read [Important changes to your development flow](#important-changes-to-your-development-flow) to understand the changes to your development flow. - -Visit https://aka.ms/teams-toolkit-5.0-upgrade to learn more about the upgrade. +> If you encountered a problem after the automatic upgrade, review the [known issues](https://aka.ms/teams-toolkit-5.0-upgrade#known-issues). If you are still having trouble, contact ttkfeedback@microsoft.com or [file an issue on GitHub](https://github.com/officedev/teamsfx/issues) with details about the problem. ## Important changes to your development flow -There's no immediate action required from you. This part illustrates what's changed to your development flow. -> If you encountered any errors or issues after upgrade, you could try the following steps or visit [known issues](https://aka.ms/teams-toolkit-5.0-upgrade#known-issues) for details. +The new features in this release make developing your apps simpler and more flexible, but also include changes to how the toolkit creates projects, automates configuration, and deploys resources. Visit [the upgrade guide](https://aka.ms/teamsfx-v5.0-guide) for more info about all of the changes. + +Some of the changes you may immediately notice are: + +* Configuration of the lifecycle management using Provision, Deploy, and Publish are now fully customizable and expressed in `teamsapp.local.yml` and `teamsapp.yml`. [More info](https://aka.ms/teamsfx-v5.0-guide#project-files) +* Configuration and values that were saved in `.fx/config` and `.fx/state` are now handled with environment files and saved to `/env` by default. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) +* The changes to use environment files give greater flexibility of configuring which resources are used to provision, but may require some manual steps when creating new environments. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) +* Teams Toolkit no longer prompts you for which environment to use when using the Launch targets in `launch.json`. You can edit `.vscode/launch.json` and configure which environments are used. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#launch-your-app) -1. You need to sync `env/.env.{env}.user` files between different machines manually. All these files will be gitignored by default. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) -2. You need to take some manual steps when creating or provisioning new environments for your old project. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) -3. You need to manually update `.vscode/launch.json` when launching your app for a certain environment if your current project contains it. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#launch-your-app) -4. You need to provide values to `APIM__PUBLISHEREMAIL` and `APIM__PUBLISHERNAME` environment variable if your current project uses APIM. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#provision-apim-service) -5. You need to manually update `Start local tunnel` task in `.vscode/task.json` if you have customized this task. Teams Toolkit now uses Dev Tunnel as default tunnel solution. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#start-tunnel-service) +If you're using APIM: +* You need to provide values to `APIM__PUBLISHEREMAIL` and the `APIM__PUBLISHERNAME` environment variables. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#provision-apim-service) -You can visit this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#feature-changes-that-impact-your-development-flow) to learn more changes to Teams Toolkit. +You can [view these changes on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#feature-changes-that-impact-your-development-flow). -## Changes to your project +## Changes to your project file structure -1. Created `teamsapp.yml` and `teamsapp.local.yml` in your project root folder. +1. Created `teamsapp.yml` and `teamsapp.local.yml` in your projects root directory. 2. Moved environment files in `.fx` to `.env.{env}` in `env` folder. 3. If your project contains file `.fx/states/{env}.userdata`, the content will be moved to `.env.{env}.user` in `env` folder -4. Moved `templates/appPackage` to `appPackage`, renamed `manifest.template.json` to `manifest.json` and placeholders in it will be updated per the latest Teams Toolkit requirement. -5. If your project contains file `templates/appPackage/aad.template.json`, it will be moved and renamed as `aad.manifest.json` and placeholders in it will be updated per the latest Teams Toolkit requirement. +4. Moved `templates/appPackage` to `appPackage`, renamed `manifest.template.json` to `manifest.json` and placeholders in it will be updated using the latest default conventions. +5. If your project contains `templates/appPackage/aad.template.json`, it will be moved and renamed to `aad.manifest.json` and the templated variables names are updated to the latest default conventions. 6. If your project contains file `.vscode/tasks.json` and `.vscode/launch.json`, they will be updated. 7. Updated `.gitignore` to ignore new environment user files. 8. Removed `.fx` folder. -For more detailed changes, please refer to this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#file-changes). +You can [view these changes on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#file-changes). ## Known issues -1. If your project only contains a bot, you may meet error that complains `STATE__FX_RESOURCE_FRONTEND_HOSTING__ENDPOINT` is missing when executing commands. Replace this placeholder with a valid URL in `appPackage/manifest.json` to fix it. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#state__fx_resource_frontend_hosting__endpoint-missing-error-in-some-projects) - -2. If your project is created with Visual Studio version < 17.4, you may see error `InvalidParameter: Following parameter is missing or invalid for aadApp/create action: name` when executing commands. Please follow [the steps](#how-to-roll-back) to roll back, install VS 17.4 and run upgrade first. - -3. If your tab app is created with Teams Toolkit 3.2.0 or earlier version, you may see error `simpleAuthEndpoint in configuration is invalid` when remote debugging your app. Please follow this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#simpleauthendpoint-in-configuration-is-invalid) to learn how to mitigate this error. -4. If your project can be provisioned successfully before, but after upgrade it cannot be provisioned or published by `teamsApp/validateAppPackage` actione, please use the [validation](https://dev.teams.microsoft.com/validation) to check your appPackage zip file and fix the error. [Learn More](https://aka.ms/teams-toolkit-5.0-upgrade#teamsappvalidateapppackage-failed-error) +1. If your project only contains a bot, you might get an error about `STATE__FX_RESOURCE_FRONTEND_HOSTING__ENDPOINT` missing when running Provision or using Start Debugging. Find this placeholder variable in `appPackage/manifest.json` and replace it with a valid URL to resolve this issue. [More Info](https://aka.ms/teams-toolkit-5.0-upgrade#state__fx_resource_frontend_hosting__endpoint-missing-error-in-some-projects) +2. If your project is created with Visual Studio version < 17.4, you might get an error like `InvalidParameter: Following parameter is missing or invalid for aadApp/create action: name` when running commands. [Try these steps](#how-to-roll-back-after-the-upgrade) to roll back the changes, install VS 17.4, and run the upgrade again. +3. If your tab app is created with Teams Toolkit 3.2.0 or an earlier version, you may get an error like `simpleAuthEndpoint in configuration is invalid` when remote debugging your app. [Try these steps](https://aka.ms/teams-toolkit-5.0-upgrade#simpleauthendpoint-in-configuration-is-invalid) to learn how to mitigate this error. +4. If your project was successfully provisioned before, but after upgrading it cannot be provisioned or published using the `teamsApp/validateAppPackage` action, try using the [validation report in Teams Developer Portal](https://dev.teams.microsoft.com/validation) to check the manifest for errors. [More Info](https://aka.ms/teams-toolkit-5.0-upgrade#teamsappvalidateapppackage-failed-error) -## How to roll back +## How to roll back after the upgrade -If you want to restore your project configuration after the upgrade is successful and continue to use old version Teams Toolkit, you can follow these steps: -1. Copy everything in `.backup` folder to your project root folder -2. Delete the new files mentioned in [Changes to your project](#changes-to-your-project) section +Follow these steps if you want to restore your project configuration after the upgrade is successful or need to use a previous version of Teams Toolkit: +1. Copy everything in the `.backup` folder that was generated during the upgrade to your project root folder. +2. Delete the new files created during the upgrade. The [Changes to your project](#changes-to-your-project) section contains info on everything that was created. -You can learn more details in this [wiki](https://aka.ms/teams-toolkit-5.0-upgrade#how-to-roll-back). \ No newline at end of file +You can [view these steps on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#how-to-roll-back). From 213ffb9aa13f3010b257e326d2c21ae9f15cccb2 Mon Sep 17 00:00:00 2001 From: Chaoyi Yuan Date: Mon, 15 May 2023 14:25:17 +0800 Subject: [PATCH 2/2] docs: resolve comments --- packages/fx-core/templates/core/v3Migration/upgradeReport.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/fx-core/templates/core/v3Migration/upgradeReport.md b/packages/fx-core/templates/core/v3Migration/upgradeReport.md index 468dbeaf98..174a60ab38 100644 --- a/packages/fx-core/templates/core/v3Migration/upgradeReport.md +++ b/packages/fx-core/templates/core/v3Migration/upgradeReport.md @@ -13,7 +13,6 @@ Some of the changes you may immediately notice are: * Configuration of the lifecycle management using Provision, Deploy, and Publish are now fully customizable and expressed in `teamsapp.local.yml` and `teamsapp.yml`. [More info](https://aka.ms/teamsfx-v5.0-guide#project-files) * Configuration and values that were saved in `.fx/config` and `.fx/state` are now handled with environment files and saved to `/env` by default. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) * The changes to use environment files give greater flexibility of configuring which resources are used to provision, but may require some manual steps when creating new environments. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#environment-management) -* Teams Toolkit no longer prompts you for which environment to use when using the Launch targets in `launch.json`. You can edit `.vscode/launch.json` and configure which environments are used. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#launch-your-app) If you're using APIM: * You need to provide values to `APIM__PUBLISHEREMAIL` and the `APIM__PUBLISHERNAME` environment variables. [More info](https://aka.ms/teams-toolkit-5.0-upgrade#provision-apim-service) @@ -22,7 +21,7 @@ You can [view these changes on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade# ## Changes to your project file structure -1. Created `teamsapp.yml` and `teamsapp.local.yml` in your projects root directory. +1. Created `teamsapp.yml` and `teamsapp.local.yml` in your project's root directory. 2. Moved environment files in `.fx` to `.env.{env}` in `env` folder. 3. If your project contains file `.fx/states/{env}.userdata`, the content will be moved to `.env.{env}.user` in `env` folder 4. Moved `templates/appPackage` to `appPackage`, renamed `manifest.template.json` to `manifest.json` and placeholders in it will be updated using the latest default conventions.