This repository has been archived by the owner on Jan 30, 2024. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Convert template to US-ASCII to fix error
I introduced some tests in a feature branch to match the contents of `/etc/nginx/router_routes.conf`. They worked fine when run with `bundle exec rake spec` or `bundle exec rspec modules/router/spec`. But when run as `bundle exec rake` each should block failed with: ArgumentError: invalid byte sequence in US-ASCII I eventually found that removing the `.with_content(//)` matchers made the errors go away. That there weren't any weird characters in the spec file. And that it could be reproduced by requiring Puppet in the same interpreter with: rake -E 'require "puppet"' spec That particular template appears to be the only file in our codebase with an identified encoding of `utf-8`. All others are `us-ascii`: dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 Attempting to convert that file back to US-ASCII identified the offending character as something that looked like a whitespace: dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert After replacing it (by hand) the file identifies as `us-ascii` again: dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii Now the tests work! One hour of my life I won't get back..
- Loading branch information
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Did you think it is searchable message? Why didnt you write a doc? Or asked and answered in SO (it could be more usefull)? But you wrote the story with explanation in the commit message, come on, and after 6 years one man told it was great commit message... Are you crazy guys? @dcarley @fatbusinessman
Commit message with the long explanation helps nobody, because it does not searchable by google, even by github. Even project people dont know about it, because how many programmers use search by commit message when they got an error? I will answer for you - nobody. Even if we assume that project people can see the message by scrolling git history there is 27k commit, guys. You really help nobody, and @fatbusinessman wrote an article only for make this commit searchable. If the commit message require a blog post for being good commit message - it is poor commit message.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What you're describing is a deficiency of the search engines, not the commit itself right @nikialeksey?
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@celtric I think that large commit message helps nobody, never. Doc helps, answer on SO helps, readme helps, but long commit message in the commit with only one character changed... No one needs to it, moreover no one will ever see it.
Ok, what do you know about maintainability? Imagine if there is another person in a project (event in this project) who face the challenge
US-ASCII
error, how he can find this commit message which obviously can help? Usually, a programmer googles error and find the answer, but in our case he will not find this commit message. So, this commit message does not improve maintainability.Commit message is not intended to documentation, it will not be formatted, it will not be indexed by search engine, there is no helpful system around it for reading such documentation in commit messages...
Even writing the test (with verifying encoding) would be better, because that guy (who will face the challenge
US-ASCII
error) will se the broken test and understand what happened.63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I disagree depending on the context. I've found descriptive commit message that were very useful when trying to understand why a change was made, as they provided the "why". These messages where right in the place where I would have expected them to be (close to the change).
You suggest:
Although you generalise (or at least I understand that) that "all large commits" are unhelpful, I suppose you're actually talking about commit messages that provide context that you would never care about unless you're suffering the same issue again. That is, a person working in this codebase wouldn't care why a space was added, but someone with the US-ASCII error would.
We agree then that we're not talking about all large commits, just these ones, right? Again, IMHO the problem are the tools (search engines, GitHub, IDEs, etc.) not the commits message itself. Isn't it ridiculous that we cannot find text inside commit messages? In a few years we'll look back and consider this situation ridiculous, and the commit message would not have changed (the tools would).
I think you're right, only partially. If this project's focus was more on the templating itself I would agree, but the core of the project is not about this error, it just happened to suffer it.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Likely reason for the sudden activity if anyone's wondering: https://reddit.com/r/programming/comments/djnp8k/my_favourite_git_commit/
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I use a Karabiner rule on macOS to solve this. Hope this helps a passerby.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Large commit messages help at least me (so your theorem is disproved).
Every time I use things like
git log --grep
,git log -S
,git log -G
,git bisect
I see commit messages as the first meaningful output ofgit
, and as long as these messages explain the motivation of the commit, they are highly useful.By the way,
git bisect
is an easy way towhen you do troubleshooting.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for
git bisect
, @QazerLab. Was doing it manually once to find a bug, didn't know that git helps to automate this :)63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This commit is so awesome that there is a blogpost about it was translated and ended ip in Russian Medium! @dcarley wait for more noobs from Ural who will teach you how to live!
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dcarley @fatbusinessman I'm sorry if I offended you. My english is far from being good. I made a mistake I wrote my comments here, I should have to write my commens somewhere on reddit, hackernews or "Russian Medium". Sorry for that.
I wrote my own blog post about long commit messages (in Russain). It contains all my thoughts about this case and long commit messages.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Your message looking strange, if you criticize - offer. Why you didn't provide a link to SO, but criticizing this guy. He did really useful work but didn't tell anyone. You are just left an unuseful comment and that's it.
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Post on SO below not so good, but I'm lazy today to make it better. The main idea, that's all main info(error message output) will be indexable.
https://stackoverflow.com/questions/58583380/argumenterror-invalid-byte-sequence-in-us-ascii-argument-error-when-i-run-bun/58583429#58583429
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From now on this commit definitely has the biggest recongnition/size ratio!
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
bump
63b36f9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Git commit messages are searchable by Git via
git log
, otherwise what is the point of writing commit messages in the first place?That is a fair question, but not everything needs to be documented in the documentation. The documentation should contain generally helpful information for developers (to develop the software) and, in some cases, for users (to use the software). Very specific bugs in very specific scenarios do not need to be documented in the documentation, otherwise, the documentation will be very dense. Organizing such documentation can also take up a lot of time, maintenance, and effort. Documentation is necessary, of course, but it should also be prudently concise and not overly meandering or complicated, which it might be if it were to include a list of all of the bugs ever encountered during the development of the project, how to reproduce them, what were the steps taken to discover/identify them, and what approaches were taken to fix them.
As mentioned, context switches reduce productivity. Also, links on the Internet are not always accessible. What if you are not able to access the Internet? What if Stack Overflow is down for maintenance? What if the post is deleted due to various reasons? In contrast, as long as you have access to the project files and directories (which would contain the
.git
folder), you would also have access to the Git commit history. It is self-contained. Hence, it is arguable if a post on Stack Overflow would be more useful than the Git commit history of the project itself.Additionally, public forums such as Stack Overflow should not be inundated with project-specific bugs and their details. Some of those details might be relevant to others sometimes, but they will always be relevant to the project itself (by definition). Hence, it should be associated/linked to the project more closely than to be put at some random web URL. In fact, even the project's issue tracker would be a much better place to document bugs than any public forums online.
There is no need to perform ad hominem here.
Firstly, descriptive commit messages have helped me (and other folks in this thread as well), so the first part of the sentence is wrong by counterexample.
Secondly, perhaps the times have changed. This link works. This is also further proof that an inability to search commit messages is more of "a deficiency of the search engines, not the commit itself".
I actually do. In fact, this process is very useful (and is done all the time) for very large projects such as the Linux kernel and the Chromium codebase. Looking through the Git history of such projects can shed some light whenever we encounter some strange/obscure bugs and it also helps with understanding the rationale behind the choices of why something was implemented in a certain way or why something was added/removed in the first place. Coupled with the usage of
git blame
to identify the history of changes for a particular line of code, this has become even more helpful.Again, this has been proven wrong by counterexample.
As mentioned, the number of commits should not be that big of a hindrance.
git bisect run
along with a script can help automate finding culprit commits.Again, proven wrong by counterexample.
Sure, it might not be that visible to the public if they don't intentionally look for the commit. However, it will be visible for those who cloned the repository with its Git history, which is arguably much more valuable since those folks are the ones who are most likely to work on the project in the first place.
I don't think I need to repeat myself here.
Again, I don't believe in cluttering such important documents such as the README and the documentation about very specific/esoteric bugs and how they were discovered/fixed, less so a public discussion forum such as Stack Overflow.
Ditto.
Sure, sometimes we need to search for ideas, inspirations, and solutions using search engines. However, webpages, articles, and online forums are not the only source of information that we can use. Git commit messages can be used as an alternative source of information (and it can even be considered a canonical one since it's closely tied to the history of the project itself). As such, it can be argued that it does improve maintainability, especially for large-scale projects with millions of commits. Project developers and maintainers would need to know why a commit is there when they are bisecting the root cause of a bug.
I agree with this. Both of them are sources of information and yet they serve slightly different purposes. However...
This is again a deficiency of the tools during the time, and not necessarily of the commit messages themselves. And I would also believe that by now, there is an abundance of tools to search through Git commit messages, which is great!
Commit messages are used to explain the rationale behind why a change was made. While adding tests can be useful to prevent regressions or to indicate expected behavior, the tests themselves might not be sufficient in understanding the full context, reasoning, and history behind the change.