Exploring solutions: Changing the way an issue page works

You are viewing a wiki page. You are welcome to join the group and then edit it. Be bold!

How can we fix the layout/components on an issue page so that it is easier to contribute and our discussions/collaborations are more effective?

Some big ideas seem to be:

  1. Better issue summaries:
    a) What is the actual problem that we're trying to solve here?
    
b) What is/are the proposed solution(s) and their pros/cons?
    
c) What are the contentious issues that need hashing through (if any)?

    d) What is left to do on the issue before we can mark it RTBC? (and can I help?)
    e) Who has contributed and how? commented, voted, following, written/reviewed code/designs etc.

some initial implementation ideas have included a wiki-style "issue summary" that everyone can edit, or the ability to "flag" one particular comment as being a useful summary of the state of things.

  1. showing related issues for context - this should happen on the issue page as well as in the issue queue index

  2. Separating Ideas from Commentary - a way to make it easier to get your head around what has been discussed by filtering out the big ideas/next steps from the general chit chat around these. Includes needing a way to agree without disrupting flow (voting, +1ing), possibly splitting/tab out chat from patches (and UI presumably)

Personally, I think there's a lot we can draw from Quora again including the way you can visibly vote on an issue (your name gets included when you vote an answer up), and the way they hide less constructive contributions (if the community votes it down on mass). Also the way each question hosts it's own discussion.

more ideas/thoughts/etc.?

Closing Issues:
- what's the next step? what's needed? how can you help?
- marking RTBC is scary - how can we make it less so? (perhaps participatory? - I would only do it if I see someone I trust saying something like "All that is needed before RTBC is..." and I can test and verify that it is done.), checklist for RTBC?

Comments

Ariane posted an RTBC

catch's picture

Ariane posted an RTBC checklist somewhere - based on Dries' gates from his keynote. This would have to be per-project, which makes it pretty complicated, but yeah I think being able to mark something RTBC for particular areas but not others would help.

Sometimes even very large complicated issues just need someone to resolve a one line conflict in a patch, fix a typo in a code comment etc., and it's hard to figure out this is the case without reading through 200 followups - if you could see that the issue was RTBC except for x it might make that process a bit quicker.

On the other side, it'd also help to prevent premature RTBC as well - which is less of a problem but does happen a fair bit. It's quite demoralising seeing your patch marked RTBC with a comment like "+1", and having to mark it back to needs review yourself because you know no-one's ever going to commit it based on the (non) review that was posted.

I like your ideas

Stew-bee's picture

I would like to add a candidate to
1. Better issue summaries
f) Has consensus been reached on part of the issue, has this consensus closed a branch of the discussion, should the comments from the closed branch be marked as part of a dead branch. This would include issues broken off from the main issue that are now their own issue.

Redmine makes issue start yellow.

eigentor's picture

As I wrote this, I had not completely read your start post, Leisa, so forgive me for repeating things...

To allow an issue newcomer to get a grip, the start post is most important. Redmine e.g. highlights it yellow, comments are much less prominent. If it is emphasized, it should be maintained, though: The issue "owner" could keep the issue start up to date if this does not distort ore lose coherence.
So maybe make the start issue two-parted:
1. Upper: Original Issue post
2. Lower part. Update on the current status and proceedings. Marks latest and best patch, links directly to say #37 which has the best patch. Lists related issues to keep them combinded
Both these parts are highlighted and are kept at the top of every new page. If we eliminate the 300 comment direct-link problem (issue overview cannot link to the second page) pages can be shorter and main issue closer at hand. Like Leisa said, having the issue summary a wiki that anyone can edit makes sense.

This requires the issue to have a "maintainer" and a bit of a culture shift for issues. But as the poster of an issue (have often experienced this myself) feels kind of an urge to solve "his" problem, I think the motivation is basically there. If the original poster does not take interest, someone else should be able to "take over" withouth this becoming a hostile acquisition.

Life is a journey, not a destination

API change docs too

jhodgdon's picture

Another important thing to think about in the realm of issues, related to Summaries, is how to document API changes.

The way we're doing it now is not working:
- Change is committed
- Issue is marked Needs Work with tag Needs Update Documentation
- Someone maybe sometime gets around to trying to figure out what the issue was about, and adds a corresponding section to the 6/7 Module Update Guide or a similar page (http://drupal.org/update/modules/6/7 etc.)

The 6/7 page is HUGE and pretty much useless. It could be so much better if each API change item was a node/entity, and the page was a view with filters for instance. This idea is being discussed on http://drupal.org/node/648218

Just wanted to get it on the radar. Having issue summaries would help in the "figure out what the issue was about" part of this process, but the fact that the end product is not all that useful is not a good thing.

Builder of Drupal sites and modules, and Drupal tutor - http://poplarware.com
Drupal Core maintainer for documentation

Commit summary vs. progress summary

jhodgdon's picture

This week, I've been thinking and talking to people about what an issue needs in order to be committed, and the Issue Summary is coming up as being very important.

It looks like the proposals at the top of this discussion is largely concerned with the "summary" telling the status of the issue as it is in progress:
b) What is/are the proposed solution(s) and their pros/cons?

c) What are the contentious issues that need hashing through (if any)?

d) What is left to do on the issue before we can mark it RTBC? (and can I help?)
e) Who has contributed and how? commented, voted, following, written/reviewed code/designs etc.
f) Has consensus been reached on part of the issue, has this consensus closed a branch of the discussion, should the comments from the closed branch be marked as part of a dead branch. This would include issues broken off from the main issue that are now their own issue.

I agree that this is important. But I am also concerned with the "summary" in terms of what is needed when the issue is ready to be committed, so that it can be properly documented, and I've written up some guidelines for what such a "summary" might contain:
http://drupal.org/node/1155816
So I just want to make sure this is on the radar... When the issue has a patch that is ready to be committed, we do need certain information about it, in order for it to move forward (as noted on that link).

Maybe the in-progress summary and the ready-to-commit summary are two different beasts? I think both are needed, but I don't think they are serving the same purpose and I don't see them as having the same components/fields. Thoughts?

Builder of Drupal sites and modules, and Drupal tutor - http://poplarware.com
Drupal Core maintainer for documentation

Another thought...

jhodgdon's picture

As posted http://drupal.org/node/1036132#comment-4461968

The "what is the problem here" part becomes the main issue node body and the other stuff is fields that probably can be in collapsed fieldsets (for both editing and viewing) until someone wants to see them. Maybe one fieldset for "in-progress summary stuff" and another for "ready to commit summary stuff"

Builder of Drupal sites and modules, and Drupal tutor - http://poplarware.com
Drupal Core maintainer for documentation

Prairie Initiative

Group organizers

Group categories

Prairie tags

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

Hot content this week