Merge pull request #622 from LandonTClipp/migration

Add packages migration docs

Author: LandonTClipp

docs/features.md

@@ -95,7 +95,10 @@ func (_m *Handler) HandleMessage(m pubsub.Message) error {
 :octicons-tag-24: v2.21.0 · :material-test-tube: Alpha Feature
 
 !!! danger
-	This feature is considered alpha. It is likely that bugs exist, and subfeatures may be added/subtracted/modified at any time. Use at your own risk. This warning will be updated as this feature matures.
+    This feature is considered alpha. It is likely that bugs exist, and subfeatures may be added/subtracted/modified at any time. Use at your own risk. This warning will be updated as this feature matures.
+
+!!! info
+    See the [Migration Docs](/mockery/migrating_to_packages/) on how to migrate to this new feature.
 
 Mockery has a configuration parameter called `packages`. This config represents a huge paradigm shift that is highly recommended for the large amount of flexibility it grants you.
 

docs/migrating_to_packages.md

@@ -0,0 +1,43 @@
+---
+title: Migrating To Packages
+---
+
+The [packages](/mockery/features/#packages-configuration) feature is a new configuration scheme that aims to simplify and improve a lot of legacy behavior. This will be the only way to generate mocks in v3. These docs outline general principals for migrating to the new scheme.
+
+Background
+----------
+
+mockery was built during the pre-module era of Golang. Much of its codebase and configuration syntax was designed around file-based operations. This model became highly inefficient once Golang migrated to module-based packages. The old configuration semantics also proved limiting -- many users introduced and requested feature additions to mockery to support esoteric use-cases. This proved to be a huge maintenance burden that existed solely because the configuration model could not flexibly describe all the situations users wanted. The `packages` semantics provides us a few highly desirable traits:
+
+1. Orders of magnitude performance increase, due to calling `packages.Load` once or twice for an entire project, versus once per file in the legacy semantics.
+2. Hierarchical configuration model that allows interface-specific config to be inherited from package-level config, which is inherited from defaults.
+3. Single configuration file that describes the entirety of mockery's behavior, instead of spread out by `//go: generate` statements.
+4. Extensive and flexible usage of a Golang string templating environment that allows users to dynamically specify parameter values.
+
+Configuration Changes
+----------------------
+
+The existence of the `#!yaml packages:` map in your configuration acts as a feature flag that enables the feature.
+
+The configuration parameters used in `packages` have either changed meanings, been removed, or been renamed. It is recommended to wipe out all previous configuration and command-line parameters previously used.
+
+The [configuration docs](/mockery/configuration/#packages-config) show the parameters that are available for use in the `packages` scheme. You should only use the parameters shown in this section. Mockery will not prevent you from using the legacy parameter set, but doing so will result in undefined behavior.
+
+All of the parameters in the config section can be specified at the top level of the config file, which serves as the default values. The `packages` config section defines package-specific config. See some exampes [here](/mockery/features/#examples).
+
+`//go: generate` directives
+----------------------------
+
+Previously, the recommended way of generating mocks was to call `mockery` once per interface using `//go: generate`. Generating interface-specific mocks this way is no longer supported. You may still use `//go: generate` to call mockery, however it will generate all interfaces defined in your config file. There currently exists no semantics to specify the generation of specific interfaces from the command line (not because we reject the idea, but because it was not seen as a requirement for the initial iteration of `packages`).
+
+Behavior Changes
+-----------------
+
+The legacy behavior iterated over every `.go` file in your project, called [`packages.Load`](https://pkg.go.dev/golang.org/x/tools/go/packages#Load) to parse the syntax tree, and generated mocks for every interface found in the file. The new behavior instead simply grabs the list of packages to load from the config file, or in the case of `#!yaml recursive: True`, walks the filesystem tree to discover the packages that exist (without actually parsing the files). Using this list, it calls `packages.Load` once with the list of packages that were discovered.
+
+Filesystem Tree Layouts
+------------------------
+
+The legacy config provided the `keeptree` parameter which, if `#!yaml keeptree: True`, would place the mocks in the same package as your interfaces. Otherwise, it would place it in a separate directory.
+
+These two layouts are supported in the `packages` scheme. See the relevant docs [here](/mockery/features/#layouts).

mkdocs.yml

@@ -10,7 +10,6 @@ theme:
   name: material
   icon:
     logo: fontawesome/brands/golang
-    favicon: fontawesome/brands/golang
   palette:
     # Palette toggle for light mode
     - media: "(prefers-color-scheme: light)"
@@ -66,6 +65,7 @@ nav:
   - Notes: 
     - FAQ: notes.md
     - Changelog: changelog.md
+    - Migrating to Packages: migrating_to_packages.md
 
 extra_css:
   - stylesheets/extra.css