Guidelines needed for community PRs

[fekete-robert]

Hi, First of all, many thanks to everyone involved in maintaining this awesome project :)

I have a couple of questions that the contribution guide doesn't cover. Do you have any recommendations or best practices for the external contributions?

For example, PRs require two approvals, but when you open the PRs you cannot add reviewers, and as a result PRs often get stuck with only one approvals. Should we in such case request an additional review via mentions in the PR comments?

A similar case is when reviewers request changes, and it can take a long time until they cycle back to the PR - what is the best way to signal that it's ready for a re-review?

Don't get me wrong, I absolutely understand that everyone has many other things to do (and that the recent Bootsrap upgrade took a lot of effort and focus), therefore I don't want to be intrusive and nag others, so I'm somewhat reluctant to randomly mention maintainers to get their attention. But I could use some help in finding the least intrusive/annoying way to streamline the contribution process, so you don't have to review outdated/half-ready PRs - I think that would speed up the merge process of PRs that are ready.

Thanks!
Robert

[chalin]

Hey Robert! You raise good points. I dont' have a quick or simple answer, but I'll bring this up for discussion at our Steering Committee meeting and one of us will get back to you. Cheers, Patrice

[chalin]

Quick update: we discussed this topic during today's meeting, and will be continue at our next PSC meeting (in 2 weeks).

[fekete-robert]

Thanks a lot!

[deining]

Thanks Robert, I think it's worth having the discussion you started. I fully understand you: you have nine open pull requests into which you put a lot of time and energy. Others liked yours ideas (e.g. see the positive community feedback on your PR #1049). And then no reviewer is showing up, and your PRs got stuck (there is no real progress with your mentioned PR for more than one year(!)). I know how that feels. If someone eventually picks up your work, the first thing you have to do is to rebase your PR and to resolve merge conflicts. After such a long period, you are not into the topic any more, you have to re-familiarize with your own work, … To make a long story short, I fully agree with you that cycling times for PRs are ways too high and that the whole process needs to be standardizes and shortened. The question is how to achieve that, though. As Patrice mentioned already, there are now quick and simple answers, but nevertheless, I want to contribute with a few thoughts:

• First of all: you can only manage things if you measure them and know the metrics. I put some efforts into this and came up with these figures for the two daisy repos. In general, it's great to see that docsy attracts people and that the number of issues and pull requests in progress (WIP) is raising. The downside is that the approximate average cycling times (AACT) is raising, too. The figures in the linked pot are updated daily, so we can monitor how things are progressing in the future.
• Second: I fully understand and support that we focus on large tasks (like the bootstrap 5 upgrade). That shouldn't mean however, that low hanging fruits are not reviewed/neglected for a long period (as an example see Robert's PR Handle svg hero images in blocks/cover shortcode #1505). It's unfortunate to see such a small PR not being picked up. Any action -even the decision to reject the PR- is better than letting PR authors wait for a long time.
• Third: I like the idea to have and set milestones. We should make use of this function/tool a lot more than we do right now.
• Fourth: I would like to see a clear separation between code-related and documentation related changes. While I fully understand that code-related PRs need time to be discussed and implemented, it's hard to convey that documentation changes need so much time to get merged. As an example for what I mean, see Split Navigation and Search pages #1352, Documents the body_class parameter #1541 or User guide, deployment page: add section 'Deployment on GitHub Pages' #1435.
• And last, but not least: we do have both section for Issues and Discussions, but most requests come in as issues. I would like to see that the other way round: general support should be handled under discussions first. Once validated, we should encourage people to open new issues for their requests. This way, we could drop the number of issues, which is proliferating right now. What about putting an issue template in place that clearly indicates that new issues are meant for undoubted bugs, everything else should go into Discussions?

Just my two cents. WDYT?

[fekete-robert]

Hi @deining , many thanks for your detailed reply. I fully agree that running such a project is a balancing act between bigger project goals (like the bootstrap upgrade), fixing issues, and other tasks (like supporting users and reviewing contributions), all with limited resources.
That's why I think that streamlining the processes and somehow helping the maintainers focus on stuff that can actually be worked on would help, so they won't have to spend lot of time on finding which PR is up to date and ready for review, or which ones have already got a review. I'm not sure how best this could be done though, maybe by using labels and filters?

[chalin]

Hi @fekete-robert - I was away from this project for a couple of months for a number of reasons. Other PSC members have been very pressed for time this year, especially the second half.

I have some bandwidth this month for docsy -- I've just released 0.7.2 (which had been planned for August 🤷🏼‍♂️), and I plan on publishing at least one more release. I wanted to let you know that your questions and concerns are still on the PSC radar, and we’ve discussed them more than once. I’ve started drafting a preliminary response — though I can’t promise anything in terms of timing.

[fekete-robert]

Hi, no problem, and thanks a lot for the update :)

[chalin]

TL;DR - To begin addressing the concerns and questions raised in this discussion, we have released our Docsy Priorities for 2024. More actionable issues, and concrete guidelines as updates to CONTRIBUTING.md, are planned for the new year.

---

Robert: Firstly, thank you for your candid and tactful feedback. It is valuable in helping us identify and discuss needs and lacunas. Andreas: I'll address your pertinent points separately at a later time.

Secondly, I'd like to step back and offer some context and explanation for the lack of responsiveness that you mention — which I acknowledge. Due to circumstances beyond our control (in our day jobs), delays were worse in 2023, unfortunately. Also, simply put, the Docsy project is "understaffed". Like a small startup, steering committee (PSC) members fill all roles: governance, technical steering, maintainer, reviewer, developer, technical writer, dev ops, etc.

Consequently, essential work (such as the Bootstrap migration you mentioned) often consumes all available time and effort, leaving issues and PR without responses for extended periods. The number of enhancement requests and fixes far outweighs our capacity to fully assess and process them.

Note that delays impact all stakeholders, both "internal" and external. For example, I support CNCF project websites that use Docsy, and starting in 2022, I was responsible for migrating several of these projects to Google Analytics 4 (GA4). In July 2022, I opened Support Google Analytics 4 (GA4) and migration to GA4 #1096. This issue was closed only two weeks ago, 16 months later — GA4 support, which was way overdue, has finally been released (0.8.0)!

What is the "essential work" that I was referring to earlier? Defining and prioritizing work is one of the steering committee's main tasks, which it does regularly, though the PSC had not shared anything publicly yet. To address this, we've published Docsy Priorities for 2024. Please read through the post to familiarize yourself with the priorities set by the PSC. In summary, the focus for Docsy will be on stability and feature consolidation.

As mentioned in the priorities blog, consider Docsy on a feature diet. In 2024, we'll still be accepting features: we'd value community input, for example, in the form of a short list of the top 3-5 PR candidates for the next planned release. Create a discussion for that, or better yet, leave a comment on the next scheduled release's issue, such as Release 0.8.1 or 0.9.0 preparation.

Any help in support of Docsy's priorities for 2024 is most welcome! We'll make the priorities more concrete by creating supporting actionable issues as soon as possible, and revisit CONTRIBUTING.md guidelines. In the meantime, for a rough idea of what is planned for the subsequent releases, see Docsy's quarterly milestones.

Come to think of it, the Docsy project resembles a community kitchen more than a startup. We all chip in as volunteers in this space, doing our best to create something valuable and sustainable for everyone. Your understanding and support are appreciated. The PSC also greatly appreciates community feedback and contributions and does its best to integrate them. Let's continue to cook up something great together, one small step at a time!

[chalin]

Since the following issue already exists:

• Add more info on how to contribute to Docsy #191

I'll use it to track the updates to CONTRIBUTING.md.

[chalin]

@deining writes:

• we do have both section for Issues and Discussions, but most requests come in as issues. I would like to see that the other way round: general support should be handled under discussions first. Once validated, we should encourage people to open new issues for their requests. This way, we could drop the number of issues, which is proliferating right now. What about putting an issue template in place that clearly indicates that new issues are meant for undoubted bugs, everything else should go into Discussions?

Green light for implementing this (it was discussed during the Jan 11 PSC meeting)! Is this something you could work on and/or open an issue so that we can track your suggestions @deining? /cc @emckean

[deining]

Is this something you could work on?

Yes, I just created PR #1824 in order to start a discussion and make progress here.