Wiki migration and link updates (#7480)

Piinks · web-flow · commit 30cdc8ac2061 · 2024-06-17T12:08:31.000-05:00
diff --git a/README.md b/README.md
@@ -65,4 +65,4 @@ Please note the following known issues:
 If you like getting new features as soon as they've been added to the code then you
 might want to try out the dev channel. It is updated weekly with the latest contents
 from the "master" branch. It has minimal testing. Set up instructions are in the wiki's
-[dev channel page](https://github.com/flutter/flutter-intellij/wiki/Dev-Channel).
+[dev channel page](./docs/Dev-Channel.md).
diff --git a/docs/Demo-Tips.md b/docs/Demo-Tips.md
@@ -0,0 +1,5 @@
+## Demo Tips and Tricks
+
+_(A place for demo-giving tips and tricks.)_
+
+Consider using Nikolay Chashnikov's excellent [Presentation Assistant](https://plugins.jetbrains.com/idea/plugin/7345-presentation-assistant).
diff --git a/docs/Dev-Channel.md b/docs/Dev-Channel.md
@@ -0,0 +1,21 @@
+We have an early-access version of the plugin, called the dev channel. This version will be updated weekly, containing all changes made in the previous week. To use it you need to configure IntelliJ or Android Studio to look for plugins on the dev channel repository.
+
+NOTE: If you already have the Flutter plugin installed, please uninstall it before proceeding. Once you have the plugin installed from one channel it will not be available on other channels.
+
+Open the Plugins preference page (macOS) or settings page (Windows, Linux). Click the gear at the top-right and select _Manage Plugin Repositories_.
+
+
+![Screen shot of repositories page](https://lh4.googleusercontent.com/zo9vANXp01YXJC_tQGuiLJxgbdtRFWV-VXViIx_MnqCphGi8PhhQbNTa7H-8ogl0AxIpU7enEQpAs3FZ8lSd0eUw4FpSkxXRkDoQj9uCpvs93D4pTdIrjyK0--q9xBPXTQ0MN7PB)
+
+
+A list editor will pop up that allows you to edit custom plugin repositories. Add this to the list:
+[https://plugins.jetbrains.com/plugins/dev/list](https://plugins.jetbrains.com/plugins/dev/list)
+
+
+![Screen shot of repositories](https://lh3.googleusercontent.com/W4o9xr8IAx0ROAc5NLeTFMbV8b_0ONukXiQdbU9nPbsY3l1eYsqPhyRMU5GkCA93JgqEensjFHSP_AFY0UAGLtZF2epZmH-GoDNlK0okegrF-jsdpy0GuPPEt4CnqzwalWJVril3)
+
+
+Then click OK. The version of the Flutter plugin you see in the Marketplace list will be the dev channel version.
+
+
+![Screen shot of plugins](https://lh6.googleusercontent.com/q8L3R4Rqyjb9gbrKui1SK7YvVLejBXg4TLE0Nif28nxRj69pxrgQY4cwFGiCHuBEegar5MvUgCWY2ETn2lABzG2HjZznPNAtprQRGoUenFrbxpsPNRM-gnxMCAkOpGcI3bGJtRwz)
diff --git a/docs/Development.md b/docs/Development.md
@@ -0,0 +1,12 @@
+## Development Notes
+
+### Simulating a fresh install
+
+To simulate a fresh install, you need to delete any accrued application state.  To do this, you'll want to delete select folders in your plugin sandbox (location found in the `Sandbox Home` field in `Project structure | SDKs | [your IntelliJ IDEA plugin SDK]`.
+
+* **config** folder contains IDE app-level configuration, including app-level libraries, SDKs, recent projects, etc.
+* **system** folder contains indexes and caches, deleting it is similar to File | Invalidate Caches action.
+* **plugins** folder contains plugins that you additionally manually installed to the started IDE.  (Likely don't want to delete `Dart`.)
+* **test** folder will also appear as soon as you run some tests. (Deleting it when tests fail with no visible reason can sometimes help.)
+
+(_**NOTE:**_ after removing configuration info, you may need to re-prepare the `flutter-intellij` plugin for deployment in order for it to show up in your fresh runtime workbench: `Build > Prepare Plugin Module 'flutter-intellij' For Deployment`.)
diff --git a/docs/Diagnosing-Problems.md b/docs/Diagnosing-Problems.md
@@ -0,0 +1,32 @@
+This is a general page to help diagnose issues.
+
+## SDK settings page
+
+You can validate that you have a Flutter SDK configured for your project by going to `Settings > Languages & Frameworks > Flutter` and confirm that there is a setting for the `Flutter SDK path` field.
+
+## Flutter doctor
+
+Flutter doctor is a great tool to validate settings. You can run it from the command-line via `flutter doctor`, and from IntelliJ via `Tools > Flutter > Flutter Doctor`. Please validate that the results for each look reasonable, don't report issues, and agree with each other in terms of the installed toolchains and paths.
+
+## Running apps
+
+If you see issues when running apps - apps not coming up or buttons not becoming enabled - you can run in verbose mode. Open the Flutter preferences (`Settings > Languages & Frameworks > Flutter`), and select `'Enable verbose logging'`. The next time you run an app, it will log verbose information to the run console; this may help in diagnosing where the problem is.
+
+## Analysis issues
+
+The Dart specific smarts for the flutter-intellij plugin are powered by Dart's analysis server. It's a server process that provides errors and warnings as you type, code completion, refactorings, and other IDE-level features. This series of steps can help provide us with the information necessary to debug issues with the analysis server:
+
+- in IntelliJ, open the registry (`cmd-shift-A` and search for `'Registry'`)
+- search for the key `dart.additional.server.arguments`
+- change the value to `--instrumentation-log-file=/path/to/log/file` (and point it to a path for your machine)
+- close the dialog (a restart may be necessary)
+
+The next time IntelliJ runs, the analysis server will log diagnostic information to the given path.
+
+## Restarting
+
+If all else fails, try:
+
+- restarting IntelliJ
+- restarting the iOS simulator
+- checking Android devices for a 'authorize debugging' dialog
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -0,0 +1,11 @@
+## Frequently Asked Questions
+
+### How do I configure a Flutter SDK?
+
+The Flutter plugin for IntelliJ depends on a Flutter SDK to be configured in the Flutter Plugin (**Preferences>Languages & Frameworks>Flutter**). This should point to the Flutter install location.
+
+### How do I build the plugin?
+
+For details about developing with IntelliJ, see our
+[contributing](../CONTRIBUTING.md)
+instructions.
diff --git a/docs/Gradle-daemon-error.md b/docs/Gradle-daemon-error.md
@@ -0,0 +1,14 @@
+If you work with Gradle projects you might see an error like this:
+```
+The newly created daemon process has a different context than expected.
+Java home is different.
+```
+I don't know what causes this, but it appears to be internal to Gradle. IntelliJ is trying to sync the project and  this error occurs when Gradle tries to start its daemon. The cached and given locations for the Java JDK are different. The cached one can't be used in IntelliJ so there appears to be no way to fix it.
+
+I found a work around. It is painful. Remove all JDKs, unset JAVA_HOME (if set), and restart the computer. Start IntelliJ and see a different error for the Gradle-based project. Shut down IntelliJ, install a JDK, set JAVA_HOME (if used), and restart the computer. You will have to reconfigure the SDKs in IntelliJ (use the Project Structure editor). If the Gradle project does not re-sync automatically, just restart IntelliJ. You should at least get past the Gradle daemon creation problem doing this.
+
+There are two ways you might see this problem. If you use the `intellij-community` sources you are using at least one Gradle-based module. The other is if you are working with the plugin integration tests. That is also a Gradle-based module.
+
+UPDATE
+
+This problem occurred again. This time I fixed it by defining JAVA_HOME, without deleting anything or restarting the computer. I set JAVA_HOME to the "Contents" directory of the JDK that is distributed with Android Studio. Then I started IntelliJ and reset the Project Structure JDKs to use that distro. After that, a build started automatically and the Gradle daemon was created properly. Still no idea what the underlying problem is, though.
diff --git a/docs/HotUI-Getting-Started-instructions.md b/docs/HotUI-Getting-Started-instructions.md
@@ -0,0 +1,18 @@
+# Build your widgets inline with Hot UI
+
+HotUI allows you to see and interact with your widgets directly in your IDE as you’re building them. This feature is very early so not all functionality is yet available in the version of Flutter you are using.
+
+We call this feature “Hot UI” and, like Hot Reload, as you make the changes in your code, it updates the hosted UI directly. You can also interact with the hosted UI (like changing a color, as shown here) and that change goes directly into your code. To enable the Hot UI preview, enable this experiment in the Flutter plugin. Property editing is available on the stable Flutter channel and the device screen mirror will be available on master soon.
+
+## Enabling
+This feature is currently experimental. To enable, go to Preferences > Languages & Frameworks > Flutter
+Then check "Enable Hot UI" under "Experiments".
+
+## Outline view integration.
+At the bottom of the Flutter outline view Hot UI provides a list of properties for the current Widget that can be edited inline. When a property edit is made, a hot reload will automatically be triggered so you can see the results of the change on the device.
+
+## Code editor integration.
+Your location in the code editor syncs with the outline view and the highlighted widget on the device to make it easier to see how your code relates to the running application. 
+
+## Screen mirror (coming soon)
+If your version of Flutter is new enough, you will see a screen mirror next to the editable list of properties. You can click on the screen mirror to select the widget in the editor and outline view.
diff --git a/docs/Mac-Menu-Bar-Problem.md b/docs/Mac-Menu-Bar-Problem.md
@@ -0,0 +1,5 @@
+There appears to be a bug in the standard JDK that can prevent the Mac menu bar from functioning. This only affects a debuggable version of IntelliJ or Android Studio launched from IntelliJ. Commands invoked from the menu bar do nothing, although the same command invoked via a key binding works as expected.
+
+There are two work-arounds. The simplest is to edit the run config used to launch the product under test. In the **VM options**, change `-Dapple.laf.useScreenMenuBar=true` to `-Dapple.laf.useScreenMenuBar=false`. That puts the menu bar in the window, rather than at the top of the screen.
+
+The other solution is to use a different JDK. Jetbrains has one that can be used. Clone it from [https://github.com/JetBrains/jdk8u](https://github.com/JetBrains/jdk8u). Or you can use the JRE distributed with IntelliJ IDEA Ultimate. It is in the application installation folder: `<intellij>/Contents/JDK/Contents/Home/jre`. You'll need to copy `tools.jar` from `.../Home/lib` into `.../Home/jre/lib`. You also need to edit the run config to disable the JRE check. In **VM options** change _-Didea.jre.check=true_ to _-Didea.jre.check=false_. To make the run config use the alternate JDK edit it and change **JRE** to point to the new location. It will be something like _/Applications/IntelliJ IDEA.app/Contents/jdk/Contents/Home/jre_ or where ever you downloaded the github repo.
diff --git a/docs/Milestones.md b/docs/Milestones.md
@@ -0,0 +1,8 @@
+# Milestones and Planning
+
+- we're using monthly [milestones](https://github.com/flutter/flutter-intellij/milestones)
+- at the beginning of a milestone, we triage issues from the [Backlog](https://github.com/flutter/flutter-intellij/milestone/10) and [On Deck](https://github.com/flutter/flutter-intellij/milestone/11) milestones into the new milestone
+- any work done or issues fixed should be assigned to the current milestone
+- at the end of the milestone, we run through the [testing plan](https://github.com/flutter/flutter-intellij/blob/master/docs/testing.md) and validate the candidate release
+- before releasing, we update the [changelog](https://github.com/flutter/flutter-intellij/blob/master/resources/META-INF/plugin.xml#L22) (based on the work tracking in the milestone)
+- we then [ship](../docs/Releasing.md), and iterate
diff --git a/docs/Profiling-IntelliJ-Perf-Issues.md b/docs/Profiling-IntelliJ-Perf-Issues.md
@@ -0,0 +1,12 @@
+For information about how to profile IntelliJ for performance issues, see https://intellij-support.jetbrains.com/hc/en-us/articles/207241235-Reporting-performance-problems#capture_slow_startup_2019_2.
+
+In summary:
+- install the 'Performance Testing' plugin
+- restart IntelliJ
+- get set up to repro the issue
+- from the `Help > Diagnostics` menu, select `Start CPU Usage Profiling`
+- repro the issue
+- from the `Help > Diagnostics` menu, select `Stop CPU Usage Profiling`
+- this will save a zip file with a performance snapshot
+
+You can them attach that zip file to bug reports, or open it yourself in JetBrains' `YourKit Java Profiler` tool.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,7 @@
+Welcome to the `flutter-intellij` docs!
+
+This wiki is intended largely for development and process documentation.  
+
+For general plugin usage instructions see the [readme](../README.md). If you want to contribute please see the [contributor docs](../CONTRIBUTING.md).
+
+Thanks!
diff --git a/docs/Release-testing.md b/docs/Release-testing.md
@@ -0,0 +1,2 @@
+The following use cases should be tested on all new releases:
+https://github.com/flutter/flutter-intellij/blob/master/testing.md
diff --git a/docs/Releasing.md b/docs/Releasing.md
@@ -0,0 +1,48 @@
+# Creating a new release 
+
+## From IntelliJ:
+- ensure that the changelog in `CHANGELOG.md` is up-to-date (from the current milestone)
+  - edit `CHANGELOG.md` to update the release notes
+  - re-generate the plugin.xml files using `bin/plugin generate`
+  - commit these changes
+- create a new branch locally from that commit (`git checkout -B release_<version> SHA`, replacing `<version>` and `SHA` as appropriate)
+- in a terminal emulator, `bin/plugin --release=<version> build`, again replacing `<version>` with the current version number
+- the plugin is created as three separate `flutter-studio.zip` products in `/project/root/releases/release_<version>` (all three will be uploaded separately)
+  - 2017.3
+  - 2018.1
+- push your release branch upstream (`git push -u upstream release_21`)
+
+## From plugins.jetbrains.com:
+- sign into https://plugins.jetbrains.com
+- from https://plugins.jetbrains.com/plugin/9212?pr=idea, select `'update plugin'`
+- upload the `flutter-studio.zip` files (one for each product) created from the earlier step (note: the `.zip` file)
+
+# Pushing a patch to an existing release
+
+When it's necessary to patch a previously released build:
+
+## Change to the release branch
+
+- the fix should have already been committed to master
+- `git pull` to get the latest branch information
+- change to the branch for that release (`git checkout release_21`)
+
+## Cherry-pick the fix
+
+- cherrypick the specific commit (`git cherry-pick 2d8ac6a`)
+- ensure that the changelog in `resources/META-INF/plugin.xml` is up-to-date (from the current milestone)
+  - edit `CHANGELOG.md` to update the release notes
+  - again, to re-generate the plugin.xml files use `bin/plugin generate`
+- commit these changes
+- push your release branch upstream (`git push -u upstream release_21`)
+
+## Re-deploy the new Jar
+
+- in a terminal emulator, `bin/plugin --release=<version> build`, again replacing `<version>` with the current version number
+- the plugin is created as three separate `flutter-studio.zip` products in `/project/root/releases/release_<version>` (all three will be uploaded separately)
+  - 2017.3
+  - 2018.1
+  - 2018.2
+- sign into https://plugins.jetbrains.com
+- from https://plugins.jetbrains.com/plugin/9212?pr=idea, select `'update plugin'`
+- upload the `flutter-studio.zip` created from the earlier step (note: the `.zip` file)
diff --git a/docs/Triaging.md b/docs/Triaging.md
@@ -0,0 +1,39 @@
+## Inbox Tracking
+ 
+The [Inbox Query](https://github.com/flutter/flutter-intellij/issues?utf8=✓&q=is%3Aissue+is%3Aopen+no%3Amilestone) contains all the
+
+* open issues that
+* have no milestone assignment.
+ 
+The inbox tracker should do the following initial triage:
+
+* Is the issue invalid? Close it, with a brief explanation.
+* Is the issue a general question, like _"How can I make a blinking button?"_ Close it and redirect to [Stack Overflow](https://stackoverflow.com/tags/flutter) or [gitter](https://gitter.im/flutter/flutter); fodder for a redirecting response can be harvested from this [message](https://gist.github.com/pq/9c8293516b055b369e34e7410c52d2d8).
+* Is the issue better filed against Flutter or the Dart SDK?  Move it using the GitHub [Issue Mover](https://github-issue-mover.appspot.com/).
+* Is the issue an obvious duplicate?  Close it with a pointer to the duplicated issue.
+* Is this issue a bug?  Add the `bug` label.
+* Is this issue a feature?  Add the `enhancement` label.
+* Is the issue a `P0` or a `P1`? Assign the relevant label.
+  * For P0s, let the team know and find an immediate owner. Fixes for P0s get patched into the current stable release.
+  * For P1s, assign an owner and ping them. We'll plan to get fixes for P1s into the next stable release.
+* Milestone assignment:
+  * For very high priority issues, assign to the current or upcoming milestones; these are ones you know people plan to work on imminently
+  * For things that have a high likelihood of being triaged them into the next milestone during planning, assign to the 'On Deck' milestone
+  * For things we're not willing to close, assign to the 'Backlog' milestone
+* Assign any relevant `topic-` labels, and
+* Edit the issue's title to best represent our new understanding of the issue; this will save time for every other person who needs to skim the issue titles in the future
+
+## PR Bots
+- if an issue with the `waiting for customer response` label is not responded to in 14 days, it's automatically closed with an appropriate message
+- to move an issue to another repo, add the comment: `/move to flutter`
+
+## flutter/flutter issues
+
+For issues that clearly belong in the flutter/flutter repo, please do very initial triaging (for example, report 'flutter doctor -v' output with your bug), remove any of our github labels, and move the issue to the flutter/flutter repo by adding the comment to the issue: `/move to flutter`.
+
+We don't have a process for monitoring or triaging IDE issue in the flutter/flutter repo, but likely should. Some candidate github searches:
+
+- https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22dev%3A+ide+-+jetbrains%22
+- https://github.com/flutter/flutter/labels/dev%3A%20ide%20-%20vscode
+
+To move flutter/flutter issues to the flutter-intellij repo, add a comment to the issue: `/move to ide`.
diff --git a/docs/testing.md b/docs/testing.md
@@ -171,7 +171,7 @@ Verify that projects without Flutter project metadata open properly and are give
 Verify installation and configuration in a fresh IDEA installation.
 
 * Follow the instructions to
-  [simulate a fresh installation](https://github.com/flutter/flutter-intellij/wiki/Development#simulating-a-fresh-install).
+  [simulate a fresh installation](Development.md#simulating-a-fresh-install).
 * (If not running in a "runtime workbench", [install the plugins](https://flutter.dev/docs/development/packages-and-plugins/using-packages).)
 * Open "Languages & Frameworks>Flutter" in Preferences and verify that there is
   no Flutter SDK set.
diff --git a/flutter-idea/src/io/flutter/run/README.md b/flutter-idea/src/io/flutter/run/README.md
@@ -3,7 +3,7 @@
 ## `io.flutter.run`
 
 * `LaunchState` - launches a Flutter app in "machine" mode so that it
-  [sends and receives JSON messages](https://github.com/flutter/flutter/wiki/The-flutter-daemon-mode).
+  sends and receives JSON messages.
 
 * `LaunchState.Runner` - abstract class for a way of running a Flutter app (either using a Flutter SDK or Bazel).
 
diff --git a/flutter-idea/src/io/flutter/run/daemon/DaemonApi.java b/flutter-idea/src/io/flutter/run/daemon/DaemonApi.java
@@ -34,10 +34,6 @@
  * Sends JSON commands to a flutter daemon process, assigning a new id to each one.
  *
  * <p>Also handles dispatching incoming responses and events.
- *
- * <p>The protocol is specified in
- * <a href="https://github.com/flutter/flutter/wiki/The-flutter-daemon-mode"
- * >The Flutter Daemon Mode</a>.
  */
 public class DaemonApi {
   public static final String FLUTTER_ERROR_PREFIX = "error from";
diff --git a/flutter-idea/src/io/flutter/run/daemon/DaemonEvent.java b/flutter-idea/src/io/flutter/run/daemon/DaemonEvent.java
@@ -16,10 +16,6 @@
 
 /**
  * <p>A message received from a Flutter process that's not in response to a particular request.
- *
- * <p>The protocol is specified in
- * <a href="https://github.com/flutter/flutter/wiki/The-flutter-daemon-mode"
- * >The Flutter Daemon Mode</a>.
  */
 abstract class DaemonEvent {
   /**

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+The following use cases should be tested on all new releases:`
	`2`	`+https://github.com/flutter/flutter-intellij/blob/master/testing.md`