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: update upgrade report #8710

Merged
merged 3 commits into from
May 15, 2023
Merged

docs: update upgrade report #8710

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7143b22
docs: port John's changes
blackchoey May 15, 2023
213ffb9
docs: resolve comments
blackchoey May 15, 2023
0c8110d
Merge branch 'main' into chyuan/update-upgrade-report
blackchoey May 15, 2023
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
56 changes: 27 additions & 29 deletions packages/fx-core/templates/core/v3Migration/upgradeReport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,48 @@
# 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 [email protected] 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)

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 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 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).
You can [view these steps on GitHub](https://aka.ms/teams-toolkit-5.0-upgrade#how-to-roll-back).