Required Documentation for Episerver App Marketplace
Dec 03, 2019 • 3 Minute Read • Francisco Quintanilla , Architecte associé
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? This includes: release notes, installation and configuration guide, user/ admin manual, and 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: verified by your QA team based on the test cases created, tested in a clean test environment, performance tested, security tested, tested in cloud environments, and tested to see that 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.