diff --git a/content/maintainers-guide/processes/release/prestashop/_index.md b/content/maintainers-guide/processes/release/prestashop/_index.md index 679a6076..36e5ede7 100644 --- a/content/maintainers-guide/processes/release/prestashop/_index.md +++ b/content/maintainers-guide/processes/release/prestashop/_index.md @@ -5,11 +5,11 @@ aliases: - /maintainers-guide/releasing-prestashop/ --- -# How to release a new PrestaShop version +## How to release a new PrestaShop version This section describes the release process, step by step. A PrestaShop version release requires all these steps to be completed. -## Prerequisites +### Prerequisites To perform a build, you will need the following: @@ -22,7 +22,7 @@ To perform a build, you will need the following: Some of steps will require special tools or access rights which are currently not accessible for maintainers outside the PrestaShop Company. A notice indicates when this is the case. {{% /notice %}} -## Different types of releases +### Different types of releases We currently have 4 kind of new releases for PrestaShop: @@ -33,12 +33,16 @@ We currently have 4 kind of new releases for PrestaShop: Security patch releases contain security fixes for major security issues. Please read [about them][security-releases]. -## Process overview +### Process overview 1. **[Perform preliminary tasks][preliminary-tasks]**: (click to see the full step) Short summary: + - **Communicate and update GitHub milestone** + + - **Freeze development step and create build branch** + - **Update the version number in the Core.** - **Make sure the default translation catalogue has been updated and pushed to Crowdin.** @@ -64,7 +68,7 @@ Security patch releases contain security fixes for major security issues. Please - **Update the Changelog and Contributors list.** _These files must be included in the build._ - - **Push your work into a build branch.** + - **Push your work into the build branch.** _Allows the base branch to continue receiving merges while your build is being validated._ - **Build and store the zip archive.** @@ -82,7 +86,7 @@ Security patch releases contain security fixes for major security issues. Please - **Merge the updated Changelog and Contributors list on GitHub.** - **Tag the version using Git. Do not push it just yet.** - + - **Communicate and push/publish the tag and the release on GitHub.** _Make sure to link to the PrestaShop SA versions page from the GitHub release description to ease access to the latest built package of PrestaShop_ @@ -110,7 +114,6 @@ Security patch releases contain security fixes for major security issues. Please [get-composer]: [nodejs]: [nodejs-requirements]: {{< devdocs "development/compile-assets.md#requirements" >}} - [preliminary-tasks]: {{< relref "preliminary-tasks.md" >}} [create-build]: {{< relref "create-build.md" >}} [release-publicly]: {{< relref "release-publicly.md" >}} diff --git a/content/maintainers-guide/processes/release/prestashop/create-build.md b/content/maintainers-guide/processes/release/prestashop/create-build.md index 0cb5368d..da14ee16 100644 --- a/content/maintainers-guide/processes/release/prestashop/create-build.md +++ b/content/maintainers-guide/processes/release/prestashop/create-build.md @@ -5,33 +5,11 @@ aliases: - /maintainers-guide/releasing-prestashop/create-build/ --- -# Create a build package +## Create a build package Once preliminary tasks have been completed, the project is ready to be built. -## 1. Communicate - -Starting this step means that the Development phase of this release is over. - -Before you go further, make sure to **tick the "Development" box** in the Release Tracker GitHub issue (there is one per version, see the [1.7.6.6 example][release-tracker-issue]). - -## 2. Create a local branch for your build - -The following tasks will require you to perform changes and submit them as a Pull Request. - -* **Clone the project** on your computer using Git (only if you don't already have a local copy of the repository). - - ```shell - git clone git@github.com:PrestaShop/PrestaShop.git - ``` - -* **Make sure that you switch to the appropriate branch** regarding the version you'll be building (e.g. you must be on branch 1.7.7.x if you're building a 1.7.7 release). - -* **Make sure your branch is up-to-date with upstream.** Especially if you already had a local clone of the repository. - -* **Create a local branch for your work.** Keep it! You will need to go back to it later. - -## 3. Merge any not-yet merged security fixes into your branch +### 1. Merge any not yet merged security fixes into your branch To avoid disclosing security issues before the version is released, security Pull Request are merged in GitHub _after_ the build has been validated. In order to include them in your build, you need to retrieve them manually and merge them in your local branch. @@ -44,9 +22,9 @@ If this release includes security PRs: If there are security PRs to be merged, they are fixing minor security issues. Otherwise, a security release would have been done instead. {{% /notice %}} -## 4. Update the Changelog & Contributors list +### 2. Update the Changelog & Contributors list -### Extract list of changes and contributors using the changelog tool +#### Extract list of changes and contributors using the changelog tool {{% notice warning %}} **This step requires special rights.** @@ -59,38 +37,41 @@ After this step, you should obtain two files: - the Changelog file – including a list of all the merged Pull Requests. Make sure to keep this file, you'll need it later. - the New Contributors file – a list of all the people who contributed code for this version for their first time. -### Update the project's files +#### Update the project's files - Add the contents of the changelog at the top of PrestaShop's [Changelog file][changelog-file]. - Update PrestaShop's [Contributors file][contributors-file] by adding the new contributors. Keep the alphabetical order. - Commit your changed files with following message: "// Changelog [version]" -## 5. Push your work into a build branch +### 3. Push your work into the build branch + +{{% notice %}} +**As reminder** + +Your branch must follow this scheme: `[version]-build` (for example: "9.0.2-build") +{{% /notice %}} The build branch helps other people verify your work, and allows the base branch to continue receiving merges while your build is being validated. If your build is rejected because of a bug, the fixes will have to be merged into your build branch, instead of the base branch. -### If the branch does not contain security fixes +#### If the branch does not contain security fixes -- Push your changes to a new branch in the public repository. - Name your branch following this scheme: `[version]-build` (for example: "1.7.8.1-build") -- Create a new pull request to merge your changes. If you're lost, see [this example](https://github.com/PrestaShop/PrestaShop/pull/20032) from the 1.7.6.6 release. +- Push your changes to the new build branch in the public repository. +- Create a new pull request to merge your changes. If you're lost, see [this example](https://github.com/PrestaShop/PrestaShop/pull/40227) from the 9.0.2 release. {{% notice warning %}} -**Make sure your PR is not merged accidentally!** +**Make sure your PR is not merged accidentally!** The build must be validated before the PR can be merged. {{% /notice %}} - -### If the branch contains security fixes - +#### If the branch contains security fixes - Push your local branch into a private repository, in order to avoid disclosing the security bugs. - Share access to your private repository with other maintainers so that they can verify your work. -## 6. Build the ZIP archive +### 4. Build the ZIP archive (OS version) Use the [Release Creator CLI script][release-creator-readme] included with PrestaShop's sources to create the ZIP archive. @@ -119,9 +100,9 @@ By default, the release package will create two files in a new subdirectory in ` As an optional step, consider downloading the latest stable release package and compare the contents of the zip archives to look for suspicious changes. -## 7. Archive your build +### 5. Archive your OS version -### Rename files +#### Rename files Rename both files according to our naming convention: @@ -130,6 +111,7 @@ prestashop_-[beta.|rc.]+build..}} diff --git a/content/maintainers-guide/processes/release/prestashop/create-version-branch.md b/content/maintainers-guide/processes/release/prestashop/create-version-branch.md index f22bf7fa..184ecbe6 100644 --- a/content/maintainers-guide/processes/release/prestashop/create-version-branch.md +++ b/content/maintainers-guide/processes/release/prestashop/create-version-branch.md @@ -5,14 +5,13 @@ aliases: - /maintainers-guide/releasing-prestashop/create-version-branch/ --- -# Create a new branch for a new major/minor version. +## Create a new branch for a new major/minor version. - -### 1) Create the new branch and push it to the main repo +### 1. Create the new branch and push it to the main repo Create the branch on you local git and push it to the main repository. You will need to push it to the main repository and not to your fork. -### 2) Open PRs based on the new branch and modify those files: +### 2. Open PRs based on the new branch and modify those files: To create the new branch, we need to update several repositories to complete the necessary work. @@ -39,7 +38,6 @@ Below is a list of repositories with modified files for creating the `9.0.x` bra - src/App/Command/SlackNotifierCommand.php - `PrestaShop/prestashop.github.io`: ( no PR needed this time ) - data/tags.yml (make sure the tag doesn't exists already) @@ -61,4 +59,3 @@ The QA Automation Team should update the following repositories: - .github/workflows/test-sanity.yml - .github/workflows/test-with-prebuilt-shop.yml - .github/workflows/pr_test_single_campaign.yml - diff --git a/content/maintainers-guide/processes/release/prestashop/final-steps.md b/content/maintainers-guide/processes/release/prestashop/final-steps.md index cadd70cf..60eed435 100644 --- a/content/maintainers-guide/processes/release/prestashop/final-steps.md +++ b/content/maintainers-guide/processes/release/prestashop/final-steps.md @@ -5,9 +5,11 @@ aliases: - /maintainers-guide/releasing-prestashop/final-steps/ --- -# Final steps +## Final steps -## 1. Update API stream for Update Assistant +### 1. Update API stream for Update Assistant + +#### 1.1 Distribution API {{% notice note %}} **This should only be done for stable releases.** @@ -18,7 +20,8 @@ _(i.e. if not for betas and RCs)._ Additional changes must be brought to the [Distribution API repository](https://github.com/PrestaShop/distribution-api) to provide the best experience on the Update Assistant module: - Add in the file [releaseNotes.json](https://github.com/PrestaShop/distribution-api/blob/main/resources/json/releaseNotes.json) the new version and the link to its release notes, -- Update the file [autoupgrade.json](https://github.com/PrestaShop/distribution-api/blob/main/public/json/autoupgrade.json) to make the new release available for update. + +- Verify that the file [autoupgrade.json](https://github.com/PrestaShop/distribution-api/blob/main/public/json/autoupgrade.json) has been updated by the team in charge of autoupgrade to make the new release available for update. If you needed to release a new version of the module Update Assistant, update the `autoupgrade_recommended` property as well. You may have to create a new entry if the new Update Assistant is compliant with a range of PrestaShop version that is unrelated to the existing ones. @@ -30,13 +33,30 @@ Once this step is done and your changes have been merged, update the Release Tra _Please verify the contents of https://api.prestashop-project.org/autoupgrade. You might need to wait for the cache to be cleared._ {{% /notice %}} +#### 1.2 Legacy API + {{% notice note %}} -**API migration.** +**API migration in progress** + +_Update Assistant is using the Distribution API since the version 7.1. But some steps still need to be performed on the old API (only available from people of PrestaShop SA with specific rights)._ +{{% /notice %}} + +See the internal notion page [Update API stream for 1-click upgrade][stash-api] and follow the different steps. + +### 2. Deployment of the Classic edition + +{{% notice warning %}} +**This notion documentation requires special rights.** -_Update Assistant is using the Distribution API since the version 7.1. Before that, it was using an API only available from people of PrestaShop SA with specific rights._ +Go to [Create a Classic Edition](https://www.notion.so/prestashopcorp/Create-a-Classic-Edition-2c45d6cf071f80789babe11c1b379899) page for more information about +the internal tool **smb_edition_builder** and follow the different steps in the "Deployment" section. {{% /notice %}} -## 2. Create Docker images for the new version +### 3. Create Docker images for the new version + +{{% notice note %}} +**This part is normally no longer necessary and is now automated.** +{{% /notice %}} * Checkout the [project][docker-repository], install the project and create a new branch * Modify the file `versions.py` to add the new version and the related php matrix compatibility @@ -52,37 +72,37 @@ It may take a few hours for the images to be updated. You can update the Release Tracker GitHub issue: step "Docker image" is done. -## 3. Go through the checklist +### 3. Go through the checklist * Check the PrestaShop localization packs are correct (only needed for major and minor releases): - - [Repository](https://github.com/PrestaShop/TranslationFiles/tree/master/1.7/translations/) - - [Example download link](https://i18n.prestashop-project.org/translations/8.1.0/es-ES/es-ES.zip) (replace 8.1.1 with the version you just released) - + - [Repository](https://github.com/PrestaShop/TranslationFiles/tree/master/1.7/translations/) + - [Example download link](https://i18n.prestashop-project.org/translations/8.1.0/es-ES/es-ES.zip) (replace 8.1.1 with the version you just released) + * Check the Distribution API content for fresh installs is correct: - - - https://api.prestashop-project.org/prestashop features the latest release and its details are correct, - - https://api.prestashop-project.org/assets/prestashop/8.1.1/prestashop.xml lists the archive contents with the checksum of each file in it (replace 8.1.1 with the version you just released), - - https://api.prestashop-project.org/modules/8.1.1 features the right modules, and informations are correct (replace 8.1.1 with the version you just released), - - https://api.prestashop-project.org/autoupgrade shows the release among one or several compatibility range of Update Assistant (provided you allow updates to this version). + + - https://api.prestashop-project.org/prestashop features the latest release and its details are correct, + - https://api.prestashop-project.org/assets/prestashop/8.1.1/prestashop.xml lists the archive contents with the checksum of each file in it (replace 8.1.1 with the version you just released), + - https://api.prestashop-project.org/modules/8.1.1 features the right modules, and informations are correct (replace 8.1.1 with the version you just released), + - https://api.prestashop-project.org/autoupgrade shows the release among one or several compatibility range of Update Assistant (provided you allow updates to this version). + * Check that the release note has been published on the [Build Blog](https://build.prestashop-project.org) * Check that the latest release has an available docker image on the [Docker repository][docker-repository] * For 1.7.x releases, check the Addons API content for fresh installs is correct (replace 1.7.6.0 with the version you just released): - - - [Native modules](http://api-addons.prestashop.com?format=json&iso_lang=en&iso_code=FR&version=1.7.6.0&method=listing&action=native) - - [Pushed modules](http://api-addons.prestashop.com?format=json&iso_lang=en&iso_code=FR&version=1.7.6.0&method=listing&action=install-modules) + + - [Native modules](http://api-addons.prestashop.com?format=json&iso_lang=en&iso_code=FR&version=1.7.6.0&method=listing&action=native) + - [Pushed modules](http://api-addons.prestashop.com?format=json&iso_lang=en&iso_code=FR&version=1.7.6.0&method=listing&action=install-modules) * Check that if you try to install PrestaShop 1.7.5 from the archive, the installer suggests you install the latest version instead -## 4. Store the ZIP archive +### 4. Store the ZIP archive Submit a Pull Request to add the ZIP archive to the [Archives repository](https://github.com/PrestaShop/zip-archives). -## 5. Improve the process +### 5. Improve the process If during the process you encountered issues or there was some information not 100% clear, please improve this process documentation. - {{% notice tip %}} **Congratulations!** @@ -90,6 +110,6 @@ The release is now complete, you can close the Release Tracker GitHub issue. {{% /notice %}} [docker-repository]: https://github.com/PrestaShop/docker -[docker-hub-prestashop]: https://hub.docker.com/r/prestashop/prestashop/ +[stash-api]: https://www.notion.so/prestashopcorp/Update-API-stream-for-1-click-upgrade-d547202bbc814407860c134ae01b3b32 [docker-release-pr-example]: https://github.com/PrestaShop/docker/pull/287 [docker-generate-doc]: https://github.com/PrestaShop/docker/blob/master/HOW-TO-USE.md diff --git a/content/maintainers-guide/processes/release/prestashop/preliminary-tasks.md b/content/maintainers-guide/processes/release/prestashop/preliminary-tasks.md index b47a6f30..23db5691 100644 --- a/content/maintainers-guide/processes/release/prestashop/preliminary-tasks.md +++ b/content/maintainers-guide/processes/release/prestashop/preliminary-tasks.md @@ -5,11 +5,44 @@ aliases: - /maintainers-guide/releasing-prestashop/preliminary-tasks/ --- -# Preliminary tasks +## Preliminary tasks Before you can start your build, you must make sure that the project is ready to be built. -## 1. Make sure the version number has been updated in the Core +### 1. Communicate + +Starting this step means that the Development phase of this release is over (freeze step): + +Verify that the release milestone on github is 100% complete. If there are still PRs remaining, create the milestone for an another release and tag the remaining PRs to it. + +Inform the @prestashop/committers about the release tracking issue. +If discussions arise regarding critical bugs, inform QA and the PM. They will be responsible for assessing the criticality of the bugs. + +Inform the team in charge of Autoupgrade, and ask them if a version update is necessary (PRs with the tag "Needs Autoupgrade PR"). + +Before you go further, make sure to **tick the "Development" box** in the Release Tracker GitHub issue (there is one per version, see the [1.7.6.6 example][release-tracker-issue]). + +### 2. Create a branch for your build + +The following tasks will require you to perform changes and submit them as a Pull Request. + +example : If the release is `9.0.2`, create a branch from `9.0.x` and name it `9.0.2-build` + +* **Clone the project** on your computer using Git (only if you don't already have a local copy of the repository). + + ```shell + git clone git@github.com:PrestaShop/PrestaShop.git + ``` + +* **Make sure that you switch to the appropriate branch** regarding the version you'll be building + +* **Make sure your branch is up-to-date with upstream.** Especially if you already had a local clone of the repository. + +The next steps and PRs to be performed will be done on the build branch (freeze). + +NB : **For a minor or major version** see additionnal steps on [create version branch][create-version-branch] page. + +### 3. Make sure the version number has been updated in the Core {{% notice note %}} **This only needs to be done once per release.** @@ -47,7 +80,7 @@ If you're lost, check out [this example][bump-core-version-pr-example] from the [bump-core-version-pr-example]: https://github.com/PrestaShop/PrestaShop/pull/19980 {{% /notice %}} -## 2. Make sure the default translation catalogue has been updated and pushed to Crowdin +### 4. Make sure the default translation catalogue has been updated and pushed to Crowdin {{% notice warning %}} **This step requires special rights.** @@ -55,16 +88,10 @@ If you're lost, check out [this example][bump-core-version-pr-example] from the Ask a maintainer from the PrestaShop Company with access to the Translation Tool to perform this step. {{% /notice %}} -{{% notice note %}} -**This step is only needed for minor and major releases.** - -It is usually only done once per release as well. -{{% /notice %}} - 1. [Use the Github Action to extract wordings from the TranslationTool repository](). This command will automatically generates a Pull Request on the PrestaShop/PrestaShop repository (author should be jarvis). It is important to note that this PR must be reviewed by a member of the content team. is PRIVATE, and then you need special access rights to use it. -2. If the team content member requests wording corrections, they can be found either in the PrestaShop CORE, a module, or in the directory /mails of the PrestaShop CORE. +2. Access the Crowdin interface and validate any new translations (they can be found either in the PrestaShop CORE, a module, or in the directory /mails of the PrestaShop CORE). 3. If the correction occurs in a module, a release must be made, along with a bump in the composer.json of the CORE, before re-extracting. @@ -72,7 +99,7 @@ It is usually only done once per release as well. 5. Once all the wordings have been corrected, validated and merged, [a Github Action can be used on the TranslationTool repository](https://github.com/PrestaShopCorp/TranslationTool/actions/workflows/push_catalog_to_crowdin.yml) to push the catalogs to Crowdin (the repository need right access). -## 3. Lock the theme version +### 5. Lock the theme version {{% notice tip %}} You can do this step using Git or directly on GitHub in the next step. @@ -98,7 +125,12 @@ This tag is needed to lock the theme version when a new release is built. * Update `composer.lock` to target the new tag -## 4. Release any necessary improvement on the Update Assistant module +### 6. Release any necessary improvement on the Update Assistant module + +{{% notice notes %}} + +Ask the team in charge of the Autoupgrade module +{{% /notice %}} Some releases need an update of the [Update Assistant][autoupgrade] module, and some do not. For example, if the MySQL database schema has been updated between two versions of PrestaShop, a schema update SQL script is needed, and it has to be added to the [list][autoupgrade-sql-list]. @@ -109,7 +141,7 @@ Please verify whether or not this new version of PrestaShop requires If yes, please follow [the release process of the Update Assistant module][autoupgrade-release-process]. -## 5. Manual verifications +### 7. Manual verifications Make sure that in the current branch: @@ -124,6 +156,13 @@ Make sure that in the current branch: ```bash php bin/console prestashop:linter:security-annotation find-missing php bin/console prestashop:linter:legacy-link + ``` + +* All versions of the composer packages correspond to a release tag and not a development branch tag. + + ```text + "prestashop/ps_apiresources": "dev-dev", // incorrect tag + ``` * There are no known vulnerabilities in composer dependencies using `composer audit` to check vulnerabilities. @@ -151,7 +190,7 @@ This repository is now archived. Use composer audit instead * [Nightly builds][nightly-build-board] are green -## 6. Create the new version in the PrestaShop Marketplace and update native module compatibility +### 8. Create the new version in the PrestaShop Marketplace and update native module compatibility {{% notice warning %}} **This step requires special rights ([doc to create a new version on PrestaShop Marketplace](https://www.notion.so/prestashopcorp/Create-the-new-version-in-the-Addons-Marketplace-update-module-compatibility-c665ab0777204e2d95ce6df22b140747)).** @@ -171,7 +210,8 @@ If any of above verifications fails, it MUST be addressed in a Pull Requests and The preliminary steps are completed, you can now proceed to the [build steps][create-build]. -[security-checker]: https://github.com/fabpot/local-php-security-checker +[create-version-branch]: {{< relref "create-version-branch.md" >}} +[release-tracker-issue]: https://github.com/PrestaShop/PrestaShop/issues/19959 [register-new-hook]: {{< devdocs "development/components/hook/register-new-hook/" >}} [fos-js-routing]: [how-to-build-assets]: {{< devdocs "development/compile-assets/" >}}