Skip to content

Commerce Testing Documentation

Jump to bottom
Jeff Matthews edited this page Sep 15, 2022 · 14 revisions

Welcome to the commerce-testing wiki!

This wiki provides detailed work instructions for maintaining the Commerce Testing technical documentation site.

The commerce-testing repo contains source files (primarily Markdown) for the Application Testing and Functional Acceptance Testing guides.

NOTE: Members of the mftf-maintainers team have write access to this repo, but write access is not necessary to fork and create pull requests.

Project structure

As a maintainer, your primary task will involve editing content in the .md files. However, you may also need to edit .js files to update the site navigation. Both .md and .js files are stored in the src/ directory. See the following for a description of the structure of the src/ directory:

  • src/data/navigation/: Contains .js files that control site navigation.
  • src/pages/: Contains .md files that include documentation (also includes images, such as .png and .svg).

Common maintenance tasks

The commerce-testing repo is a Gatsby project that uses the aio-theme for core functionality (e.g., styling, Gatsby plugins). The aio-theme README provides advanced instructions for customizing a project, but it contains a lot of extra information that isn't necessary for the most common documentation tasks, including:

  • Editing an existing page
  • Adding a new page
  • Deploying the site to the staging environment
  • Deploying the site to the production environment

Edit a page

To edit an existing page, you can either use the GitHub web interface (simple) or fork this repo and work locally (advanced).

GitHub web interface

For simple updates to a single page, you can use the GitHub web interface.

  1. Click the Edit in GitHub button at the top of any documentation page:

    Screen Shot 2022-08-19 at 11 33 51 AM

  2. Edit the file.

  3. Add a commit message.

  4. Click Create a new branch for this commit and start a pull request.

    The main branch is protected, so you cannot commit directly to it.

    Screen Shot 2022-08-19 at 11 35 47 AM

  5. Click Propose changes.

  6. Complete the pull request template.

  7. Request a review from a team member who has write access to the repo.

Fork

For complex updates to multiple pages, you should fork the repo and work locally. See the GitHub docs for instructions.

Add a new page

Adding a new page is considered an advanced task. You should fork the repo and work locally, then create a pull request.

  1. Fork the repo.

  2. Navigate to your local project.

  3. Create a new .md file in the src/pages/ directory.

  4. Add the appropriate metadata to the top of the file.

    ---
title: New page
description: Description required for SEO best practices.
---

  5. Add a first-level heading. It should match the metadata title property.

    # New page

  6. Add content. See existing files for examples.

  7. Add the new file to the navigation. In most cases, you will only need to update an existing section (src/data/navigation/sections/). You will not need to add a new header (src/data/navigation/header.js).

    1. For Functional Acceptance Testing updates, open the src/data/navigation/sections/framework.js/ file.
    2. Add a new entry to the multi-level side navigation using JSON.
    3. Save your changes.

  8. Build the site locally to verify your changes and that the navigation works as expected.

    yarn dev

  9. Create a pull request.

Deploy the site

NOTE: Access to the deployment workflows is currently restricted to members of the Pangolins team.

This repo uses GitHub Actions to deploy the site to Microsoft Azure static site hosting. You can deploy to staging or production using the same workflow.

Staging

You can deploy a working branch to a non-production staging environment for review: https://developer-staging.adobe.com/commerce/testing/

  1. Click Actions > Deployment > Run workflow.
  2. Select the branch that you want to deploy.
  3. Use the default option for Clean cache (no).
  4. Click Run workflow.

Production

You should only deploy the main branch to the production environment: https://developer.adobe.com/commerce/testing/

To deploy the site after merging a pull request with the main branch:

  1. Click Actions > Deployment > Run workflow.
  2. Select the main branch.
  3. Use the default option for Clean cache (no).
  4. Click Run workflow.
Clone this wiki locally