New Plugin Publishing Section

docs/plugin-development/getting-started.md

@@ -2,10 +2,10 @@
 
 Plugins allow you to interact with the game and add features, modify
 functionality, and do much more. We ask you to be respectful of
-[our guidelines](restrictions#what-am-i-allowed-to-do-in-my-plugin) to ensure
+[our guidelines](../plugin-publishing/restrictions.md) to ensure
 that your plugin is approved into the official plugin repository, and to
 minimise the risk of action by Square Enix. You can read more about this
-[here](restrictions#why-do-you-discourage-certain-types-of-plugins).
+[here](../plugin-publishing/approval-process.md).
 
 We recommend that you start by cloning one of the following templates, and then
 customising it to your requirements. While `SamplePlugin` is the most actively

docs/plugin-development/technical-considerations.md

@@ -0,0 +1,22 @@
+# Plugin Technical Considerations
+
+There are many potential technical decisions that you should consider when
+developing a plugin. Here are a few examples:
+
+- For regular windows, like settings and utility windows, you should use the
+  [Dalamud Windowing API](https://dalamud.dev/api/Dalamud.Interface.Windowing/).
+  It enhances windows with a few nice features, like integration into the native
+  UI closing-order, pinning, and opacity controls. If it looks like a window, it
+  should use the windowing API.
+- If interacting with game data, we strongly recommend using
+  [Lumina](https://github.com/NotAdam/Lumina) over XIVAPI. Lumina uses your
+  local game files, which will always be up-to-date and accurate, and is much
+  faster than making requests to XIVAPI.
+
+## Are there any performance constraints to be aware of?
+
+You should generally aim to not impact game performance too much as that can
+degrade the experience for the player and cause other issues. A good place to
+start debugging performance issues is through the Plugin Statistics window,
+which can be found through Plugins > Open Plugin Stats in the dev menu
+(`/xldev`).

docs/plugin-publishing/_category_.yml

@@ -0,0 +1,5 @@
+label: Publishing your Plugin
+position: 40
+link:
+  type: doc
+  id: index

docs/plugin-development/plugin-submission.md → docs/plugin-publishing/approval-process.md

@@ -1,4 +1,4 @@
-# Plugin Submission & Approval
+# The Approval Process
 
 This article describes the process that decides which plugins are merged into
 the official repository, and how we make sure that what goes in is safe for you
@@ -45,14 +45,14 @@
 ## New submissions
 
 When a plugin is newly submitted, the team checks that it conforms to a set of
-[guidelines](restrictions#what-am-i-allowed-to-do-in-my-plugin) and
+[guidelines](./restrictions.md) and
 [technical criteria](https://github.com/goatcorp/DalamudPluginsD17#approval-criteria).
 The team then votes on each newly submitted plugin - if a plugin clears 4 yes
 votes, it is approved and will appear in the repo. Every team member can veto a
 plugin, blocking it from being merged until the concern is resolved. This hasn't
 happened yet.
 
-These [guidelines](restrictions#what-am-i-allowed-to-do-in-my-plugin) exist
+These [guidelines](./restrictions.md) exist
 because we want to improve the experience Square Enix provides - not harm it or
 any other player playing the game. We think that they allow for a lot of freedom
 for plugin developers, while encouraging them to stay true to that intent.
@@ -92,6 +92,6 @@
 clarified, feel free to reach out.
 
 [^1]:
-    Technically, this is still possible, but you would need NSA-grade
-    datacenters and a lot of time (at the moment, probably hundreds of years) to
-    break the hash algorithm Git uses.
+Technically, this is still possible, but you would need NSA-grade
+datacenters and a lot of time (at the moment, probably hundreds of years) to
+break the hash algorithm Git uses.

docs/plugin-publishing/custom-repositories.md

@@ -0,0 +1,71 @@
+# Publishing to a Custom Repository
+
+:::warning
+The Dalamud Project offers minimal support to custom repository plugins, including assistance in setting up a custom
+repository.
+
+Developers wishing to publish their plugins should strongly consider submitting their plugin to the official 
+("mainline") repository.
+:::
+
+At times, developers may want to control the release cycle of their plugin more strictly than what the mainline
+repository can allow. Dalamud allows end users to add custom repository paths to their installation to facilitate this
+specific process.
+
+## The Repository URL
+
+A plugin repository, briefly, is a URL pointing to a specifically-formatted JSON file containing an array of store
+entries. This URL must be accessible by an HTTP `GET` request, and may support query parameters. It does not support
+authentication or authorization.
+
+At its simplest, a plugin repository file is structured as follows:
+
+```json5
+[
+  {
+    "Author": "A Plugin Developer",
+    "Name": "A Custom Plugin",
+    "Description": "A long description about what this plugin is or does, to show upon expanding its installer entry.",
+    "InternalName": "ACustomPlugin",
+    "AssemblyVersion": "1.0.0.0",
+    "TestingAssemblyVersion": null,
+    "RepoUrl": "https://github.com/APluginDeveloper/ACustomPlugin",
+    "ApplicableVersion": "any",
+    "DalamudApiLevel": 10,
+    "Punchline": "A short blurb about what this plugin is.",
+    "IsHide": false,
+    "IsTestingExclusive": false,
+    "DownloadLinkInstall": "https://example.com/path/to/release/output.zip",
+    "DownloadLinkTesting": "https://example.com/path/to/testing/output.zip",
+    "DownloadLinkUpdate": "https://example.com/path/to/release/output.zip",
+    "LastUpdate": "1701231234" 
+  }
+]
+```
+
+Multiple plugins may be returned by a single plugin repository URL.
+
+## Store Entry Keys
+
+Broadly speaking, all keys supported by the plugin manifest are also supported by the Store Entry. Store Entries also
+support some additional keys:
+
+* `IsHide` - allows hiding a plugin from clients without removing it from the manifest.
+* `DownloadCount` - a count of number of times this plugin has been downloaded.
+* `DownloadLinkInstall` - a URL to the artifact zip file for this plugin.
+* `DownloadLinkUpdate` - a URL to use specifically when updating this plugin, e.g. for download count tracking.
+* `ImageUrls` - an array of URLs to use as marketing/preview images for this plugin.
+* `IconUrl` - a URL to use as the icon for this plugin in the installer.
+
+### Testing Keys
+
+Dalamud supports the ability to mark certain plugins as "testing only", or to publish testing builds of plugins to
+prospective beta testers who opt in. This can be done using the below testing-exclusive keys. These keys are not
+required unless a testing build is desired.
+
+* `IsTestingExclusive` - marks a plugin as only available for people who have opted in to see testing plugins.
+* `TestingAssemblyVersion` - the version of the plugin currently available for test.
+    * Will only be used if it is greater than the release assembly version.
+* `TestingChangelog` - a special changelog to display for the current test version.
+* `TestingDalamudApiLevel` - the target API level for the testing release of this plugin.
+* `DownloadLinkTesting` - a URL to the artifact ZIP file for the testing release of this plugin.

docs/plugin-publishing/index.md

@@ -0,0 +1,2 @@
+# Publishing Your Plugin
+

docs/plugin-development/restrictions.md → docs/plugin-publishing/restrictions.md

@@ -1,54 +1,45 @@
-# Restrictions
+# Plugin Restrictions
 
-## What am I allowed to do in my plugin?
-
-Dalamud plugin development, by its nature, interferes with the game's
-functioning and changes the experience as intended by Square Enix. This makes it
-very important to ensure that your plugin does not do anything that a human
-player could not do; Dalamud plugins should enhance the experience, not
-radically alter it.
+Dalamud plugin development, by its nature, interferes with the game's functioning and changes the experience as 
+intended by Square Enix. This makes it very important to ensure that your plugin does not do anything that a human
+player could not do; Dalamud plugins should enhance the experience, not radically alter it.
 
 Please make sure that, as much as possible:
 
 - your plugin does not interact with the game servers in a way that is:
-  - automatic, as in polling data or making requests without direct interaction
-    from the user
-  - outside of specification, as in allowing the player to do or submit things
-    to the server that would not be possible by normal means
+    - automatic, as in polling data or making requests without direct interaction
+      from the user
+    - outside of specification, as in allowing the player to do or submit things
+      to the server that would not be possible by normal means
 - your plugin does not augment, alter, or interfere with combat, unless it only
   provides information about your own party or alliance members that is
   otherwise available, but represents said information differently.
-  - Note that there are plugins on the repository that do not abide by this
-    rule, but they have been grandfathered and similar plugins will not be
-    allowed.
+    - Note that there are plugins on the repository that do not abide by this
+      rule, but they have been grandfathered and similar plugins will not be
+      allowed.
 - your plugin does not interfere with Square Enix's monetary interests (i.e.
   granting access to Mog Station items)
 - your plugin does not provide parsing, raid logging, DPS meters, or similar
   (i.e. information beyond what is traditionally available to players)
 - your plugin does not have a hard dependency on any plugin that violates the
-  Plugin Guidelines
-
-If you are not sure whether your plugin will be allowed, _please_ contact us
-before you start work on it. We don't want to have to turn you down after you've
-already done the work!
+  Plugin Guidelines.
 
-Plugins that violate these rules will not be accepted into the Dalamud plugin
-repository, and you will not receive support from the Dalamud community.
+Certain plugins may be subject to certain additional constraints or review based on their featureset, potential
+impact to the ecosystem, and other factors. [Plugin review is a subjective process](./submission.md) and many factors go
+into making a decision for any specific plugin.
 
-## Are there any technical decisions I should consider making?
+## I'm not sure if my plugin idea violates the guidelines!
 
-There are many potential technical decisions that you should consider when
-developing a plugin. Here are a few examples:
+If you are not sure whether your plugin will be allowed, _please_ contact us in the
+[Dalamud Discord](https://discord.gg/holdshift) before you start work on it. Members of the Plugin Approval Committee or
+Dalamud staff will evaluate your idea and let you know if there are any risk factors that may put it in breach of one
+of our guidelines. We *highly* suggest you ask us to weigh in on an idea before starting to work on it - it's not a 
+good feeling for anyone when we need to reject a completed plugin that breaks our rules.
 
-- For regular windows, like settings and utility windows, you should use the
-  [Dalamud Windowing API](https://dalamud.dev/api/Dalamud.Interface.Windowing/).
-  It enhances windows with a few nice features, like integration into the native
-  UI closing-order, pinning, and opacity controls. If it looks like a window, it
-  should use the windowing API.
-- If interacting with game data, we strongly recommend using
-  [Lumina](https://github.com/NotAdam/Lumina) over XIVAPI. Lumina uses your
-  local game files, which will always be up-to-date and accurate, and is much
-  faster than making requests to XIVAPI.
+It's not particularly uncommon for a newly-submitted plugin to unintentionally violate one or more guidelines. When
+this happens, the Plugin Approval Committee will leave detailed commentary explaining the nature of the violation as
+well as possible remediations in your plugin submission. We ultimately *want* your plugin to be on our repository, so
+we are very willing to work with developers to find a solution or workaround that makes everyone happy.
 
 ## Why do you discourage certain types of plugins?
 
@@ -72,21 +63,7 @@ developing a plugin. Here are a few examples:
 > work, but I would like to ask you to consider and empathize with my opinion
 > when creating software that depends on Dalamud.
 
-- [goat](https://github.com/goaaats), the lead developer of XIVLauncher/Dalamud
-
-## Are there any performance constraints to be aware of?
-
-You should generally aim to not impact game performance too much as that can
-degrade the experience for the player and cause other issues. A good place to
-start debugging performance issues is through the Plugin Statistics window,
-which can be found through Plugins > Open Plugin Stats in the dev menu
-(`/xldev`).
-
-## How are plugins reviewed and approved?
-
-[This page documents our plugin submission process](plugin-submission), and the
-stringent review that is applied to each new submission. Feel free to join the
-Discord and ask for more details if required.
+\- [goat](https://github.com/goaaats), the lead developer of XIVLauncher/Dalamud
 
 ## I don't like plugin X, can you block it or delete it?
 
@@ -104,7 +81,7 @@ rules, there is very little we can do as a project to prevent this.
   we are not immune to deception or politics.
 - Most ready-to-use APIs offered by Dalamud itself are read-only and don't allow
   changing the actual state of the game. Plugins run on your PC like any other
-  program and are not "sandboxed", so they have free reign to interact with the
+  program and are not "sandboxed", so they have free rein to interact with the
   game in any way they please with their own code.
 - Limiting what plugins can do is a very difficult technical problem, and might
   lead to a lot of very popular plugins not being able to do what they do

docs/plugin-publishing/submission.md

@@ -0,0 +1,86 @@
+# The Submission Process
+
+Once you're happy with the state your plugin is in, it's time to submit it! This is a relatively involved process
+where a plugin developer will build *yet another* manifest file and submit it to [our GitHub Repository][d17] for
+inclusion in the official ("mainline") plugin repository.
+
+## The D17 Workflow
+
+Dalamud's plugin workflow is managed by a system called [Plogon][plogon], which is a powerful CI/code management
+solution designed specifically for us. Plogon and D17 allows us to attest that the final binary running on an end user's
+computer is generated from an exact commit hash in a publicly-available Git repository. This process ensures that both
+Dalamud and its plugins remain completely open source and auditable by anyone interested.
+
+The D17 workflow allows plugins to be submitted to two separate "tracks":
+
+* `stable`, which is intended for builds of a given plugin intended for the public. These should be relatively
+  bug-free and be properly supported. This track is controlled by the `stable/` directory in D17.
+* `testing`, which is intended for experimental or new versions of a plugin. The `testing` track may sometimes be
+  subdivided into child tracks, though the main testing track is called `live`. This track is controlled by the
+  `testing/live/` directory in D17.
+  * Other testing tracks may sometimes be created, e.g. `testing/net8`. These will be documented in the D17 readme as
+    well as in the news section of this site. 
+
+## Submitting a Plugin
+
+In order to submit a plugin for initial inclusion into the mainline repository, you must open a pull request against
+the [DalamudPluginsD17][d17] repository. This pull request must be formatted in a specific way, and follow certain
+system requirements.
+
+Please ensure you're only modifying *one* plugin per submission and pull request! This helps us work through the process
+more efficiently, and allows plugins to get through review faster. Each submission must also be in its own branch to 
+better protect against merge conflicts.
+
+Every plugin submitted to D17 must follow the below directory structure, located in the appropriate track:
+
+```
+MyPluginName/
+ |- manifest.toml
+ |- images/
+     |- icon.png
+     |- image1.png [OPTIONAL]
+     |- image2.png [OPTIONAL]
+     |- image3.png [OPTIONAL]
+
+```
+
+Note that new plugins *must* be submitted to the `testing` track; that is, their directory must be placed in the
+`testing/live/` directory of the repository.
+
+The `manifest.toml` file is a special type of manifest intended for D17 consumption. A sample is provided below:
+
+```toml
+[plugin]
+repository = "https://github.com/goatcorp/SamplePlugin.git"
+commit = "765d9bb434ac99a27e9a3f2ba0a555b55fe6269d"
+owners = ["goaaats"]
+project_path = "SamplePlugin"
+changelog = "Added Herobrine"
+```
+
+The `icon.png` image must have a 1:1 aspect ratio, and must be between 64x64 and 512x512 in size.
+
+Plugin developers may optionally upload up to five marketing/preview images, named `image1.png` through `image5.png`.
+
+### Submitting Plugin Updates
+
+To update a plugin, submit a new pull request (from a new branch) modifying at least the `commit` field of the plugin's
+`manifest.toml` file. This commit must be publicly accessible at the specified repository, though it does not need to
+be on any specific branch.
+
+You may optionally provide a `changelog` field in the `manifest.toml`, which will be displayed in the plugin installer.
+If this changelog field is omitted, a changelog will be pulled from the JSON manifest or the pull request body, in that
+order.
+
+### Changing Release Tracks
+
+To change a release track, simply copy (or move) the plugin's manifest directory to the new track's directory. Version 
+bumps and commit hash changes are not required to move a plugin between tracks.
+
+When a plugin exists in multiple tracks that can be targeted by any specific Dalamud install, the newest version (as
+determined by the `AssemblyVersion` of the plugin's JSON manifest) will be installed. As such, plugin developers will
+often leave older versions in tracks so that they can re-enable that track quickly.
+
+
+[d17]: https://github.com/goatcorp/DalamudPluginsD17
+[plogon]: https://github.com/goatcorp/Plogon