Significant behavior change not documented in release notes

per1234 commented 1 year ago

v1 of the action ran editorconfig-checker on the files in the workspace:

https://github.com/editorconfig-checker/action-editorconfig-checker/blob/0527b11555ed46afd00df746f35b79cb7f7b68c2/src/entrypoint.sh#L3

v2 of the action makes editorconfig-checker available in the runner machine for use by subsequent steps in the job, but the action itself does not run editorconfig-checker.

The subsequent major version bump indicates to the existing users of the action that there was a breaking change, but there is no effective communication of what the change was. We are only given a list of seemingly non-breaking changes in the release notes. The users bumping the action in their workflows will need to do quite some investigation to discover that what is described incredibly vaguely as "refactor" in the release notes is actually FAR more than a refactoring (which by definition should not cause any change in behavior) and includes a complete change in the action's behavior.

Exacerbating the problem of poor communication is that there will not be any immediate symptom of the behavior change to the users. If their workflow runs were passing before bumping the action due to the files of their repository being .editorconfig compliant, they will only see that the workflow runs continue to pass after the bump. Maintainers may consider a browse of the release notes and a passing workflow run to be sufficient validation of the action bump and not realize that if they don't add a new step to their workflow to actually execute editorconfig-checker then they will no longer be getting any validation of the .editorconfig compliance of their files.

I think the behavior change is reasonable but it should be clearly communicated to the existing users in the release notes. I recommend providing some guidance in the migration of the workflows (the addition of the subsequent step to execute editorconfig-checker.

mstruebing commented 1 year ago

That's why I couldn't find where the action is executing the checker 😆 Could someone prepare something I can add to the release notes? That would be great.

per1234 commented 1 year ago

Could someone prepare something I can add to the release notes?

@mstruebing I will take responsibility for doing that. I'll add my proposed updated release notes in a comment here as soon as I am done. I'm working on it now.

per1234 commented 1 year ago

@mstruebing here it is. I provide the complete contents of the release notes so that it can replace the current content wholesale rather than requiring a merge of the texts:

## What's Changed

### Breaking

#### Behavior change in #10

Prior to 2.0.0 the purpose of the action was to run **editorconfig-checker** on the files in the workspace. The purpose of the action is now solely to make **editorconfig-checker** available in the runner machine for use by subsequent steps in the job.

##### Migration Guide

A new step that invokes `editorconfig-checker` must be added to the workflow.

**Before:**

```yaml
- name: Check EditorConfig compliance
  uses: editorconfig-checker/action-editorconfig-checker@v1

After:

- name: Install editorconfig-checker
  uses: editorconfig-checker/action-editorconfig-checker@v2

- name: Check EditorConfig compliance
  run: editorconfig-checker

Removal of `output` output in #10

Prior to 2.0.0 the action provided an output named output that contained the output from running editorconfig-checker on the files in the workspace. This output could be referenced by the action user in subsequent steps/jobs of their workflow.

Due to the change in the action's behavior, the output is no longer provided. If needed, you can capture and use the output in the shell code of the step in the workflow that invokes editorconfig-checker.

Enhancement

Add optional github-token input in #10
Add optional version input in #10
refactor by @septs in #10
Bump @types/node from 17.0.21 to 20.6.4 by @dependabot in #14
Bump @vercel/ncc from 0.33.3 to 0.38.0 by @dependabot in #15
Bump @actions/github from 5.0.0 to 5.1.1 by @dependabot in #16
Bump typescript from 4.5.5 to 5.2.2 by @dependabot in #17
Bump @actions/tool-cache from 1.7.1 to 2.0.1 by @dependabot in #18
chore: update actions core by @mstruebing in #19

New Contributors

@septs made their first contribution in #10
@dependabot made their first contribution in #14

Full Changelog: v1...v2.0.0



I'm happy to make adjustments if you have any requests.

mstruebing commented 1 year ago

Thank you very much! I've edited them right now.

editorconfig-checker / action-editorconfig-checker