docs: update submission instructions in DEVELOPMENT.md (#853)

Co-authored-by: Bill Glesias <[email protected]>
Co-authored-by: Emily Rohrbough <[email protected]>

Author: 3 people

DEVELOPMENT.md

@@ -1,40 +1,82 @@
 # Development
 
-## Testing via examples
-
-1. Add a new example project in `examples` folder. It is a regular NPM package with its own `package.json` and Cypress dev dependency.
-1. Add a corresponding `.github/workflows` YAML file that uses this action and runs inside `examples/X` working directory. The example should demonstrate the feature
-1. Add workflow badge to README if needed
-
-## Testing against another repo
-
-1. Create a new local branch for any development, for example `git checkout -b featureA`
-1. Update the source code in [index.js](index.js)
-1. Build `dist` file(s) using `npm run build`
-1. Commit any changed files, note the SHA of the commit
-1. Push the local branch to GitHub
-1. In a test repository, create a test branch, change the action to point at the new commit. Example
-
-```yml
-name: End-to-end tests
-on: push
-jobs:
-  cypress-run:
-    runs-on: 22.04
-    steps:
-      - uses: actions/checkout@v3
-      # use specific commit pushed to GitHub
-      - uses: cypress-io/github-action@<full commit SHA>
+This document describes topics useful to contributors to this repository. The repository's purpose is to provide a GitHub JavaScript action which is published to:
+
+1. npm's JavaScript Package Registry as [@cypress/github-action](https://www.npmjs.com/package/@cypress/github-action)
+2. GitHub's Marketplace as [cypress-io/github-action](https://github.com/marketplace/actions/cypress-io#cypress-iogithub-action--)
+
+You can read the GitHub document [Creating a JavaScript action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action) for background information on how JavaScript actions for GitHub are created and how they work.
+
+## Providing fixes or features
+
+If you are submitting a Pull Request (PR) to provide a fix or feature for the action, the following is relevant to you:
+
+The main source code elements for the action are:
+- [action.yml](action.yml)
+- [index.js](index.js)
+- [src/ping.js](src/ping.js)
+
+The action runs from the [dist](dist) directory, which requires a `build` step to set up. This step uses [@vercel/ncc](https://github.com/vercel/ncc) to compile the code and modules into one file used for distribution.
+
+To contribute changes, follow these instructions in the order given below:
+
+1. If you are a new external contributor, then first fork the repository (see GitHub documentation [About forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)).
+1. Create a new branch with a meaningful name e.g. `fix/my-bug` based on the current `master` branch.
+1. Make the necessary source code changes, including additions or changes to the [README.md](./README.md) documentation if parameters are added or affected.
+1. Ensure you are using [Node.js LTS](https://nodejs.org/en).
+1. Execute the following in the root directory of the cloned repository
+
+```bash
+npm install
+npm run format
+npm run build
+```
+
+6. Commit the change. (If you are working on Microsoft Windows, see [Windows users](#windows-users) below.)
+1. Push to the repository.
+1. If you are working in a fork, ensure actions are enabled.
+1. Refer to [Manually running a workflow](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) to use this to test any particular workflow affected by your change.
+1. Open a draft PR with a title which starts with `fix:` or `feat:` if a new release should be triggered by the PR. For more details on the release process, see the section [Merging pull requests](#merging-pull-requests) below.
+1. Note that first-time submitters must sign the CLA agreement and be approved to run workflows.
+1. Check that all tests which are triggered by the PR were either successful or were skipped.
+1. If the PR is showing that the tests were successful mark the PR as Ready for Review.
+
+### Windows users
+
+The repository is set up with a `git` / `Husky` pre-commit hook which ensures that any changes to the core source files are formatted and built consistently before they are committed. This does not work well with [GitHub Desktop](https://docs.github.com/en/desktop). You can disable this function by setting an environment variable `HUSKY=0`. If you do this and then omit to use `npm run format` / `npm run build` before you commit any changes affecting the core source files, you will find that checks fail when you submit a PR. In this case you should run the format and build commands and amend your commit.
+
+## Adding a new example
+
+1. If you are creating a new example, add this as a new project in the `examples` directory. An example project is a regular NPM package with its own `package.json` and Cypress dev dependency. (Note: Legacy `examples/v9` should not be extended.)
+2. Add a corresponding `.github/workflows` YAML file that uses this action and runs using your new `examples/X` through the `working-directory` parameter. The example should demonstrate any new feature.
+3. Add a workflow status badge to the [README.md](README.md) file (see [Adding a workflow status badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge)), like the following:
+
+[![Chrome example](https://github.com/cypress-io/github-action/workflows/example-chrome/badge.svg?branch=master)](.github/workflows/example-chrome.yml)
+
+## External Testing
+
+The example workflows in [.github/workflows](./.github/workflows) specify
+
+`uses: ./`
+
+which calls the action code from the branch they are running in when the workflow is run directly in the repository here.
+
+From another (external) repository, the production version of the action is called with
+
+```yaml
+- uses: cypress-io/github-action@v5
 ```
 
-You can use [cypress-gh-action-example](https://github.com/bahmutov/cypress-gh-action-example) or [cypress-gh-action-monorepo](https://github.com/bahmutov/cypress-gh-action-monorepo) as test projects.
+To test out a branch in development calling it from another repository, replace `v5` by the name of your branch. If your branch is in a fork, then also replace `cypress-io` by your own GitHub username in the form:
+
+`- uses: <your-username>/github-action@<your-branch>`
 
-7. Push the change and make sure the new feature performs correctly. If yes, open a pull request.
+## Merging pull requests
 
-**For pull request reviewers:**
+This information is for Cypress.io Members or Collaborators who merge pull requests:
 
-1. When merging a pull request, squash all commits into one.
-1. Make sure the commit subject and body follow [semantic commit convention](https://semantic-release.gitbook.io/semantic-release/#commit-message-format). For instance, keeping it simple:
+1. When merging a pull request, use the [Squash and merge](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits) option to squash all commits into one.
+1. Make sure the commit subject and body follow [semantic commit convention](https://semantic-release.gitbook.io/semantic-release/#commit-message-format), for instance:
 
 ```text
 feat: added new parameter
@@ -46,14 +88,15 @@ If you need to bump the major version, mark it as breaking change in the body of
 ```text
 fix: upgrade dependency X
 
-BREAKING CHANGE: requires minimum Node.js 14 to run
+BREAKING CHANGE: requires minimum Node.js 16 to run
 ```
 
-3. New versions of this action will be released automatically by the CI, see [.github/workflows/main.yml](.github/workflows/main.yml). This will create a new [GitHub release](https://github.com/cypress-io/github-action/releases) and will update the current `/v5` branch. Thus specifying `- uses: cypress-io/github-action@v5` selects the new version automatically.
+3. New versions of this action will be released automatically by the CI when merged to master, see [.github/workflows/main.yml](.github/workflows/main.yml). This will create a new [GitHub release](https://github.com/cypress-io/github-action/releases) and will update the current `v5` branch. Thus specifying `uses: cypress-io/github-action@v5` selects the new version automatically. This **will not** push the latest release to Github Marketplace.
+4. The action's CI is configured to use the [default Angular release rules](https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-rules.js). This means that only `feat:`, `fix:` and `perf:` trigger a new release which is then logged to the [releases](https://github.com/cypress-io/github-action/releases) page. Other Angular commit types listed on [Contributing to Angular](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) can be used for documentation purposes, however they are ignored by the currently configured release process.
 
-## Updating the latest version in GitHub Marketplace
+## GitHub Marketplace publication
 
-Seems to be a manual process right now. After a new release has been created, go to the release and click "Edit"
+Publishing a new release to the GitHub Marketplace is a manual process. After a new release has been created, go to the release and click "Edit"
 
 ![Edit the release](images/edit-release.png)
 
@@ -64,3 +107,5 @@ Review the release info, make sure the "publish ..." checkbox is checked
 After clicking "Update the release" check that the Marketplace [https://github.com/marketplace/actions/cypress-io](https://github.com/marketplace/actions/cypress-io) has been updated.
 
 ![Latest release in marketplace](images/latest-release.png)
+
+See also [Publishing actions in GitHub Marketplace](https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace).