Episerver marketplace required documentation

As part of the process to deliver our plugins to the new Episerver app marketplace we had to create several documents for each plugin. In this post we are going to talk about these documents, how we tackled each of them and some general recommendations.

The first document you should read is the Verification Guidelines provided by Episerver, in short it explains what kind of documentation is expected and general guidelines about the code quality and quality assurance for each app. In brief terms the document tries to tell us the following:

• You must follow best development practices including but not limited to code reviews, static code analysis, unit testing with complete test coverage and TDD. It is important the plugin is tested using the latest version of the Episerver CMS/Commerce
• Generate test plans which will be delivered to Episerver QA team
• Fill out other documents provided by Episerver
• To test the plugin, Episerver will set up a call with your QA or development team to show the capabilities of the plugin, this will generate more test-cases which will form part of a verification plan which will try to avoid issues with other Episerver products
• Additional checks must be considered when the plugin is installed and uninstalled. The installation should keep the components of the plugin (dlls, files) in the folders and places that Episerver recommends /modules/_protected, and when removed they should be removed properly
• If the plugin has visual components, it must be checked against the same browsers that Episerver supports for incompatibility issues
• If your plugin keeps private information in a server, you must describe the data flow and what have you done to keep the information secure. The main objective is to comply with the GDPR specification
• All plugins should be tested against Episerver security guidelines which include cross site request forgery, ineffective session termination, header disclosures, clickjacking attacks, SQL injections and more.

The second document you should pay attention is the Marketplace App Verification Checklist also provided by Episerver. This document includes a checklist of all the documents you must create, which Episerver products are compatible with your plugin, how is distributed, where are the files of the plugin located, and more. These are the main things you should fill in these documents:

• Is your plugin a NuGet package or distributed in another way?
• Which versions of Episerver products support; it should only support the latest ones of each product. For CMS it is 11
• Location of your plugin files inside the protected folder
• Does it use Episerver logging?
• Is the plugin displayed in the editor/admin interface or as part of another system?
• Does the plugin save data in the same database as Episerver, a separate database, config file or in another place?
• Have you completed the documentation for your plugin?
  • Release notes
  • Installation and configuration guide
  • User/ Admin manual
  • Scenario/Description for the main workflows and/or functionalities
• Have you tested your installation procedure? This includes:
  • Testing in a sandbox created for Episerver
  • Modules required for the plugin must be included and ready for test
  • Guidelines if there are configuration files
  • Key/License if applies
• Finally, you must test your plugin in all these scenarios
  • Should be verified by your QA team based on the test cases created
  • It has been tested in a clean test environment
  • It has been performance tested
  • It has been security tested
  • It has been tested in cloud environments
  • It supports running in a CDN-environment

If all the points mentioned above are checked, it means you are ready to send the documentation to Episerver in order to continue with the QA process.

The other four documents you must create must be specific for each application, we are going to being with the Release notes document, this document is quite simple. It specifies in which version is your plugin, what versions of the CMS or any other Episerver product supports, and which are the bug fixes and the new- features implemented in the current version. It is also important to include if the current version has some breaking changes.

The Installation and configuration guide document include which are the pre requirements for your plugin, what is the process to install it which frequently will explain how to install the plugin using the NuGet package manager and finally, it specifies what must be configured in order to make the plugin work as intended by the client

The Scenario/Description for the main workflows and/or functionalities document explains in brief terms what are the main features of your plugin. It should include screenshot for better understating but should not go in detail about each functionality, how to access it or how to make it work. That detail should go in the next document

User/ Admin manual document must explain how to use the plugin from the editor / administrator point of view. It should explain in detail each functionality of your plugin, how to access it and use it. Screenshots of your application are highly recommended in this document too. While creating this document you can start writing test cases which should be explained in another document.

The latest document Episerver requires is the document with your QA Test cases, it is not officially mentioned as part of the documentation, but it is required when you contact them to review your plugin. This document explains several workflows in order to detect possible errors in your plugin. It should also include screenshots and be described in enough detail that can be used by another person which was not involved in the project, such a QA engineer from Episerver

Those are all the documents you need and are required by Episerver to deploy your plugin in the Episerver marketplace. We would highly recommend that you create the documents in the same order as we presented here. It will help you to reduce headaches while creating this documentation which is quite extensive and time consuming but necessary to offer a well-documented and quality assured plugin.