Guidelines for writing

Keep in mind that upgrade instructions are written for users that do not understand our system well, so more clear they are, more useful they are.


  • Our users work in a clone of project-base and even when they do the upgrade, their project-base is not upgraded. Every time you change/add anything in project-base, write upgrade instruction how to repeat this work
    • for anything with docker, phing, frontend, config, ...
  • Make instructions as easy to follow as possible
    • Good example: postgres upgrade
    • Copyable commands are great
    • Bad example: "Apply changes done in PR...", however link to particular diff is all right
  • If you mention a file, make a link for it
    • This is especially important for files in project-base, as users don't have new changes in their project-base
  • Link files in an accurate version, because the project evolves in time
  • Write instructions
    • Good example: "Do this, then that"
    • Bad example: "This was done, this was changed"

The main file where a project developer should start looking for instructions is file in the monorepo root.

This file contains information for the contributors in the form of the link to upgrade/ file.

Instructions for developers building a project based on project-base should follow. First, there must be general information about upgrading with recommended steps and a typical upgrade sequence, following with a list of links to upgrade guides for each version. These versions should be placed in a upgrade/ folder.

Structure of upgrade files

Each upgrade file must have link to main file with general information about upgrade and may contain one or more of following main sections:

  • shopsys/framework
  • shopsys/coding-standards
  • shopsys/form-types-bundle
  • shopsys/http-smoke-testing
  • shopsys/migrations
  • shopsys/monorepo-tools
  • shopsys/plugin-interface
  • shopsys/product-feed-google
  • shopsys/product-feed-heureka
  • shopsys/product-feed-heureka-delivery
  • shopsys/product-feed-zbozi

Each section must contain instructions relevant only to the package they cover and the sections have to be ordered as they are in a list above.

Each step should have a link to the related pull request and may contain an additional link or links to make instruction more clear.

Section shopsys/framework

Because this section is expected to be the longest, it should contain a finer division into one or more of the following sub-sections:

  • Infrastructure
    • related with Docker, Kubernetes, Environment settings, ...
    • instruction to rebuild images must occur only once
  • Composer dependencies
    • related to composer.json
  • Configuration
    • related with parameters, YML configuration files, ...
  • Tools
    • Phing, PHPStan, PHPUnit, ...
  • Database migrations
    • Which database changes were introduced in a current version
  • Security
    • Important security upgrades
  • Application
    • Changes in a code that may require some changes in a particular implementation.