cypress-documentation

cypress-documentation copied to clipboard

Subject

Contributing - Plugins

Description

The Plugins list includes a link "Follow these instructions to submit your own plugin." as a section in the CONTRIBUTING document - see below under "Adding Plugins" for full text.

It however does not deal with the situation that a listed plugin no longer meets the criteria for new submission.

Suggestion

Add a new section to CONTRIBUTING which deals with maintaining plugins.

• What are the criteria for plugins to remain on the Plugins list?
• What are the criteria for a plugin to be listed in the Plugins list > Legacy section? For instance is there a minimum version of Cypress which the plugin needs to be compatible with?

Discussion

The Plugins list > Legacy section does not define the meaning of "Legacy", so unless there is some text added to the Legacy section, it is unclear what it means when a plugin is listed in this section.

• Legacy could refer to a plugin which runs only on Cypress 9 and below using a Configuration (Legacy)
• Legacy could also refer to plugins which are archived, deprecated or otherwise unsupported

Problematic plugin states

• Plugin's npm registry entry is deprecated
• Plugin is explicitly deprecated in source repo
• Plugin's source repo is archived
• Plugin is not compatible with current major version of Cypress
• Plugin's CI pipeline fails

Examples

@cypress/xpath

• npm package @cypress/xpath

$ npm view @cypress/xpath deprecated
Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

• Source https://github.com/cypress-io/cypress/tree/develop/npm/xpath#readme

@cypress/xpath has been deprecated and is no longer supported.

@cypress/skip-test

• npm package @cypress/skip-test

• Source https://github.com/cypress-io/cypress-skip-test archived on Jan 31, 2023.

• https://github.com/cypress-io/cypress-skip-test/blob/1f9bb3ee95dcbc3884c4cc2c8d1692509ba0ab44/package.json#L23 specifies old "cypress": "6.2.1"

• CircleCI https://app.circleci.com/pipelines/github/cypress-io/cypress-skip-test no longer configured

• Last commit https://github.com/cypress-io/cypress-skip-test/commit/1f9bb3ee95dcbc3884c4cc2c8d1692509ba0ab44 failed CircleCI

---

CONTRIBUTING

Text copied from https://github.com/cypress-io/cypress-documentation/blob/master/CONTRIBUTING.md#adding-plugins:

Adding Plugins

To add a plugin, submit a pull request with the corresponding data added to the plugins.json file. Your plugin should have a name, description, link to the plugin's code, as well as any keywords.

We want to showcase plugins that work and have a good developer experience. This means that a good plugin generally has:

1. Purpose of plugin articulated up front
2. Installation guide
3. Options and API are documented
4. Easy to follow documentation. Users should not have to read the source code to get things working.

Each plugin submitted to the plugins list should have the following:

1. Integration tests with Cypress

   • Demonstrates the plugin working
   • Acts as real-world example usage

2. CI pipeline

3. Compatibility with at least the latest major version of Cypress

Plugins are listed in in the following order to for users:

• official
• verified
• community
• experimental

---

Depending on the criteria for keeping deprecated plugins displayed in the list and therefore the number of plugins in this category, it might be better to introduce a deprecated badge and then leave each affected plugin listed in its existing category instead of collecting all deprecated plugins at the end of the list.

This issue was assigned to Ely who left the organization.

The issue is still very relevant and it needs some management decisions from the Cypress team.

What is the compatibility criteria for a plugin to remain on the full list?

• Suggestion: Should provide support for at least the previous latest major version i.e. currently Cypress 12.x.

What is the compatibility criteria for a plugin to remain on the deprecated list?

• Suggestion: Should provide support for at least the latest legacy major version i.e. Cypress 9.x.