WordPress/gutenberg

ESLint plugin: Relax the rule for @since in JSDoc

Open

#20,859 opened on Mar 13, 2020

View on GitHub
 (0 comments) (1 reaction) (0 assignees)JavaScript (3,893 forks)batch import
Good First IssueNeeds Dev[Status] In Progress[Tool] ESLint plugin[Type] Enhancement

Repository metrics

Stars
 (9,607 stars)
PR merge metrics
 (Avg merge 12d 18h) (509 merged PRs in 30d)

Description

Is your feature request related to a problem? Please describe.

When increasing the severity of eslint-plugin-jsdoc to error (#20427), we found that the rule for @since doesn't allow explanation after version number.

// It's an error below.
/**
* @since 8.8.8 An awesome change
*/

But it's a frequently-used pattern in WordPress projects like this. So, we had to disable check-value option in eslint-plugin-jsdoc.

And there's even a documentation for @since for PHP developers.

But this makes us manually check if the version number follows the semver format.

// Below lines are false positives
/**
* @since 3.14
* @since version 7
* @since 6.7.x
*/

Describe the solution you'd like

Create an eslint rule that checks the format below:

@since <required semver> [optional description]

Describe alternatives you've considered

  • I thought about adding this to eslint-plugin-jsdoc. But I think adding description after version number is more of WordPress convention than widely-used one. So, I think it should be implemented in this project rather than eslint-plugin-jsdoc.

Contributor guide

Research direction
Create a custom ESLint rule that validates @since comments follow the format '@since <semver> [optional description]'. Look at existing ESLint plugin examples in the Gutenberg repository for structure. Test with sample JSDoc comments.
Tech stack
javascript
Domain
developer experiencetooling
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
ESLintNode.jsnpm
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40