The live documentation does not always match the latest released version

[theneva]

Hi there! 👋

I'm migrating my revive config to use golangci-lint, and the project looks great so far!

Coming from revive, I had to migrate my config. It makes pretty heavy use of the exclude 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 the linters-config option, where all keys seem to use the kebab-case style. This difference is neither addressed explicitly in the golangci-lint documentation on configuring the revive linter, nor in revive's own brief mention of integrating with golangci-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 of go reported by golangci-lint version (I was), and revive (I was – and I later realised that my local revive 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 of golangci-lint (1.56.2) so that they could use the new exclude 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 in revive.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 as false).
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:

1. The release cycle seems unpredictable. As a new user, I have no idea if the feature I'd like to use will be released in the next few days, or if I have to wait several months.
2. The documentation is out of sync with the latest release. (This can be framed as a direct consequence of the first point).

I'd love to hear your thoughts on the matter:

1. Do you, perhaps, already have something in the works to address it?
2. Do you see ways to improve the current experience other than the two I outlined?

Thanks again for a really cool project – I can't wait to get up and running!

[bombsimon]

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 golangci-lint from master and if you do the documentation makes sense. However, I can see how it's confusing that the latest stable release isn't what's being reflected.

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 golangci-lint.

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.

[ldez]

To avoid confusion about whether a PR is released or not, I added milestones to all the PRs since the beginning of golangci-lint.
The unreleased PRs use the milestone next.
When the release happens I will rename this milestone next to v1.57 and create a new milestone next.

[theneva]

Wow, thanks! That should help a lot 😄

[ldez]

I recommend using the JSON schema to validate your configuration.
The majority of IDE or text editors embed those schemas.

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.

[theneva]

Oh, you're right! That's a good note – I'm using IntelliJ with the Go Linter plugin, so it apparently already worked in my IDE. I was just really liable to trust my own config since I didn't have a working starting point. I'm looking forward to seeing the schema improvements as well! 🎉

[ldez]

I would add some context: golangci-lint is not a product owned by a company, it's maintained by volunteers in their free time.
So it's not possible to have the same expectations as a commercial product or an open-source project by a company, even if we try to do our best to provide high-quality software and high-quality documentation.

And to share my thoughts, I hope that at some point, we will be able to get money for our work.
A lot of people and companies use golangci-lint, it seems possible to do that if at least a few people/companies think of us.

[theneva]

Thank you for sharing!

I think this point is both interesting and important bring up. It can be really hard to tell the projects that have financial backing from the ones that rely exclusively on free labour, and this project has virtually no tells that it's the latter.

Both the repo and the documentation look clean and polished, there's a lot of activity, and the CI pipeline looks convincing – not to mention that the repo has over 14k stars, which is… a lot.

I also have to admit that I skimmed right past the "This project exists thanks to all the people who contribute" part of the readme, and interpreted the "Core Team" section as a group of maintainers who receive some kind of compensation for your work on the project.

This is not to say that I think you should change the readme, or anything else – I'm just giving you my perspective so you can see where my original post came from.

I'd like to reiterate that my post was not at all meant as a criticism of this project. I just wanted to share my "onboarding" experience as a new user trying to integrate one of the most popular linters, because I thought this perspective might be valuable to you.

In particular, I pointed to Grafana not as a comparison, but rather as a well-known reference on versioned documentation, and I pointed out my annoyance with their implementation to say that I think it takes a lot of work to get such a solution just right. All this was mainly intended to reinforce my main point – that releasing more frequently is probably a better option than trying to "fix" the documentation with code 😄

I understand now that releasing more frequently is not really feasible as a quick fix, which is completely fair.

The reliance on free labour is definitely the bane of many great projects… Then again, the same can be said about being adopted by a big corporation 😅

I'm afraid I'm not in a position to offer you anything other than perspectives and suggestions. I do have one suggestion, though, in case you're interested: Uber's guide to writing Go explicitly recommends golangci-lint, and does not name any alternatives. I think they provide a lot of good stuff for the Go community, and they're clearly already invested in this project. Perhaps they would be interested in backing the project if you reached out to them?

[ldez]

Improvements we've made since this discussion started:

• Milestones has been added to all the PRs since the beginning of golangci-lint.
• The unreleased PRs use the milestone next.
• The documentation of linters only provides information about the current stable version.
• The documentation pages have been reorganized to be easier for new users.
• The JSON schema is managed inside the project repository and provides information only about the current stable version.
• There is command config verify to check the configuration against the JSON Schema related to the version of the binary.
• The changelog page content has been improved.

I think we addressed the majority of your feedback.

I hope, all those efforts, will improve the experience for new users.

[theneva]

Oh wow, this is fantastic. I almost feel bad for causing you so much non-product work, but I really do believe that all these improvements will make the project more approachable and easier to adopt. Thank you so much for both the changes and this update!