[Marketplace] update action docs to state that yml is the preferred format and to describe what happens when changing between yml and yaml formats (#54311)

Co-authored-by: Anne-Marie <[email protected]>
Co-authored-by: Kevin Heis <[email protected]>

Author: 3 people

content/actions/sharing-automations/creating-actions/about-custom-actions.md

@@ -32,7 +32,7 @@ Actions can run directly on a machine or in a Docker container. You can define a
 
 ## Types of actions
 
-You can build Docker container, JavaScript, and composite actions. Actions require a metadata file to define the inputs, outputs and main entrypoint for your action. The metadata filename must be either `action.yml` or `action.yaml`. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions).
+You can build Docker container, JavaScript, and composite actions. Actions require a metadata file to define the inputs, outputs and main entrypoint for your action. The metadata filename must be `action.yml`. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions).
 
 {% rowheaders %}
 

content/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions.md

@@ -19,7 +19,7 @@ type: reference
 
 ## About YAML syntax for {% data variables.product.prodname_actions %}
 
-All actions require a metadata file. The metadata filename must be either `action.yml` or `action.yaml`. The data in the metadata file defines the inputs, outputs, and runs configuration for your action.
+All actions require a metadata file. The metadata filename must be either `action.yml` or `action.yaml`. The preferred format is `action.yml`. The data in the metadata file defines the inputs, outputs, and runs configuration for your action.
 
 Action metadata files use YAML syntax. If you're new to YAML, you can read [Learn YAML in five minutes](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes).
 
@@ -771,3 +771,12 @@ Brand icons, and all the following icons, are omitted.
 <li>zoom-in</li>
 <li>zoom-out</li>
 </ul>
+
+{% ifversion fpt or ghec %}
+
+## Changing the metadata file name
+
+While the actions metadata file supports both YAML formats, changing the metadata file name (from `action.yml` to `action.yaml` or vice versa) between releases will affect previous release versions that have been published to {% data variables.product.prodname_marketplace %}. Changing the file name will hide all release versions associated with the previous file name from {% data variables.product.prodname_marketplace %}. Previous release versions will still be accessible to users through the source repository.
+
+When releasing new versions of actions, only versions released after the metadata file name change will have the {% data variables.product.prodname_marketplace %} tag and will show up on {% data variables.product.prodname_marketplace %}
+{% endif %}

content/actions/sharing-automations/creating-actions/publishing-actions-in-github-marketplace.md

@@ -26,7 +26,7 @@ Actions are published to {% data variables.product.prodname_marketplace %} immed
 * The action must be in a public repository.
 * Each repository must contain a single action.
 * Each repository must _not_ contain any workflow files.
-* The action's metadata file (`action.yml` or `action.yaml`) must be in the root directory of the repository.
+* The action's metadata file (`action.yml`) must be in the root directory of the repository.
 * The `name` in the action's metadata file must be unique.
   * The `name` cannot match an existing action name published on {% data variables.product.prodname_marketplace %}.
   * The `name` cannot match a user or organization on {% data variables.product.prodname_dotcom %}, unless the user or organization owner is publishing the action. For example, only the {% data variables.product.prodname_dotcom %} organization can publish an action named `github`.
@@ -40,7 +40,8 @@ You can add the action you've created to {% data variables.product.prodname_mark
 To draft a new release and publish the action to {% data variables.product.prodname_marketplace %}, follow these instructions:
 
 {% data reusables.repositories.navigate-to-repo %}
-1. Navigate to the action metadata file in your repository (`action.yml` or `action.yaml`), and you'll see a banner to publish the action to {% data variables.product.prodname_marketplace %}. Click **Draft a release**.
+
+1. Navigate to the action metadata file in your repository (`action.yml`), and you'll see a banner to publish the action to {% data variables.product.prodname_marketplace %}. Click **Draft a release**.
 1. Under "Release Action", select **Publish this Action to the {% data variables.product.prodname_marketplace %}**.
 
    > [!NOTE]

content/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow.md

@@ -165,7 +165,7 @@ For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-act
 
 An action often accepts or requires inputs and generates outputs that you can use. For example, an action might require you to specify a path to a file, the name of a label, or other data it will use as part of the action processing.
 
-To see the inputs and outputs of an action, check the `action.yml` or `action.yaml` in the root directory of the repository.
+To see the inputs and outputs of an action, check the `action.yml` in the root directory of the repository.
 
 In this example `action.yml`, the `inputs` keyword defines a required input called `file-path`, and includes a default value that will be used if none is specified. The `outputs` keyword defines an output called `results-file`, which tells you where to locate the results.