clean up a bit of the installer docs

[deitch]

Just a little bit of installer docs cleanup.

[deitch]

Should not require full CI other than yetus, since I am changing just two markdown files.

[deitch]

I am ignoring yetus complaints about sections I did not change.

[christoph-zededa]

I am ignoring yetus complaints about sections I did not change.

But don't they appear because of your changes?
I mean f.e.:

markdownlint:MD051/link-fragments Link fragments should be valid [Context: "[following these instructions](#how-to-write-eve-image-and-installer-onto-an-sd-card-or-an-installer-medium)"]

and you changed the "location" so that they point into the void.

[deitch]

Oh, you may be right. I just looked at the line it was complaining about and thought, "there goes yetus again". Good catch @christoph-zededa ; I will check and update if necessary

[deitch]

Yup, you were right. Fixed it.

[deitch]

This is strange. How am I seeing go test failures for something that changes only markdown? This markdown cannot have broken go code.

I also see it is complaining about lint messages. The message is brief and to the point, and is signed. What is it complaining about?

[OhmSpectator]

I also see it is complaining about lint messages. The message is brief and to the point, and is signed. What is it complaining about?

We would like to see a body for commit messages. Like what you usually put into the PR description =)

[OhmSpectator]

This is strange. How am I seeing go test failures for something that changes only markdown? This markdown cannot have broken go code.

ERROR: failed to solve: lfedge/eve-alpine:1f7685f95a475c6bbe682f0b976f12180b6c8726: failed to resolve source metadata for docker.io/lfedge/eve-alpine:1f7685f95a475c6bbe682f0b976f12180b6c8726: failed to authorize: failed to fetch oauth token: unexpected status from POST request to https://auth.docker.io/token: 502 Bad Gateway

I see it time to time...

[deitch]

We would like to see a body for commit messages. Like what you usually put into the PR description

It shouldn't complain about a single line; sometimes that is more than enough.

[OhmSpectator]

It shouldn't complain about a single line; sometimes that is more than enough.

Sometimes, yes. But in most cases, it is not, and people just don't put any details in commit messages (at the same time, they are fine with providing an explanation in the PR description)).
So we have introduced a quick check to remind devs to put more description.
If you are absolutely sure one line is enough, then the checks can be just ignored. But it's kind of 10% of all cases when people omit body. =(

[europaul]

Just some typos in the docker commands, otherwise LGTM

[OhmSpectator]

If I were the one who created the commit, I would put the following body:

Refined installer documentation for clarity and usability. Updated terminology
to "storage media" throughout. Enhanced instructions on flashing images by
recommending better graphical tools. Added disclaimers for third-party tools.

But I do not insist =D

[rene]

It shouldn't complain about a single line; sometimes that is more than enough.

Sometimes, yes. But in most cases, it is not, and people just don't put any details in commit messages (at the same time, they are fine with providing an explanation in the PR description)). So we have introduced a quick check to remind devs to put more description. If you are absolutely sure one line is enough, then the checks can be just ignored. But it's kind of 10% of all cases when people omit body. =(

If I were the one who created the commit, I would put the following body:

Refined installer documentation for clarity and usability. Updated terminology
to "storage media" throughout. Enhanced instructions on flashing images by
recommending better graphical tools. Added disclaimers for third-party tools.

But I do not insist =D

@deitch got a specific case, for this kind of changes, yeah, a single line is enough. However, as @OhmSpectator pointed out (very well) the idea is to avoid commits that changes a lot of stuff without a suitable (to not say any) explanation. It works while reviewing the PR, for a couple of days and/or weeks, but once you need to revisit changes done long time ago (or not so long), it might be painful to quickly understand all the details without a good explanation. IMHO, forbid commit message without a body it's an affordable price to pay consider the benefits... TBH the only drawback I can tell is to enforce put a description for messages that one line would be sufficient, like this PR....

But, since we introduced the check, let's follow it, make exceptions just open the way for more discussion, so in this case is better to remove the check.....

[deitch]

Agreed. So let's ignore here. Need an approval and I can merge it in.

[OhmSpectator]

Yep, let's approve this, and do not slow down the merging)
For some reason I don't see an approve button..
Upd. Done.

[deitch]

It worked, thanks @OhmSpectator

I will merge it in to stop wasting eden test resources on this.

[OhmSpectator]

It worked, thanks @OhmSpectator

I will merge it in to stop wasting eden test resources on this.

By the way, as far as I understand, Eden will work anyway, as a part of "push" into master action. Yep, we have a lot of actions working on commits at the moment they're merged...

[deitch]

Good point. Yash is working on all of that as far as I know.