-
Notifications
You must be signed in to change notification settings - Fork 2.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs for generating docs are 404 #1527
Comments
Duplicate of #1243. |
Oh, I didn't notice that issue, but it seems to have been closed as stale...? Is cobra no longer maintained? |
In fact, it was closed by the OP almost a year after it was labeled as stale: #1243 (comment)
That's not an easy question. Strictly, cobra is maintained, not abandoned. Several big companies depend on cobra, so it's very unlikely to be let die. In practice, it has been in extremely low maintenance mode for at least the last 2-3 years. Almost no new features are accepted and obvious fixes/enhancements take months to be reviewed and accepted. The notable exception is support for completions, which was accepted suprisingly fast, and many of the related PRs were initially picked fast enough. Still, it also fall in the months of delay. Overall, if you are willing to use cobra as-is, with all the advantages and the caveats, I recommend to use it. However, I would not expect any significant enhancement in the short or mid term. If you find a missing feature or a problem which you cannot work around, I suggest to have a look at more actively maintained alternatives. Previous paragraphs might sound harsh. Please, feel free to read through the context:
I believe the critical content is:
Since @spf13 is both the original author of cobra and the Product Lead of golang at Google, IMHO those statements might have demotivated co-maintainers from putting much time on cobra lately (apart from the obvious fact that they do have jobs and families). @spf13, is there any update with regard to the new |
Thanks for the very detailed response. I assume that I'll continue using cobra for the time anyway -- it suits my needs and its replacement is nowhere to be seen (plus, google has a habit of deprecating and retiring stuff and then never really completing a replacement for it either). I'm working on building man pages quite a bit more detailed than what cobra offers right now (e.g.: include subcommands in a single man page, adding sections, and additional entries to |
@umarcor I think there is confusion here. As @WhyNotHugo said, Cobra is among the most popular libraries in the entire Go ecosystem and is depended on by Go's largest projects & many huge enterprises including Google and Microsoft. Go.dev (which will soon be Go's official website) features Cobra in the use cases and the getting started section. With such a large adoption base and the initial goals largely reached, Cobra is more or less in maintenance mode. I think the project would benefit strongly from an additional maintainer or two who understands that maintenance mode means accepting well tested fixes, but not accepting additional features unless they serve a broad set of users and reduce complexity. I've spent a good amount of time and effort recruiting maintainers, and am grateful for all those who have contributed their time and talents to the project. Even with these efforts, I think it's clear that the project could benefit from additional maintainers. |
Right, so If you haven't, do take a look at the usability of |
@spf13, thanks a lot for clarifying. There was confusion, indeed.
As a complementary strategy, I believe we should improve both testing and documentation. Those are critical assets in a mature/stablished project to avoid rotting. I have a couple of ideas in this regard:
However, those two areas do need a rolling project. We cannot ask contributors/users to write MWEs or improve the documentation in-place, if we are then going to apparently ignore them for months. I know that's not literally true, but it's the perception. We are struggling to push a wheel with square edges, we really need to get them round. Note that moving faster does not mean less secure. We can still release a single "relevant" version a year, or twice a year, so that most critical users can bump steadily. Yet, we should integrate PRs faster and have "release candidates" broadly tested for weeks/months before tagging a new release. Currently, we are delaying merges and having so little time for testing/catching regressions, which is the opposite to what a mature project needs.
I believe the issue is not so much about the number of maintainers, but about the procedures which are not explicitly documented. As far as I am aware, there are no guidelines for "new maintainers" to understand how should they label issues, when is a PR ready to be merged, what is "agreement" or "non agreement" about adding/removing a feature... As a result, whoever is the last maintainer merging some PRs does then get flooded with comments/pings from lots of other PRs, many of which has no clue about. That's overwhelming for anyone, particularly because this is not the main project of any maintainer. GitHub does provide features to help with some of those "problems". If we used both labels and milestores, #1496 would not be required. That'd be a milestone, which would show the percentage of finished issues. Stupid but effective gamification. Moreover, several mature projects do have an explicit list of maintainers in the README/Docs, and frequently there is a reference about which areas they focus on. We might cross-reference that to specific labels. That'd allow users/contributors to avoid pinging maintainers who can actually not take care of those areas. It would also be useful for the project to understand what's the current state: which areas do need new maintainers. Unfortunately, roles for user repos in GitHub are pretty limited compared to organisations. Since we don't want to modify the cobra namespace, that means all potential co-maintainers (collaborators) need to have push access. Particularly, organisations can have "triagers" which can precisely help with organisation by setting labels and milestones, but they cannot push/merge. As far as I understand, that's not possible on user repos. See:
As a result, maintainer roles in this repo need to be enforced by humans. In this context, I would be happy to collaborate in the maintenance of CI and Documentation (not the documentation generation feature of the codebase, but the sources to be used in cobra.dev). Nevertheless, I would never merge a PR on my own. I believe it should be enforced that PRs are approved by two co-maintainers at least. If @marckhouzam joined in a similar effort, taking care of completions and maybe some other area, I think we might complement @jpmcb as the main merger (should he be happy in that role). |
This is a bit surprising to me, although, I agree that not much needs to be done or changed since the cobra library is so stable. And truthfully, I have been treating it as such; many of the fixes and PRs that get into releases are not net new features, but small, stable enhancements, project maintenance bits, security bumps, etc. In my opinion, if we want to treat Cobra as a more stable / maintenance project, I think we need to draft something up for the community, close existing PRs that include major feature adds, etc. But I won't be the one to make that call. Steve, I'd like if you could handle that, make the decision, and communicate it to the community.
@spf13 In all honesty, I think cobra is in severe need of an injection of maintainers, at least to handle the influx of issues and pull requests. Right now, I believe I am the only one merging PRs or active as a maintainer. And even then I can't commit much more than a few hours a week, if that. |
I'm supportive of all the proposals here.
Cobra is in maintenance mode in practice right now, but if we had more
maintainers and an agreed upon roadmap with semi-regular releases we could
entertain more feature development.. Though, to be honest, I'm not sure
what major features would benefit our users that would need to be in the
core framework... but I'm happy to have that discussion.
We can try to drum up more interest in Cobra maintenance and see what
additional support we can get. A ton of projects use Cobra, and
historically our big users have done a good job as maintainers.
…On Wed, Nov 17, 2021 at 4:32 PM John McBride ***@***.***> wrote:
Cobra is more or less in maintenance mode.
This is a bit surprising to me, although, I agree that not much *needs*
to be done or changed since the cobra library is so stable. And truthfully,
I have been treating it as such; many of the fixes and PRs that get into
releases are not net new features, but small, stable enhancements, project
maintenance bits, security bumps, etc.
In my opinion, if we want to treat Cobra as a more stable / maintenance
project, I think we need to draft something up for the community, close
existing PRs that include major feature adds, etc. But I won't be the one
to make that call. Steve, I'd like if you could handle that, make the
decision, and communicate it to the community.
I think it's clear that the project could benefit from additional
maintainers.
@spf13 <https://github.com/spf13> In all honesty, I think cobra is in
severe need of an injection of maintainers, at least to handle the influx
of issues and pull requests. Right now, I believe I am the only one merging
PRs or active as a maintainer. And even then I can't commit much more than
a few hours a week, if that.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1527 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AABKKZAOE5UZCPSZC4VRKJDUMQNQNANCNFSM5HQYNOPQ>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.
|
In this section: https://cobra.dev/#generating-documentation-for-your-command
The link to
man page
is a 404.The text was updated successfully, but these errors were encountered: