Skip to content

CREATE_RELEASE_NOTES.md

Latest commit

 

History

History
196 lines (131 loc) · 6.61 KB

CREATE_RELEASE_NOTES.md

File metadata and controls

196 lines (131 loc) · 6.61 KB

Create release notes for PWA Studio

Here are the steps you need to follow to create PWA Studio release notes. :

PART 1: Code repo tasks (magento/pwa-studio):

  1. Clone the magento/pwa-studio repo.
  2. Create a release-notes branch.
  3. Login to the Adobe network using VPN as necessary.
  4. Run the JitNotes CLI.
  5. Update the magento-compatibility.js file.
  6. Create a PR.
  7. Generate and copy the source-code docs.

PART 2: Docs repo tasks (AdobeDocs/commerce-pwa-studio):

  1. Clone the AdobeDocs/commerce-pwa-studio repo.
  2. Create a release branch from main.
  3. Replace auto-generated docs.
  4. Verify changes.
  5. Create a PR.
  6. Fix markdown linting errors.
  7. Merge PR to main.

PART 3: Deploy docs to production

  1. From the GitHub AdobeDocs/commerce-pwa-studio repo, access the Deployment workflow from the Actions tab.

  2. Run the workflow with a production configuration.

PART 1: Code repo tasks (magento/pwa-studio)

  1. Clone the magento/pwa-studio repo:

    git clone git@github.com:magento/pwa-studio.git

  2. CD into the project and run yarn to install the dependencies:

    cd pwa-studio
yarn

  3. Add a new release-notes branch based off the release/xx.x branch. Example: release-notes/13.1.

  4. Login to the Adobe network or access it using the GlobalProtect VPN.

    NOTE: You must be logged in to the Adobe network to run the JitNotes CLI.

  5. Run the JitNotes CLI from the pwa-studio root:

    npx jitnotes

    This command generates a new CHANGELOG.md in the project's root to replace the existing one.

  6. Add relevant content to the following sections of the CHANGELOG.md:

    • Documentation changes
    • Known issues
    • Updated package dependencies table.

    NOTE: You may also need to add release note entries to the Jira ticket's Release note field if they are shown as missing in the CHANGELOG.

  7. From your magento/pwa-studio project root, update the magento-compatibility.js file.

    This file is used by the docs script to create the markdown-compatibility.md table for the PWA Studio documentation.

    module.exports = {
+  '13.1.0': '2.4.6',
   '13.0.0': '2.4.5',
   '12.7.0': '2.4.5',

  8. Commit and push your changes, then create a PR for approval. Example PR: #4080.

  9. CD into the pwa-studio/pwa-devdocs directory and run the following command:

    yarn build:docs

    This command generates the following markdown files:

    • magento-compatibility.md

    • JSDoc source-code markdown from the following directories:

      root
└── packages
   ├── buildpack
   ├── pagebuilder
   ├── peregrine
   ├── pwa-buildpack
   └── venia-ui

  10. Open the auto-generated directory to verify the generated files:

    pwa-devdocs
└── src
   └── _includes
      └── auto-generated
         ├── pagebuilder
         ├── peregrine
         ├── pwa-buildpack
         ├── venia-ui
         └── magento-compatibility.md

  11. Copy the auto-generated directory, with all its subdirectories and files.

PART 2: Docs repo tasks (AdobeDocs/commerce-pwa-studio)

  1. Clone the AdobeDocs/commerce-pwa-studio repo:

    git clone git@github.com:AdobeDocs/commerce-pwa-studio.git

  2. CD into the project and run yarn to install the dependencies:

    cd commerce-pwa-studio
yarn

  3. Add a new release branch based off the main branch. Example: release-13.1.0.

  4. Replace the existing src/data/auto-generated directory with the auto-generated directory you copied from the magento/pwa-studio output.

    This replacement should result in one or more changes to existing files. Example:

    7_Docs-Repos/commerce-pwa-studio [release-13.1.0●] » git status
On branch release-13.1.0
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
+  modified:   src/data/auto-generated/magento-compatibility.md
+  modified:   src/data/auto-generated/peregrine/lib/talons/CartPage/PriceSummary/usePriceSummary.md

  5. Run yarn dev to build the docs locally and verify the changed files:

  6. Commit and push your release branch to the repo.

  7. Create a PR to merge the source-code changes into main:

    ## Purpose of this pull request

This pull request (PR) updates the docs based on the source-code JSDoc changes made for PWA Studio 13.1.0.

## Affected pages

- src/data/auto-generated/magento-compatibility.md
- src/data/auto-generated/peregrine/lib/talons/CartPage/PriceSummary/usePriceSummary.md

  8. Fix all markdown linting errors.

    NOTE: You WILL have markdown linting errors that you will need to correct. These errors are created by the auto-generated markdown from the magento/pwa-studio code base. If you want to fix this at the source, you can adjust the .hbs files here: magento/pwa-devdocs/scripts/create-reference-docs/templates/handlebars.

    Otherwise, the linting issues you will encounter are described in the logs. Here are two examples:

    ![image-20230414135520471](/Users/case/Library/Application Support/typora-user-images/image-20230414135520471.png)

  9. After all CI/CD tests (markdown linters, etc.) pass and your reviewers have approved, merge your PR into main.

PART 3: Deploy docs to Production

After the merge tests to main have completed successfully, it's time to deploy the documentation changes to the public. Follow these steps.

  1. Navigate to the Deployment UI on GitHub: https://github.com/AdobeDocs/commerce-pwa-studio/actions/workflows/deploy.yml

  2. Click the Run Workflow button and configure the dialog as follows:

    • Use workflow from: Branch: main.
    • Deploy to: prod.
    • Clean cache: yes.

    ![image-20230414141355699](/Users/case/Library/Application Support/typora-user-images/image-20230414141355699.png)

  3. After Deployment is successful, check the live site to make sure the changes are displayed. It may take up to 10 minutes for Fastly to update the site after deployment.