Replies: 5 comments 3 replies
-
Thanks for sharing! And I can see how this is confusing. I know this has been discussed more than once but my skills combined with GitHub's search only makes me find #4255. I think it's worth mentioning that you can install I don't think we should change this behavior because like stated in the linked issue we must be able to merge changes and fixes to the documentation for released features without having to draft a new release of The only actual improvement I can see is to just clarify this in the docs. We could have a clear statement at the top of https://golangci-lint.run/usage/configuration/ explaining this behavior. Do you think that would've helped your situation here? Regarding the release cadency I can agree, I think the current situation is that releases requires a bit of manual work and there's more or less only one person who can and is handling everything with the releases. I also want to say that we've discussed pretty recently to replace the current documentation system because frankly it's not great and depending on what path we take improving things like this might be doable. |
Beta Was this translation helpful? Give feedback.
-
To avoid confusion about whether a PR is released or not, I added milestones to all the PRs since the beginning of golangci-lint. |
Beta Was this translation helpful? Give feedback.
-
I recommend using the JSON schema to validate your configuration. The JSON schema is only updated after a release, so it's something stable and it can help you find if an option is supported or not. I'm currently working on several improvements around JSON schema. |
Beta Was this translation helpful? Give feedback.
-
I would add some context: golangci-lint is not a product owned by a company, it's maintained by volunteers in their free time. And to share my thoughts, I hope that at some point, we will be able to get money for our work. |
Beta Was this translation helpful? Give feedback.
-
Improvements we've made since this discussion started:
I think we addressed the majority of your feedback. I hope, all those efforts, will improve the experience for new users. |
Beta Was this translation helpful? Give feedback.
-
Hi there! 👋
I'm migrating my
revive
config to usegolangci-lint
, and the project looks great so far!Coming from
revive
, I had to migrate my config. It makes pretty heavy use of theexclude
option, and I was happy to see it in the live documentation!But… It doesn't work.
And because I just spent an hour figuring out why, I figured I'd share my journey with you.
Please keep in mind that I don't mean this post as a criticism of the project. I just saw an opportunity for a discussion, and I'd love to hear your thoughts 😄
Just to get it out of the way: I have no experience with
golangci-lint
.Users tend to blame themselves, and I'm no different: My first hunch was that I must have migrated my
revive
config wrong. After all,revive
accepts a toml config file in which some options are lowercased and some are Title-cased, and I had to manually convert the config to the yaml format required by thelinters-config
option, where all keys seem to use the kebab-case style. This difference is neither addressed explicitly in thegolangci-lint
documentation on configuring therevive
linter, nor inrevive
's own brief mention of integrating withgolangci-lint
. I eventually decided that I'd done it right, though.I then triple-checked that I was using the latest released version of
golangci-lint
(I was), the version ofgo
reported bygolangci-lint version
(I was), andrevive
(I was – and I later realised that my localrevive
install does not matter).Confident that my local setup and configuration were both correct, I started Googling, and found my way to the PR that recently added the
exclude
option: #4365. At the time of writing, the PR was merged to master 3 weeks ago. Yay! 🎉Just below the "merged" message in the PR's "Conversation" tab, GitHub had helpfully added a "mention" from a different repo (
go-tpm
, which I'm also not familiar with), whose wording seems to strongly indicate that they're upgrading to the latest released version ofgolangci-lint
(1.56.2) so that they could use the newexclude
option.Back to my config, then. To give you an idea of how I was feeling, here are a few of my ideas:
1. Does
golangci-lint
's yaml config wants me to provide a regex instead of globs?2. Did the pull request ONLY implement the
TEST
token, and not the glob syntax I was using inrevive.toml
?3. Is the wildcard syntax different – do I need to use something like
*
instead of.*
or**
?4. Is this yaml weirdness? (As a Norwegian, I've definitely been burned by the fact that the literal
NO
is interpreted asfalse
).4.1. Is yaml weird about special tokens like
*
so I have to quote them?4.2. Do I need to use single or double quotes?
4.3. Is there a difference in which list syntax I use?
Alas, nothing seemed to help.
Eventually, it occurred to me to actually follow the "mention" from
go-tpm
posted to the PR's "Conversation" page. That PR's description made the problem completely obvious:The new
exclude
option just hasn't been released yet.Now, almost none of this is your fault. My lack of experience is on me, I guess, and you can't really control the "mentions" that GitHub posts automatically to your PR and issue conversations. I also don't really expect you to maintain migration guides from every single linter's native configuration, nor do I expect you to try and expand the linters' own documentation on the integration. I also can't blame the
go-tpm
project for mentioning the PR in the way that they did – I would likely have done the same thing.I do, however, find it very confusing that the live documentation on the website mentions unreleased features.
I guess I was just really unlucky to stumble upon this particular feature that was added so recently during my very first encounter with the project, but I do see two pretty standard approaches to mitigating this issue. (I'm sure you're familiar with both, but I'll hash it out so we're all on the same page.)
First, versioned documentation. For example, Grafana has this thing on every single documentation page:
This would have immediately solved the problem I had today, since the
exclude
option would simply not have shown up in the documentation.On the other hand, versioning the entire documentation would likely require quite a lot of implementation work for little actual value. It's also hard to get just right: For example, switching to another version of the Grafana documentation consistently takes you back to the main landing page for the product you were looking at, even if the specific page you were on exists in the version you switched to.
A simpler option might be to just… release more frequently.
To be perfectly honest, I was quite surprised to find that a PR merged several weeks ago was yet to be released in an active project like this one. Given that the feature is also mentioned in the documentation, with no mention of the version in which it was added, I don't think I really stood much of a chance.
I tried looking around the repo and documentation to see if there's a consistent release cycle, but I couldn't find anything.
Looking at the Releases page, both the release dates and content of each release – both in terms of number of commits and size of the changes – seem to be pretty inconsistent. For example, there were no releases for over 2 months between November 3 and February 7.
I share my story as a starting point for a broader discussion about release management.
As I see it, there are two points of possible improvement:
I'd love to hear your thoughts on the matter:
Thanks again for a really cool project – I can't wait to get up and running!
Beta Was this translation helpful? Give feedback.
All reactions