Adding .git-blame-ignore-revs for "bulk cosmetic changes" on Rails Guides

rubyonrails-docs
1

I’ve been wondering if I could perform bulk cosmetic changes on Rails Guides for integrity. Currently the inconsistency disturbs us when updating Rails Guides translations.

Of course I recognize that a policy that is stated in #13771: staggered cosmetic changes would disturb other developers especially when git blame. So I thought I had no chance to do that.

Recently git added a new feature: blame.ignoreRevsFile config options on 209f075.

Adding .git-blame-ignore-revs file to the project, and perform the following:

$ git config --global blame.ignoreRevsFile .git-blame-ignore-revs

Then we can add the cosmetic commits to .git-blame-ignore-revs to ignore them when git blame. GitHub already supports the feature on Web UI, assuming the filename .git-blame-ignore-revs.

I guess this feature may be a good tool for us to perform bulk cosmetic changes on Rails Guides to make the style consistent.

Considerations:

  • Each developer has to perform the git config above to activate them?
  • Whether the filename .git-blame-ignore-revs is ready for other repositories or tools such as GitLab or Git Lens
  • The bulk cosmetic commits should be squashed to avoid slowing down.
  • ruby_on_rails_guides_guidelines.md should also be updated to describe this.

Any ideas or mentions?

2

I’m not sure, but it seems ignoring specific revisions would be per-client.

Do you have any examples of changes you’d like to make?

1 Like
3

Thank you for the reply!

The most changes I’d like to to make:

  • fragmented paragraphs by around 80 chars:

20230304_093646_UVlBiY
20230304_093646_UVlBiY2274×700 142 KB

Seems most people don’t mind that (perhaps because this does not effect the html), but this is very bad for translation to other language.

  • fix missing language indications on code blocks, such as bash or html+erb

  • change Note. or Warn. to NOTE: or WARNING:

  • Use the separated link style (highlighted yellow) for external links

image
image2266×1510 479 KB

I recognize that the priority of such trivial and cosmetic changes is low. I wish I just had a chance to do that.

4

@hachi8833 Sorry for the delay, after a quick think. I want to get rubocop-md and markdownlint merged before making any major changes.

The idea is that we can then enforce these decisions and not have to constantly monitor PRs that don’t adopt this style.

It seems really straight forward to implement custom markdown lint rules as well!

1 Like
5

Sounds nice! I agree with the idea that just leaving them to RuboCop is the best.

1 Like
6

I’ve cleaned up and got this PR ready:

They provide many existing rules and it seems straight-forward to add our own custom rules, like for the ones you’re suggesting. There is already a rule for line-length, which I’ve set to 2000 but we can put it somewhere more reasonable, like 200. I’m not sure how you would detect fragmented paragraphs however, still some interesting stuff to work with that will hopefully save us and contributors time in code review.

1 Like
7

Great! I look forward to the merging.