[wiki migration] Leftover wiki pages and links (#148989)

This is waiting on 
- https://github.com/flutter/flutter/pull/148777
- https://github.com/flutter/flutter/pull/148790

After this PR lands, there will likely be 1-2 more clean up PRs, after which the migration will be done!

---

This moves the remaining wiki pages as planned in [flutter.dev/go/migrate-flutter-wiki-spreadsheet](https://docs.google.com/spreadsheets/d/1x65189ZBdNiLRygpUYoU08pwvXD4M-Z157c6pm8deGI/edit?usp=sharing) 

It also adds the team labels to the label bot for future PRs.

Changes to the content were only updating cross links, or links to refer to the main branch rather than master.
Remaining links to the wiki will be updated once all other pages have finished moving, they still work in the meantime.

Part of https://github.com/flutter/flutter/issues/145009
This commit is contained in:
Kate Lovett
2024-05-28 10:12:10 -05:00
committed by GitHub
parent a1a33e63b9
commit 1fbcbb73a0
94 changed files with 271 additions and 770 deletions

View File

@@ -1,7 +1,7 @@
This is an index of team-facing documentation for the [flutter/packages repository](https://github.com/flutter/packages/).
- [Contributing to Plugins and Packages](contributing/README.md)
- [Flutter migrate](https://github.com/flutter/flutter/wiki/Flutter-migrate)
- [Flutter migrate](../wiki_archive/Flutter-migrate.md)
- [Package migration to 1.0.0](Package-migration-to-1.0.0.md)
- [Plugin Tests](testing/Plugin-Tests.md)
- [Plugins and Packages repository structure](Plugins-and-Packages-repository-structure.md)

View File

@@ -1,4 +1,4 @@
This page covers additional information that is specific to contributing to flutter/packages. If you aren't already familiar with the general guidance on Flutter contribution, start with [Tree hygiene](https://github.com/flutter/flutter/wiki/Tree-hygiene).
This page covers additional information that is specific to contributing to flutter/packages. If you aren't already familiar with the general guidance on Flutter contribution, start with [Tree hygiene](../../contributing/Tree-hygiene.md).
## Version and CHANGELOG updates
@@ -178,12 +178,12 @@ On some platforms, there are multiple native languages that can be used to write
- Currently our policy is to have a limited number of plugins in Kotlin, to ensure that we are finding Kotlin-specific plugin issues in our own development.
- Java if the plugin is already in Java (which is almost all of them).
- Allowing Kotlin more broadly is [under consideration](https://docs.google.com/document/d/1Ok_mUPgmw8_l-ynLueEKtXm2Fs48lEVB0JqZd7M7uyA/edit?usp=sharing), but currently most plugin development is limited to Java to avoid adding another language to the set of languages Flutter team members need to interact with regularly.
- If you are interested in taking on a **long-term ownership role in a plugin**, and would like to migrate it to Kotlin, please reach out in the `hackers-ecosystem` channel [on Discord](https://github.com/flutter/flutter/wiki/Chat).
- If you are interested in taking on a **long-term ownership role in a plugin**, and would like to migrate it to Kotlin, please reach out in the `hackers-ecosystem` channel [on Discord](../../contributing/Chat.md).
- iOS: Depends on the plugin. The goal is to eventually migrate all plugins to Swift; see [the migration section below](#swift-migration-for-1p-plugins) for details. For non-migration PRs, use:
- Swift if the plugin is entirely Swift.
- Swift or Objective-C if the plugin is partially migrated.
- Objective-C if the plugin is still entirely Objective-C.
- Linux: C. Use of C++ constructs is strongly discouraged; see [repo style notes](https://github.com/flutter/packages/blob/main/CONTRIBUTING.md#style) for details
- Linux: C. Use of C++ constructs is strongly discouraged; see [repo style notes](../../../CONTRIBUTING.md#style) for details
- macOS: Swift only\*.
- \* In some cases an existing iOS implementation has been updated to support macOS, so is Objective-C (e.g., `in_app_purchase`). This is the only case where Objective-C is allowed for macOS plugins.
- Windows: C++.

View File

@@ -1 +1 @@
The flutter/plugins repository is no longer in use. See [Setting up the Packages development environment](https://github.com/flutter/flutter/wiki/Setting-up-the-Packages-development-environment) instead.
The flutter/plugins repository is no longer in use. See [Setting up the Packages development environment](Setting-up-the-Packages-development-environment.md) instead.

View File

@@ -9,7 +9,7 @@ This page describes the process of updating flutter/packages after a stable Flut
`dart run script/tool/bin/flutter_plugin_tools.dart update-min-sdk --flutter-min=3.7.0`
* Per [repo policy](https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#version), we do not version-bump these changes, so the associated `update-release-info` command should use `--version=next`. A convenient way to run the `update-release-info` command on only the necessary packages is to make the `update-min-sdk` run its own commit, then use `--base-branch HEAD^ --run-on-changed-packages` to target only the packages changed in that commit.
* Per [repo policy](../contributing/README.md#version), we do not version-bump these changes, so the associated `update-release-info` command should use `--version=next`. A convenient way to run the `update-release-info` command on only the necessary packages is to make the `update-min-sdk` run its own commit, then use `--base-branch HEAD^ --run-on-changed-packages` to target only the packages changed in that commit.
* This must be done in the same PR as the previous step, or CI will fail.
* The [release action](https://github.com/flutter/packages/blob/e7d812cefce083fa09762d25cd42303737d05b9f/.github/workflows/release.yml#L34) should be updated to use the new stable.

View File

@@ -1,4 +1,4 @@
*If you haven't already read it, start with [the repository structure overview](https://github.com/flutter/flutter/wiki/Plugins-and-Packages-repository-structure) to familiarize yourself with the types of packages discussed below.*
*If you haven't already read it, start with [the repository structure overview](../Plugins-and-Packages-repository-structure.md) to familiarize yourself with the types of packages discussed below.*
## Types of Tests
@@ -131,7 +131,7 @@ flutter pub run build_runner build
## Adding tests
A PR changing a plugin [should add tests](https://github.com/flutter/flutter/wiki/Tree-hygiene#tests). Which type(s) of tests you should add will depend on what exactly you are changing. See below for some high-level guidance, but if you're not sure please ask in your PR or in `#hackers-ecosystem` [on Discord](https://github.com/flutter/flutter/wiki/Chat).
A PR changing a plugin [should add tests](../../contributing/Tree-hygiene.md#tests). Which type(s) of tests you should add will depend on what exactly you are changing. See below for some high-level guidance, but if you're not sure please ask in your PR or in `#hackers-ecosystem` [on Discord](../../contributing/Chat.md).
Hopefully the scaffolding to run the necessary kinds of tests are already in place for that plugin, in which case you just add tests to the existing files in the locations referenced above. If not, see below for more information about adding test scaffolding.
### FAQ: Do I need to add tests even if the part of the code I'm changing isn't already tested?
@@ -170,7 +170,7 @@ Some patterns to consider given all of the above:
If a plugin is missing test scaffolding for the type of tests you want to add, you have several options:
- If it's simple to enable them, and you are comfortable making the changes, you can enable them as part of your PR.
- If it's non-trivial to enable them, but you are comfortable doing it, you can make a new PR that enables them with some minimal test, and ask for that to be reviewed and landed before continuing with your PR.
- If you aren't comfortable making the change, reach out [via Discord](https://github.com/flutter/flutter/wiki/Chat) and ask in `#hackers-ecosystem`.
- If you aren't comfortable making the change, reach out [via Discord](../../contributing/Chat.md) and ask in `#hackers-ecosystem`.
Regardless of the approach you use, please reach out on Discord if a PR that sets up a new kind of test doesn't get reviewed within two weeks. Filling in the gaps in test scaffolding is a priority for the team, so we want to review such PRs quickly whenever possible.

View File

@@ -16,7 +16,7 @@ flutter/packages uses the same LUCI infrastructure as most of the rest of Flutte
### LUCI
This is the CI system used by flutter/flutter and flutter/engine. For information about LUCI results pages, see [Understanding a LUCI build failure](https://github.com/flutter/flutter/wiki/Understanding-a-LUCI-build-failure).
This is the CI system used by flutter/flutter and flutter/engine. For information about LUCI results pages, see [Understanding a LUCI build failure](../../infra/Understanding-a-LUCI-build-failure.md).
#### Results
@@ -40,7 +40,7 @@ GitHub Actions tasks are configured in `.github/workflows/`.
The overall testing structure for flutter/packages is:
- Most tests are run on only one host platform: Linux when possible, or the relevant platform if necessary (e.g., Windows target tests must run on Windows hosts, and iOS and macOS tests must run on macOS hosts).
- Most tests are run with both Flutter `master` and Flutter `stable` (see [discussion of supported platforms](https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#supported-flutter-versions) for more details).
- Most tests are run with both Flutter `master` and Flutter `stable` (see [discussion of supported platforms](../contributing/README.md#supported-flutter-versions) for more details).
- Since in practice `stable`-only failures are very rare, CI is currently configured to only run `stable` in post-submit to reduce CI time and costs.
- Architecture coverage is as-needed; we generally don't duplicate tests across architectures. For plugins, where architecture is most likely to be an issue, we try to run:
- the majority of the tests (`*_platform_tests`) on the most popular architecture, and
@@ -56,25 +56,25 @@ Exclusions **must** include explanatory comments, and in cases where they are no
# Specific tests
In addition to Dart unit tests, Dart integration tests, and for plugins the various kinds of [native plugin tests](https://github.com/flutter/flutter/wiki/Plugin-Tests), there are a number of tests that check for repository best practices or to catch problems that have affected packages in the past. As a rule of thumb, any time we find a bug or mistake only *after* publishing a package, we try to add a check for that in CI to prevent similar issues in the future.
In addition to Dart unit tests, Dart integration tests, and for plugins the various kinds of [native plugin tests](Plugin-Tests.md), there are a number of tests that check for repository best practices or to catch problems that have affected packages in the past. As a rule of thumb, any time we find a bug or mistake only *after* publishing a package, we try to add a check for that in CI to prevent similar issues in the future.
Below are descriptions of many of the less self-evident CI tests, and common solution to failures. Anyone adding new tests is encouraged to document them here.
- **`submit-queue`**: This only shows in PRs (presubmit), and reflects the current state of the tree: if it is red, the tree is currently closed to commits (which can mean either that the tree is red, or that a recently landed PR is still running post-submit tests), and if it is green the tree is open. This has **no relation** to the PR itself, and as a PR author you do not need to do anything about it; Flutter team members monitor the state of the tree, and will handle failures.
- There is a known issue that sometimes causes the status of this check to be stale; the causes is unknown. If this happens (i.e., the check in red but the tree state as described in the Infrastructure section above is actually green), you an either update your PR by merging in the latest `main` to force updates, or you can reach out to a Flutter team member (in a comment on the PR, or in Discord) to override the incorrect check.
- **`*_platform_tests`**: This runs each package's integration tests on the given target platform, as well as any [native plugin tests](https://github.com/flutter/flutter/wiki/Plugin-Tests) for that platform. This can also include native-language-specific analysis or lint checks.
- **`*_platform_tests`**: This runs each package's integration tests on the given target platform, as well as any [native plugin tests](Plugin-Tests.md) for that platform. This can also include native-language-specific analysis or lint checks.
- **`analyze`**: The initial `analyze` step is a straightforward Dart `analyze` run, but the `pathified_analyze` step is more complicated; it is intended to find issues that will cause out-of-band breakage in our own repository when the change being tested is published (most commonly with federated plugins). It does this by finding all packages that have non-breaking-version changes in the PR, and then rewriting all references to those packages in the repository to be `path:` dependencies, then re-running analysis.
A failure here does not necessarily mean that the PR is wrong; because we use very strict analysis options, changes that are not considered breaking by Dart semver conventions can break our CI. Common sources of failures here include:
- Accidentally making a breaking change without making a major version change to the plugin.
- **Solution**: Fix the versioning.
- Deprecating something that is still in use by another package within the repository.
- **Solution**: Suppress the warnings with `// ignore: deprecated_member_use` annotations in the other packages using that method, [with a comment](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#comment-all--ignores) linking to the issue that tracks updating it. Once it lands, do a follow-up PR to update the calls and remove the `ignore`s.
- **Solution**: Suppress the warnings with `// ignore: deprecated_member_use` annotations in the other packages using that method, [with a comment](../../contributing/Style-guide-for-Flutter-repo.md#comment-all--ignores) linking to the issue that tracks updating it. Once it lands, do a follow-up PR to update the calls and remove the `ignore`s.
- Adding a new enum value. We generally do not consider this breaking, but use your judgement and discuss with your reviewer; consider whether it is likely that clients have critical logic that depends on exhaustively handling all enum values, and what the effects are likely to be for those use cases if a new value is added.
- **Solution**: If it's not treated as breaking, then temporary disable that analyzer warning while adding the value:
* In the PR that adds the value, suppress the warnings with `// ignore: exhaustive_cases` annotations, [with a comment](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#comment-all--ignores) linking to the issue that tracks updating it.
* In the PR that adds the value, suppress the warnings with `// ignore: exhaustive_cases` annotations, [with a comment](../../contributing/Style-guide-for-Flutter-repo.md#comment-all--ignores) linking to the issue that tracks updating it.
* In the follow-up PR that picks up the new enum value and uses it, remove the `ignore`.
- **`legacy_version_analyze`**: Runs `analyze` with older versions of Flutter than the current `stable` on any package that claims to support them; see [the supported version policy](https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#supported-flutter-versions) for details.
- **`legacy_version_analyze`**: Runs `analyze` with older versions of Flutter than the current `stable` on any package that claims to support them; see [the supported version policy](../contributing/README.md#supported-flutter-versions) for details.
- **Solution**: Unless you have a specific need to keep support for the old version (unlikely), just update the Flutter constraint in `pubspec.yaml` to exclude the failing version(s) of Flutter.
- **`analyze_downgraded`**: Runs `analyze` after running a `pub downgrade`, to ensure that minimum constraints are correct (e.g., that you don't add usage of an API from version `x.1` of a dependency that is specified as `^x.0` in `pubspec.yaml`).
- **Solution**: Update the relevant constraint to the version that introduced the new APIs.
@@ -84,7 +84,7 @@ Below are descriptions of many of the less self-evident CI tests, and common sol
- Otherwise, temporarily add the necessary package(s) to the `exclude_all_packages_app.yaml` exclusion file (see discussion of exclusion files above).
- **`repo_checks`**: Enforces various best practices (formatting, style, common mistakes, etc.). In most cases, the error messages should give clear and actionable explanations of what is wrong and how to fix it. Some general notes on specific steps:
- **`license_script`**: All code files must have the repository copyright/license block at the top. In most cases a failure here just means you forgot to add the license to a new file.
- **`federated_safety_script`**: Changing interdependent sub-packages of a federated plugin in the same PR can mask serious issues, such as undesired breaking changes in platform APIs. See the documentation on [changing federated plugins](https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#changing-federated-plugins) for next steps.
- **`federated_safety_script`**: Changing interdependent sub-packages of a federated plugin in the same PR can mask serious issues, such as undesired breaking changes in platform APIs. See the documentation on [changing federated plugins](../contributing/README.md#changing-federated-plugins) for next steps.
# Out-of-band failures
@@ -111,7 +111,7 @@ LUCI tasks are run on Flutter-infrastructure-managed VMs, using an [out-of-repo
- Usually easy to identify since failures are generally before the tests even run.
#### Investigation & resolution tips
- File an [infrastructure ticket](https://github.com/flutter/flutter/wiki/Infra-Ticket-Queue).
- File an [infrastructure ticket](../../infra/Infra-Ticket-Queue.md).
- Check the recipe file for recent changes.
### Firebase Test Lab (Also known as: "FTL")