Add a workflow for nitpicking on trailing spaces and similar issues (to discuss)

[ghost]

PR creator: Description

Adds a GitHub workflow to find when commits add:

• trailing spaces (and trailing protected spaces)
• tabs
• Windows/Mac line ends
• long lines (lines outside of a screen that are longer than 90 characters -- 90 characters gives some leeway over the normal 80 characters)

Caveats etc.:

* This is the hackiest possible implementation, if we agree to do this,
  it would probably be best to use an own GitHub Action action for it.
* I wanted to use "continue-on-error: true" in my steps but while that
  correctly recognizes all issues, people would not see the evil red
  X marking the check failed (which arguably we want to have).
* Output is not particularly pretty currently.
* On longer PRs, the current output may be a bit confusing, because we
  don't try to give file names/lines that failed.
* This only runs on PRs. Running on push would mean running after the
  damage is already dones.
* This will only compare main..my-branch, rather than each commit added
  to my-branch individually
* Checking out the 1.3 GB doc-sle repo for 10 seconds worth of scripts
  is a bit wasteful. Unfortunately, it would not work easily with any
  kind of `git clone --depth` setting. :/

PR creator: Which product versions do the changes apply to?

When opening a PR, check all versions of the documentation that your PR applies to.

• SLE 15/openSUSE Leap 15.x
  • SLE 15 SP4/openSUSE Leap 15.4 (if applicable to 15 SP4 only -- do not merge yet!)
  • SLE 15 SP3/openSUSE Leap 15.3 (current main, no backport necessary)
  • SLE 15 SP2/openSUSE Leap 15.2
  • SLE 15 SP1
  • SLE 15 GA
• SLE 12
  • SLE 12 SP5
  • SLE 12 SP4
  • SLE 12 SP3

PR reviewer only: Have all backports been applied?

The doc team member merging your PR will take care of backporting to older documents.
When opening a PR, do not set the following check box.

• all necessary backports are done

[tomschr]

Thanks, looks good! 👍 I have some minor comments:

• As shown below, I'd really suggest to use the ::error::{message} template to make error messages consistent and distinct from other debug messages.

• You can avoid the exit commands (see my comment below). Would reduce the line count a bit.

• If you really want to keep the exit commands, maybe reduce it like this:

    if [ ... ]; then
        echo "::error::Something bad happens"
        exit 1
    fi
    echo "All fine"
  

Hope this helps. 🙂

[tomschr]

I'd suggest to use the GitHub formatted error message to make it visually distinct from other messages:

https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-error-message

Syntax

::error file={name},line={line},col={col}::{message}

Most of these parameters are optional. So you would probably use something like this:

Suggested change

	echo -e "\nThis pull request introduces tabs (→) on the following lines:"
	echo -e "\n$tab\n"
	echo "::error::This pull request introduces tabs (→) on the following lines:"
	echo "::error::$tab"

You may want to apply it to the other echo commands as well.

[ghost]

An exit command isn't really necessary if you use the template from previous item. The Action will stop this step anyway.

If that is true, then using two echos with ::error:: in succession as suggested here won't work, because it'd exit after the first ::error:: message. I am also unsure if ::error:: allows for -e which is extremely necessary for the second echo.

Additionally, an exit just blows up the code for my taste.

exit 1; is 7 characters ... if anything "blows up the code", it's hardly that.^^

You can use the continue-on-error: true. What you need is to "summarize" the result of each steps into an output. Then in a last step you check each one and react accordingly

I should probably do something like that. It could have been less work though if continue-on-error worked better though. :/

[tomschr]

An exit command isn't really necessary if you use the template from previous item. The Action will stop this step anyway.

If that is true, then using two echos with ::error:: in succession as suggested here won't work, because it'd exit after the first ::error:: message. I am also unsure if ::error:: allows for -e which is extremely necessary for the second echo.

Right, maybe I misremembered that.

Additionally, an exit just blows up the code for my taste.

exit 1; is 7 characters ... if anything "blows up the code", it's hardly that.^^

It's not only this line, there are other lines. But it's probably a matter of taste, so ignore that. 😉

I should probably do something like that. It could have been less work though if continue-on-error worked better though. :/

Right. It was just an idea. As you wrote, maybe for the future it would be better anyway to move it into a "real" GH Action. But for the time being, you could leave it as is.

[tomschr]

Regarding this item:

I wanted to use "continue-on-error: true" in my steps but while that correctly recognizes all issues, people would not see the evil red X marking the check failed (which arguably we want to have).

You can use the continue-on-error: true. What you need is to "summarize" the result of each steps into an output. Then in a last step you check each one and react accordingly. Here is a rough snippet:

jobs:
  nitpicks:
    steps:
      - name: Step 1
        id: step1
        run: |
           # ... $RESULT can be 0 or 1
           echo "::set-output name=result::$RESULT"

      - name: Step 2
        id: step2
        run: |
           # ... $RESULT can be 0 or 1
           echo "::set-output name=result::$RESULT"

     # many more steps in between
     - name: Collect result from each step
       run: |
          if [[ $(( ${{ steps.step1.outputs.result }} + ${{ steps.step2.outputs.result }} )) -ge 1 ]]; then
            # ... maybe output something useful
            exit 1
          fi

(Haven't tested it yet, but I think it should work.)

[ghost]

@tomschr @taroth21 I am wondering what to do with this now.

• I will not get to finishing this and making this better. (Big issue: It does not tell you which files are failing.)
• I am worrying that it might ultimately just have the effect of people ignoring CI altogether because they will see a red icon very often, despite the documentation building. (I think many people are still not used to looking at the CI error log and think CI is a complete black box.) So this workflow might achieve the opposite of its stated goal.

[tomschr]

@sknorr
I was curious and looked at the marketplace and voilá! For the trailing whitespace issue, there is already an existing Action: https://github.com/marketplace/actions/find-trailing-whitespace Could serve as inspiration?

Although this Action would be nice, I think it isn't something of uttermost importance. You don't need to finish this. Just leave it open for the time being and we can come back later. We could discuss it for the next SLE writers call.

[ghost]

https://github.com/marketplace/actions/find-trailing-whitespace

The implementation there is ... lacking, even compared to what I have:

• It checks all files, rather than just the diffs (in a big project like doc-sle, this means that the first person to run this tool will be staring into a firehose of thousands of issues)
• Despite that simple approach, it does not output the name of the file or the line number with the trailing spaces
• It really only checks trailing spaces, nothing else.

I am pretty sure that there is an existing action that is much better than mine, but this is not the one. :)