Docs for generating docs are 404

[WhyNotHugo]

In this section: https://cobra.dev/#generating-documentation-for-your-command

The link to man page is a 404.

[umarcor]

Duplicate of #1243.

[WhyNotHugo]

Oh, I didn't notice that issue, but it seems to have been closed as stale...?

Is cobra no longer maintained?

[umarcor]

Oh, I didn't notice that issue, but it seems to have been closed as stale...?

In fact, it was closed by the OP almost a year after it was labeled as stale: #1243 (comment)
The most up to date reference about what's going on is #1245. Precisely, see #1245 (comment) and #1245 (comment).
TL;DR: #1428 is ready to merge, which would provide the foundation for adding a Jekyll/Hugo site to cobra.dev using the (markdown) sources of this repo.

Is cobra no longer maintained?

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:

• Sep 2019: Maintenance/governance of this project #959
• Feb 2020: v1.1.0rc #1028
• Oct 2020: Reorganise the cobra library and the CLI as siblings #1240
• Jul 2021: Projects #1454
• Sep 2021: Fall release 🍁 - 2021 #1496
• Nov 2021: 🍁 Fall 2021 - release candidate #1525

I believe the critical content is:

#1240 (comment)
We've not yet talked about it publicly much, but there's intent to develop a quickstart tool for Go and Cobra's an obvious case to build it around since there's already a prototype here. I think it's best to leave things as they are for now with hopes that the new go quickstart (or whatever we end up calling it) will displace the cobra tool entirely anyway. Let's circle back on this in a couple months when we've made more progress towards that tool. Right now it's mostly an idea without a proposal.

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 go quickstart displacing cobra?

[WhyNotHugo]

Thanks for the very detailed response. I assume that go quickstart would replace the cli aspect of cobra, but not the library aspect of it, right?

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 SEE ALSO). I guess it's best to keep this in an external package for now -- I don't think the timing is quite right to try and upstream this.

[spf13]

@umarcor I think there is confusion here.

As @WhyNotHugo said, go quickstart would only replace the cli aspect of cobra.. as in the cobra generation tool. As it stands right now go quickstart is still only an idea without a roadmap and the team is very busy with generics, so I don't think this will happen anytime soon.

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.

[WhyNotHugo]

Right, so go quickstart is similar to go init; it's a boot-strapper for projects, so won't replace cobra, but complement it.

If you haven't, do take a look at the usability of npm init ...; it's a really neat reference.

[umarcor]

@spf13, thanks a lot for clarifying. There was confusion, indeed.

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.

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:

• Apart from the internal/synthetic tets, have a testsuite directory with Minimal (non) Working Examples (MWE). At the same time, require issues (either bugs or features) to provide an executable (or legit failing) MWE. Synthetic tests are written by developers/maintainers and reflect how the tool is expected to be used, while MWEs reflect how is the tool used in practice.
  • Refactor the internal tests to make them more robust from a purely technical point of view. At the moment we are comparing strings to detect errors. I believe it is desirable to first have a bunch of MWEs before heavily refactoring the testing sources, so that we have a blind check.
• Have the documentation automatically updated and generated from the markdown sources. This is already being discussed, as referenced above.
  • The documentation might (should) include references to MWEs showcasing non-usual solutions.

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'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.

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.
Moreover, there are no de facto labeling practices which might alleviate the lack of explicit documentation. Actually, there is the "stale bot", which is partially offensive to contributors.

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:

• https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role
• https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-a-user-account-repository#collaborator-access-for-a-repository-owned-by-a-user-account

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).

[jpmcb]

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

[spf13]

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