conventionalcommits.org
conventionalcommits.org copied to clipboard
conventional-commits
should "feature" be alias for "feat"
A few folks have pointed out that "feat" can be confusing, is adding ambiguity worth saving three characters?
CC: @jskeet, and @bshaffer, who brought this up.
For me it's more about how obvious it is for those who don't have English as a first language. Abbreviations can add a friction with very little benefit.
I'd also say that there can be a perception of professionalism associated with not abbreviating. For example, I wouldn't expect professional documentation to say "When u do X" instead of "When you do X" - even when it's clear, published artifacts can benefit from things like this. (For that reason, I'd also capitalize Feature personally, as well as the title of the feature itself.)
@damianopetrungaro this suggestion was also brought up by my colleague @bshaffer, who felt the abbreviation can come across as unprofessional.
It doesn't bother me personally, but I don't think it's a bad idea to consider adding support for feature: to the spec/parsers; since a few folks have brought it up.
@JeanMertz, have any opinions?
I don’t mind if it was an alias. I personally wouldn’t use it, as I also care about adhering to the maximum title length, which is already difficult sometimes with both a type and a scope in a title.
Note that “docs” is also an abbreviation, should we also add the alias “documentation”? Although to be fair, it seems to me that “docs” is more common in usage than “feat”.
In the case of the parser I wrote, there is no list of allowed type names, as long as it’s a single word, it’s fine.
So what would the idea be here? Using “feature” as the default in the documentation, adding it to a list of example types, or adding an extra FAQ item?
I’m fine with all three, although I’m less enthusiastic about the first option, as I think it makes sense to stay close to what’s already out there, and being promoted by other projects such as Angular.js.
@bcoe, sure, worth nothing adding it :) Or at least it should be hinted somehwere.
Vote up to support the "feature" type as well. The "feat" confuse me for the first time because there is no naming rule here. Why don't we use abbreviation for Breaking-Change but feature ?. If we decide to go with abbreviation, we should use abbreviation for all type (say 3 characters code) Otherwise, use a full English word as we are introducing "human readable meaning to commit messages".
@hung-doan: abbreviation for Breaking-Change but feature ?.
I guess that's why we introduced ! thing... that I still don't like it's place.
If there's this demand we can support feat and feature.
I personally don't see a big use case for it, but I am open to discuss it :)
I don't like the idea of having more than one way to indicate something is a feature. In fact, I'd say that I don't like the idea of having more than one way to specify any given Conventional Commits type.
Given that it is a breaking change, and a bunch of tooling in the ecosystem will have to be updated to support the alternate, I think the bar for justifying the breakage has to be pretty high. That it's an abbrevation doesn't seem to be reason enough (nobody is complaining about other abbreviations, like "docs" and "perf", for example). And as far as confusion, who really is confusing "feat" with the dictionary word of the same name? You might even say that it is a cute that a feature is a play on "an act or product of skill, endurance, or ingenuity". 🤔
Are we losing sight of the fact that the purpose of Conventional Commits is to structure commit messages with human and machine readable information? Having synonyms only makes the format harder for machines to read. And "feat" is described within the first few sentences of the spec — is there really any human out there who is having trouble reading it within 15 seconds of learning that Conventional Commits is a thing?
On a more wide scenario replying to @jskeet it is all about context. In each context, a specific word may have its own meaning and even a 1 letter word may have a strong meaning.
A concrete example the Go language where is really common to use a 1 char letter for variables
Given the code below code, if you see c what may it be representing:
package Customer
struct Customer {
}
The same it is for me about Conventional Commits, a convention created for a tech-related world (where people are always talking about bugs and features) based on SemMer (which has "feature", "fix" and "breaking change" all over the place).
I totally get the point you folks are moving but for me is really hard to make the ROI clear about that, all the tooling are based on that it will break and may never be supporting feature over feat.
We have ~7 people reporting it as something we may improve where there are ~2000 people that read the convention.
And, on top of that, ConventionalCommit is already supporting custom types, so nothing is blocking the usage of feature where is needed (thinking about particular domains).
I do not wanna sound arrogant or whatever I am only trying to be convinced by your opinion but it's hard :)
On a more wide scenario replying to @jskeet it is all about context.
Absolutely. And the benefit of "feature" is that you don't need any additional context in order to understand it. Anyone reading a commit line starting with "feature" is likely to know what it means even if they have never heard of Conventional Commits. I view that as a good thing. Yes, anyone who decides to read the Conventional Commits spec will understand it quickly - but why require that, when allowing the synonym makes it immediately meaningful to everyone?
I suspect more people will read commit messages that have been written as Conventional Commits than the number of people who've read the spec. I think it's worth thinking about those "read-only, uninterested in the spec" folks.
We have ~7 people reporting it as something we may improve where there are ~2000 people that read the convention.
I don't think you should assume that all 1993 of the others would be against the change though. I don't think those numbers give enough weight for or against the change. If there'd been a large number of people who had seen this proposal and given it a negative reaction, that would be a different matter.
I totally get the point you folks are moving but for me is really hard to make the ROI clear about that, all the tooling are based on that it will break and may never be supporting feature over feat.
That implies that you really feel the spec is already at 1.0.0, despite being advertised as 1.0.0-beta04 - if you're basically saying there can't be any breaking changes now, because tools are already locked into the current spec. That would make me sad - but I'd suggest this should at least be made clear, so that no-one suggests any further breaking changes.
I still fundamentally believe that "feature"1is more immediately readable than "feat", but I'll readily admit that I have a relatively minor interest in Conventional Commits compared with other commentators here. I view it as a missed pre-1.0 opportunity, but if the bigger players are adamantly against it, so be it.
1 Or preferably "Feature" - I'm a big believer in making code comments commit messages read like regular English from a book, with punctuation and capital letters. I'm glad that conventional commits are explicitly case-insensitive other than for breaking changes.
you're basically saying there can't be any breaking changes now, because tools are already locked into the current spec
The spec isn't 1.0 final yet, so obviously it's not correct to say that there literally "can't" be any breaking changes. But I honestly think that that's a technicality of semver which is distracting us from something really important. Even if it were 1.0 final, it still wouldn't be correct to say you "can't" make breaking changes, because of course you could: just say, "let's make the change and call it 2.0".
The question isn't "can" we make a breaking change, but "should" we make them? Like I said in my previous comment, I think that for a project like this, "the bar for justifying the breakage has to be pretty high". I'd even say, extremely high.
Why? Because this project is more than just a specification document: it's embedded in an ecosystem of related tooling, it's embodied in the behavior of developers, encoded in their contributing guidelines and other documentation, and exists in a (so far) consistent set of countless commits spread across hundreds of projects that all use the "feat:" type in their immutable histories. I think all that adds up to an unusually strong basis for desiring to preserve backwards compatibility. I'd say that in an ideal world, there'll never be a version 2.0.0 — and those same reasons are why I'd hope we don't see any breaking changes even now, before 1.0.0 final.
There are two other concerns I'd add about moving from "feat" to "feature" or "Feature" that I don't think I've seen mentioned on this issue, although they don't weigh as heavily on my mind as the concern about tooling compatibility:
- Is that it is inconsistent to make this argument for "feat" but not for the other types that are mentioned in the docs (eg. "perf", "docs").
- Switching to longer labels is going to encumber interoperation with tooling or communities that require commit messages to stay under a hard length limit (the Git project's own guidelines specify a limit of 50 characters, and many other tools and projects have adopted similar guidelines) — advocating for longer types will mean that either people chose not to adopt Conventional Commits because it clashes too much with their length limits, or they will adopt it but then end up writing rubbish commit subject lines because it's harder for them to encode relevant information without breaking the limit.
Regarding the consistency of "feat", "perf" and "docs" - I'd say that "perf" and "docs" are very, very widely used abbreviations within developer communities. I can't recall ever seeing "feat" as an abbreviation for "feature" before Conventional Commits. That's not to say it's not out there, but I believe it's massively less widely used than "perf" and "docs".
Regarding line lengths: point noted, although that's an argument in favour of "BREAKING" instead of "BREAKING CHANGE" as well.
Note that adding an alternative of "Feature" is a breaking change for tooling, but it does not affect the backward compatibility of the "countless commits" mentioned. I'm not suggesting we should remove support for "feat", and those committers who still want to use it could do so. I'd just like to be able to use a more immediately understandable (IMO) word and expect it to be supported by tooling that supports a 1.0.0 of the spec, when such a version is published.
OT: Actually the v 1.0 has been released a while ago, probably one of the lastest commits removed it from the config entry 😂 SLO to a new level
Oh, well if 1.0 has already shipped, it's too late. That makes me sad, but I'm not sure I was going to convince anyone anyway.
(I filed the issue as if I got confused by the lack of 1.0.0 on the web site, others might too.)
I do really like your argument @jskeet but still not fully convinced. And anyway nothing will block us to release a v.2.0.0 is the community thinks it makes sense!
I never meant to. I meant that the number of people asking for clarification is really low (~0.4% or sth like that? I did the math in mind so I am not sure about it)
I don't think you should assume that all 1993 of the others would be against the change though
This is probably where we do disagree, I think the context for feat is already the one who is interested in it.
Absolutely. And the benefit of "feature" is that you don't need any additional context in order to understand it.
@damianopetrungaro @jskeet for an additive change like accepting "feature", I agree that we could add this in v1.1.0 of the specification, and should.
The only reason we haven't is there's a long standing PR that removed support for feat: rather than adding the new option feature:, I suggest we politely close this, and move forward with the decision in this thread.
@jskeet
Regarding line lengths: point noted, although that's an argument in favour of "BREAKING" instead of "BREAKING CHANGE" as well.
No it is not.
- "BREAKING CHANGE" appears in the commit footer, which can occupy as many lines as you want. Its size is irrelevant to any subject line length limits.
- Even if the length of "BREAKING CHANGE" were a problem, I'd still be saying we shouldn't make breaking changes lightly, and that includes not changing "BREAKING CHANGE" to "BREAKING".
- In the case of "BREAKING CHANGE", we already have an alternative, width-friendly way of indicating a breaking change ("!" after type(scope), before the colon).
@damianopetrungaro
And anyway nothing will block us to release a v.2.0.0 is the community thinks it makes sense!
Nothing, except for the desire to shield the ecosystem from the pains of making a breaking change. As I said before: just because you can, doesn't mean you should. There are plenty examples of software projects that live with "suboptimal" decisions for long periods, in the name of backwards compatibility — and often, the biggest ecosystems sprout up around those projects precisely because of their emphasis on avoiding breaking changes (textbook example: Windows). I think wanting to tweak the types despite the fact that they work well enough is an example of perfect being the enemy of the good: we're focusing on the benefits of getting the words "just right", and ignoring the costs of the externalities that come with making breaking changes.
Point taken about the BREAKING CHANGE - my mistake, sorry about that.
In terms of making breaking changes - it would be a matter of "All existing tools support Conventional Commits 1.0.0. Repository X uses Conventional Commits 1.1.0, so will only work with tools supporting that." That sort of "depending on newer versions" is certainly common within languages, of course - we don't say that languages should never change because there are compilers that wouldn't work with the newer code. Again, that's a matter of tools catching up over time. But I may have missed subtleties around what would need to support "Feature" beyond the existing tools. (Do we have a reasonably complete list of tools which parse Conventional Commits? That would make things a bit easier to reason about.) A proposal of removing the support for "feat" would be massively breaking, of course - but that's a different matter.
One aspect of living with suboptimal decisions is that anything done to correct the decision is best done as early as possible, because pain increases over time. I heard anecdotally that the "suboptimal" nature of Make using tabs was discovered quite early - but the author protested that there were dozens of Makefiles that would need to be changed. And so now there are millions of Makefiles that have to live with that suboptimal decision. There's a balance to be considered - which involves finger-in-the-air guesswork in terms of the long-term popularity, of course.
Let me give you a concrete example of what this change would mean for me (just one data point).
At my job we have about a dozen repos currently following Conventional Commits and using the Semantic Pull Requests bot; if you make this change:
- The conventional-commit-types package's list of types will need to be updated and a release made.
- The bot will need to update its dependency on that package, and a new version of the bot will need to be deployed.
- Contributing guidelines that exist in most of those repos will need to be updated to reflect the new alias.
- Once/if people start using the new type, all existing contributors will have to deal with the inconsistency with previous practice and the uncertainty about which type they should use; I'll have to answer questions and add recommendations.
- I also have a changelog generator that will have to be taught about the new type.
If want to avoid that update, I can instead configure the bot to only accept "feat", but that isn't much better because it will require me to update all the repos. And all those repos would now require a declaration that they "follow Conventional Commits vA.B.C spec", or "vA.B.C except that we continue to use only feat to indicate features". Well-intentioned participants will ask questioins about what is holding us back from moving to vA.B.C+1.
Now multiple this by dozens of tools and hundreds of projects, where similar things will be required. To me, this looks like a case of the "juice not being worth the squeeze".
I suspect that no-one's convincing anyone to change their mind about whether this is worth doing or not, so I'm going to bow out of the conversation at this point. I'm glad this was a good-natured discussion despite the large gap in opinions though - I've seen far more heated, negative discussions where contributors come from closer viewpoints to start with.
Let me jump here again.
Totally understand why some may want feature and Feature. Okay. But it definitely must not replace the current feat. The best approach would be to have a note (or just another point in the list, just after the point of feat) saying "hey, you still can use feature, Feature, FEaTu as long as it starts with feat and the parser inside your tooling support it", similar to @bcoe's in #204. I agree it can be closed and we can proceed with another.
The parse-commit-message (which is used in the mentioned Semantic PRs bot) is and will be able to support even this change, just because it checks for /feat/i or similar, and that's it. It seems it disappeared from the site, again.
But I'm totally against so-called "breaking changes" for the spec (I didn't agreed with releasing v1 either, but...), and any other wording that replaces or removes the feat. It's used enough, and the JavaScript community alone is huge enough.
Totally agree with both @jskeet and @wincent.
We can stop this philosophical debating, add a simple bullet to the list, release v1.0.1 and call it a day.
2. The type `feat` MUST be used when a commit adds a new feature to your application or library.
+3. The type `feature` MAY be used as an alternative for the `feat` type and the same things MUST apply to it.
4. The type `fix` MUST be used when a commit represents a bug fix for your application.
Easy. And really, that's it. Both sides will be okay, plus the tooling and the parsers.
Easy. And really, that's it. Both sides will be okay, plus the tooling and the parsers.
I think you might be overstating the ease here. Sure, parse-commit-message can (already) extract an arbitrary type from a commit subject line, the conventional-commit-types package can be updated and released, the Semantic PR bot can pull in the new dependency and redeploy etc; but so will any other tools that have been built on the current spec. The trouble is that the word MAY makes it sound like support is optional, but it's really not: changing the spec means users get the option to use an alternative word, but tooling implementors have no choice at all — they'll all have to change in order to support that option.
Funnily enough, I made a changelog generator that assumes the "standard types", but already has support for gracefully accommodating common "mistakes", including "feature", so I won't have to update that tool even if this change goes in — I'm just speaking up on behalf of the other tool implementers out there we might not even know about, and whose tools will become broken as a result. (I imagine it's probably not limited to tools we know about in the JS ecosystem.)
True. But at the same time, I think that's why I intentionally or unintentionally added the last part "MUST follow" and "the same things MUST apply". Not good wording, definitely, but I think we get the idea. The idea is exactly what you're saying - we, somehow, should say it to both parties.
CC is in an interesting position. It's a spec for both the tool authors and for the regular users which is just writing commits.
<maybe-offtopic>
CC is in an interesting position. It's a spec for both the tool authors and for the regular users which is just writing commits.
Is it that different from a spec like ECMA-262? That's a spec for people to who write JS, and for people who make JS engines. (Obviously the scope and detail is a bit different, but I think it's actually pretty common for specs to address both tool-users and tool-makers.)
</maybe-offtopic>
also <maybe-offtopic>, but I think somewhat in line with @wincent's point.
✋ this thread has drilled home for me the fact that our approach to evolving this spec isn't working great at this point. Conventional commits now has a lot of stakeholders, which is awesome!, but it makes it hard to come to consensus in a thread like this.
I haven't figured out how to approach it yet, but I would like to move towards having a bit more governance on this project ... as a starting point, I think having a monthly meeting with a few interested parties would be a great start.
This would be a good venue to discuss contentious issues like this.