That must be what you mean.
891 karma · joined March 4, 2014
Maintained Code School 2012-2018.
Created https://shields.io
Maintainer of https://keepachangelog.com
Tending to https://indigene.app
That must be what you mean.
If you want Rails-specific benchmarks for Ruby commits I suggest the `discourse_` benchmarks that are running specific chunks of the open-source Discourse Rails app: https://rubybench.org/ruby/ruby/commits?result_type=discours...
I find that seeing the exact changes you're about to commit does lead to more detailed git commit messages, although the maximum length of most "properly" written commit message titles (50 characters) tends to hinder the quality of commit message titles as entries in a changelog. They're often very high level summaries of introduced changes and it's common for people to focus on the change at hand — not on its impact on end-users — when writing a commit.
Again, this all goes back to the intended audience for commit messages compared to change logs. If the end users of the projects you work on diligently read every commit in the project history, then I dare suggest you're in a rare and privileged situation. I don't expect end-users of most open source software to be satisfied with either the high-level nature of commit titles, or their minutia. This leads me to think that keepachangelog.com needs to gather more examples of the of changelogs I advocate for. It seems that a surprisingly small number of people have encountered them.
Rebasing and squashing commits to clean them up to be changelog-worthy does not solve the 50-character issue with conventional commit titles I mentioned above. It also doesn't solve for situations with collaborative pull requests or branches. That is, unless there's a clear process for squashing and rebasing being done by a single person at the very end of the project. I think it's more realistic to expect a single file changelog to be regularly updated (through an Unrealeased section) as changesets are being introduced prior to a release and to eventually update this same single file when the group of changesets is about to be released under a new dated version release.
An open source project like Rails has different components all developed within a single repository although they're packaged up independently for release. Each different component has a root level changelog that documents its changes and there isn't a centralized changelog for all of Rails. In some ways it's problematic because you can't see a merged changelog for all core components of Rails but it's also useful when you're only worried about changes to the ORM component since you'll only see changes pertaining to it within its own changelog.
In my mind a changelog is a root-level concern for a single piece of software, regardless of how many isolated components it's composed of. Basic tooling should be able to centralize each changelog (as long as versions are synchronized, but that's another issue) and ideally you should be able to filter by sub-component.
This is definitely not something we've created any guidelines for yet. So if you have any thoughts on the matter, feel free to suggest them: https://github.com/olivierlacan/keep-a-changelog/issues
It's strange to me that anyone would consider especially open source software as something so good and obviously beneficial that the archeology you mention would be a fact of life for end-users. It betrays a misconception about the value of software in a vacuum: without tests, code documentation, interface design, and change documentation (a changelog).
The best algorithm is useless without proper tests verifying how it functions against real input; it's obscure without good documentation highlighting its quirks and design decisions, and if it evolves without clear explanations within a changelog then the changes in its behavior will remain mysteries to end-users as long as they don't go deep inside the code to understand how it worked before and how it works now.
I've had to do this kind of programmer-archeology on numerous production dependencies (transitive or otherwise) in the past and the resulting frustration is very much the fuel that motivated me to make keepachangelog.com
Generally people edit changelogs after pull requests have been merged or as part of the pull requests themselves. It's far easier to figure out merge conflicts if and when other versions appended to the changelog simultaneously because all changelog entries are dated (or at least they should be) or at least versioned and contain plain text.
That said I agree that we should probably spend some time detailing common processes for editing and appending to a changelog in situations with concurrent branches being developed.
There's surely personal bias at play, but I'm far more concerned with people keeping a changelog in the first place to worry too much about how exactly they do it. If Org-mode is what they go with, fine, but what we're facing right now is hordes of open source projects that people end up taking on as direct or transitive dependencies and which do not document their evolution in any meaningful way.
I've covered these recent changes in a post that didn't quite make it to the front page recently: http://olivierlacan.com/posts/logging-changes-all-over-the-w...
I'd agree this is an area we need to clarify for version 0.4.0 and forward.
It's relevant because it's from Mind of Chef season 1 with David Chang.
It's very bad.
Also had VOIP phone to contact députés. Many were and avoided questions or said they would toe the party line. Evidence here: https://pad.lqdn.fr/p/PJLdeputes
No being a jerk, seriously I'd love help with the copy. :-)
I'll try to make it... pop out more?
I'm so sorry.
Thank you :-)
The GNU conventions for change logs and news files are not exactly self-explanatory (semantics matter), which probably explains how rarely they have been followed to the letter. I have no data to back this up, but I doubt people who use and depend on open source software would discard this claim.
Now it's interesting to see this initiative mocked as a "not invented here syndrome" (Moru's comment). I did not define these guidelines, I merely gathered them from existing open source projects which were exceptionally good at communicating changes. The poor examples and the frustration that fueled this project came from projects that did the opposite:
- inconsistent (file naming, change categories, etc.)
- dumping git diffs which provides absolutely no value to end-users (OSS software users who need to regularly update their dependencies)
- littered with references to irrelevant issue trackers (which did not provide clarifications regarding the changes)
- poorly written with the wrong audience in mind (fellow project collaborators who have context vs. external users who don't)
- not given any dates or given confusing regionally-flavored dates
- and the crux of my frustration: not singling out and emphasizing API breaking changes and deprecations
Anyway, please don't dismiss this project because a convention exist in one community. This convention is not being followed for now and I would really appreciate your help in improving the status quo: https://github.com/olivierlacan/keep-a-changelog/issues
Thanks.
The story behind it is here: http://www.adweek.com/adfreak/story-behind-water-inspiring-v...
A commit message should be formatted like an email to your past self, or your future collaborators. It should have a very descriptive and concise title (the first line of the message) written in the present tense and after a line break you should (when necessary) write an email style explanation of the reasoning behind the commit.
If you fixed something, is there context that should be useful for someone discovering this commit in a vacuum. Are there any related commits? If you added something, why? There is so much useful information that can be encoded in a commit message and discovered when someone does a `git blame` for example.
Caleb Thompson wrote a nice concise post on this: http://robots.thoughtbot.com/5-useful-tips-for-a-better-comm...
1) That's true. Although sending beginners into a less/vi commit interface that is even more bewildering than the basic shell is not a good way to concisely introduce people to a new tool. The hardest part of teaching is what you chose not to teach. 2) We purposefully used the GUI file browser (My Octocat Repository) at the bottom to avoid having to systematically do `git status` in order to check the state of the repo.
We learned how to solder stuff on circuit boards (yes, soldering irons, yes some kids burned themselves, big whoop), how to use glue guns (again, I burned myself a bit, nothing serious) to put components together when assembling basic machines.
Can you even imagine the kind of amazing physical computing kids could be doing with Arduino and Raspberry Pi these days. HTML & CSS seem like a no brainer. I learned those in a "Technology" (in regular class hours) during my last year of middle school (again, in Paris).
If it weren't for a sympathetic instructor who told us to do make a website using FrontPage on anything we were passionate about (RTS for me at the time) I'm not sure I'd be a web developer today. I think these kinds of a programs are a great first steps to get kids excited about the web and/or basic languages before middle school and high school classes (in our out of class schedule) provide more thorough or complex introductions to programming proper.
Thanks a lot for the feedback. :-)
> You can also type `git add -A .` where the dot stands for the current directory, so everything in and beneath it is added. The `-A` ensures even file deletions are included.