Merge pull request #160 from FirelyTeam/vonk/update-plugins

Vonk/update plugins

.gitignore

@@ -7,4 +7,6 @@ _build/
 /.vs/firely-docs/config/applicationhost.config
 /.vs/VSWorkspaceState.json
 venv
-*.code-workspace
+#output from previewer in VSCode
+/output
+*.code-workspace

firelyserver/releasenotes/releasenotes_old.rst

@@ -44,7 +44,7 @@ Database
 Features
 ^^^^^^^^
 
-#. Upgrade to HL7.Fhir.Net API 1.3, see its `releasenotes <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_.
+#. Upgrade to HL7.Fhir.Net API 1.3, see the `Older SDK release notes`_.
 #. Vonk calls ``UseIISIntegration`` for better integration with IIS (if present).
 
 Fix
@@ -114,7 +114,7 @@ Feature
 Plugin and Facade API
 ^^^^^^^^^^^^^^^^^^^^^
 
-#. We upgraded the embedded Fhir.Net API to version 1.2, see its `release notes <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_.
+#. We upgraded the embedded Fhir.Net API to version 1.2, see the `Older SDK release notes`_.
 #. Together with the upgrade to .NET Core 2.2, several libraries were updated as well. Most notably Microsoft.EntityFrameworkCore.*, to 2.2.3.
 
 .. _vonk_releasenotes_200-beta2:
@@ -168,7 +168,7 @@ Fix
 Feature
 ^^^^^^^
 
-#. Upgraded Fhir.NET API to version 1.1.2, see its `release notes <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_.
+#. Upgraded Fhir.NET API to version 1.1.2, see the `Older SDK release notes`_.
 #. The Vonk Administration API now allows for StructureMap and GraphDefinition resources to be loaded.
 #. The opening page of Vonk (and the only UI part of it) is updated. It no longer contains links that you can only execute with Postman, and it has a button that shows you the CapabilityStatement.
 #. We published our custom operations on `Simplifier <https://simplifier.net/vonk-resources>`_! And integrated those links into the CapabilityStatement.
@@ -250,7 +250,7 @@ Feature
 #. This feature may also be used for :ref:`accesscontrol_custom_authentication`.
 #. A :ref:`vonk_plugins_template` is added to the documentation.
 #. A documentation page on performance is added: :ref:`vonk_performance`.
-#. Upgrade of the Hl7.Fhir.API library to 1.1. See the `API releasenotes <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_.
+#. Upgrade of the Hl7.Fhir.API library to 1.1. See the `Older SDK release notes`_.
 
 Fix
 ^^^
@@ -346,7 +346,7 @@ Features and fixes
    If this is relevant for you, you may want to reindex for this searchparameter. See :ref:`feature_customsp_reindex_specific`, just for 'Encounter.length'.
 #. Fix: Error "Unable to index for element of type 'base64Binary'". This type of element is now correctly indexed. 
    One known searchparameter that encounters this type is Device.udi-carrier. If this is relevant to you, you may want to reindex for this searchparameter. See :ref:`feature_customsp_reindex_specific`, just for 'Device.udi-carrier'.
-#. Fix: Validation would fail on references between contained resources. See also fix #423 in the `release notes for the FHIR API <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_.
+#. Fix: Validation would fail on references between contained resources. See also fix #423 in the `Older SDK release notes`_.
 #. Fix: E-tag was missing from the response on a delete interaction.
 #. Fix: An invalid mimetype in the _format parameter (like _format=application/foobar) returned response code 400 instead of 415.
 #. Fix: If a subscription errors upon execution, not only set the status to error, but also state the reason in Subscription.error for the user to inspect.
@@ -437,7 +437,7 @@ Features and fixes
 #. Feature: Through :ref:`Vonk FHIR Pluginss<vonk_plugins>` you can replace the landing page with one in your own style. We provided an :ref:`example<vonk_plugins_landingpage>` on how to do that.
 #. Feature: You can now start Vonk from within another directory than the Vonk binaries directory, e.g. ``c:\programs>dotnet .\vonk\vonk.server.dll``.
 #. Feature: You can configure the maximum number of entries allowed in a Batch or Transaction, to avoid overloading Vonk. See :ref:`batch_options`.
-#. Upgrade: We upgraded the FHIR .NET API to version 0.96.0, see their `release notes<https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_ for details.
+#. Upgrade: We upgraded the FHIR .NET API to version 0.96.0, see the `Older SDK release notes`_ for details.
    Mainly #599 affects Vonk, since it provides the next...
 #. Fix: Under very high load the FhirPath engine would have concurrency errors. The FhirPath engine is used to extract the search parameters from the resources. This has been fixed.
 #. Fix: Search on a frequently used tag took far too long on a SQL Server repository.
@@ -488,7 +488,7 @@ Features and fixes
    This required a few small changes to the MongoDB implementation (the share the drivers), so please reindex your MongoDB database: :ref:`reindex/all <feature_customsp_reindex>`.
 #. Feature: Configuration to restrict support for ResourceTypes, SearchParameters and CompartmentDefinitions, see :ref:`supportedmodel`.
 #. Feature: Errata.zip: collection of corrected search parameters (e.g. that had a faulty expression in the FHIR Core specification), see :ref:`feature_errata`
-#. Upgrade: FHIR .NET API 0.95.0 (see `releasenotes <https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html>`_)
+#. Upgrade: FHIR .NET API 0.95.0 (see the `Older SDK release notes`_)
 #. Fix: a search on _id:missing=true was not processed correctly.
 #. Fix: better distinction of reasons to reject updates (error codes 400 vs. 422, see `RESTful API specification <http://hl7.org/fhir/http.html#2.21.0.10.1>`_
 #. Fix: recognize _format=text/xml and return xml (instead of the default json)
@@ -861,3 +861,5 @@ Release 0.3.0.0
 
   #. Added indexes to MongoDb and SQL Server implementations.
 
+
+.. _Older SDK release notes: https://docs.fire.ly/projects/Firely-NET-SDK/releasenotes.html

firelyserver/releasenotes/upgrade.rst

@@ -93,12 +93,19 @@ Upgrading Plugins
 Since a Plugin runs in the context of a Firely Server we advise you to start by upgrading your Firely Server, without loading your Plugin.
 Check the section on :ref:`settings_pipeline` to see how you can exclude your plugin from the pipeline.
 
+.. attention::
+
+   We do not guarantee that a plugin built against version x.y.z of Firely Server can be run within a newer or older version as-is.
+   Between minor versions recompilation is usually enough to update your plugin. Between major versions you should prepare for breaking changes in the public programming API.
+   Sometimes we choose to apply such changes even on a minor version update, if we are fairly sure that you will not or only slightly be affected by it.
+
 Upgrade the references in your plugin:
 
 #. Open the source code of your plugin, and open the project file (``yourplugin.csproj``).
 #. Change the references to the Firely Server.* packages to the version that you want to upgrade to.
 #. Build and check the errors.
 #. Check the list of breaking changes for the new Firely Server version in the :ref:`vonk_releasenotes`. Applying the changes should fix the errors.
+#. With some releases Firely Server is also upgraded to a newer version of the Firely .NET SDK. That is then mentioned in the release notes. If this is the case, also check the `SDK release notes`_ for breaking changes.
 #. Still errors? Maybe we have overlooked a change. Please report it to us, see :ref:`vonk-contact`. And if it is easy to fix - do so :-)
 #. Build and publish your plugin. 
 #. Put the resulting dll's in the plugin directory of the new installation of Firely Server.
@@ -115,3 +122,4 @@ So start with upgrading the references right away.
 
 Especially for Facades to relational databases: match the version of EntityFrameworkCore that the new version of Firely Server is using. Check the list of changes to see whether we upgraded.
 
+.. _SDK release notes: https://github.com/FirelyTeam/firely-net-sdk/releases