When to jump ship for new go fmt behavior?

[thediveo]

As of Go 1.19 go fmt now has changed formatting behavior regarding go documentation comments, such as header identification using #, bullet list, et cetera.

As this will naturally cause a larger diff I would suggest doing this once and for all when Go 1.20 will be officially released, so that we adhere to the N and N-1 support rule. The github actions need to be adapted, so that we run go fmt checks on at least 1.19 rules.

What do you think?

[onsi]

I think that makes sense. So basically, no actions until 1.20 is released and then run go fat and clean up the doc comments and push out a commit with updated gh action rules?

I can get behind that - thanks for bringing it up proactively. I wasn't even aware they had made this change.

...wonder why they didn't adopt markdown more formally, though. There's some subtle differences I think.

[thediveo]

I wouldn't call them "subtle" differences.

[onsi]

LOL I was being "generous"

[pohly]

Why wait for 1.20? The format changes are compatible with the rules for older Go, i.e. one can reformat the comments with "go fmt" from Go 1.19 and they will pass a format check with Go 1.18.

[thediveo]

Ah, I missed that. Nevertheless, at some point we need to jump ship the CI where the gofmt checks are done and switch to 1.19. Should we dothis at the same time, affecting future PRs, or wait? I would switch gofmt at the same time, as PRs need to work on 1.19 anyway. Am I overlooking something here?

[pohly]

I would update all comments and move gofmt checking to 1.19 in a single PR. Then once that PR is merged, the updated formatting requirements are met and enforced.