Just like any other community website, Drupal.org has lots of places which could be changed and improved. However upgrading such a website to the next major version of Drupal is already a huge undertaking. So when we originally started the Drupal.org D7 upgrade project our goal was a straight port to Drupal 7. No major regressions, no major new features.
Nearly all sections and pages on D7 Drupal.org will look the same as they do now on Drupal 6. This includes documentation pages, project pages, case studies and marketplace nodes, issue queues, change records etc.
There is however one page which will change - the issue page. Knowing that this is an essential part of the website, where most contributions to Drupal are coordinated and where some people spend many hours each day, we want to explain why we chose to change certain things, show the new UI we are working on, let you try it out on our test site and tell us what is working for you and what isn’t.
Why is the issue page changing?
Redesigning the issue page was not part of our plan. However the Project* suite, and especially the Project Issue Tracking module, suffer from a lot of technical debt. This is some of the oldest contributed code in the entire Drupal project (node/3281 is the url for the Project module).
While porting to Drupal 7, we had to finally pay-off some of this debt:
- We rewrote the issue tracker from the ground up using the D7 core Field API and modern best practices.
- We tried to remove as much code as possible from Project Issue Tracking and either use existing field modules (core fields, Entity Reference, Field Group, etc) or move our custom code or functionality into general-purpose, reusable field modules (Machine Name, Dereference List, Extended File Field, Node Changes, etc).
At the end it’s safe to say we rewrote close to 90% of the code behind issue pages.
Since it was such a massive rewrite already, we used it as a chance to take a look at how people use the queue and to make changes to the UI. Many of these are ideas that we’ve discussed with Leisa Reichelt through the Prairie Initiative, and that many people on the Drupal.org team have been wanting to address for a long time.
In D6 there are two separate ways to update an issue:
- to update the issue summary, you have to use the edit tab
- to update anything else, you have to add a new comment and the comment form includes a bunch of "fields" from the node form.
Not only is this confusing (why are there two separate “modes” for updating an issue?), it means the issue summary is more rarely updated. Not everyone even understands they can do it, and since it’s a different/extra step, it tends to be ignored. Worst of all, it’s actually broken for deep technical reasons (aforementioned technical debt).
How you update an issue in D6 is simply weird. Although it seems natural to many people in the Drupal community that have been using Drupal.org for a while, having to add a comment to try to change something is unnatural and goes against the experience people have with adding comments on basically any other website. Support requests periodically appear in the Project Issue Tracking issue queue from people trying to use this module on their own sites wondering how to update issues once they post them. Newer contributors often find our issue queue strange. This is another Drupalism that many of us have internalized.
Another big problem in the D6 issue page UI is that unless you’ve been participating all along and following an issue closely, it’s often very hard to figure out what patch(es) are current, relevant, worth reviewing or testing, etc. You basically have to read the entire comment history to understand what files are still relevant, and often this means dozens of comments.
So, recreating the exact D6 UI where you have to use the comment form to change certain things about the issue and where most files are attached directly to comments would have taken a huge amount of work and special-case hacks to get working. We thought it was better to just fix the problems and build a new UI using code that will be easier to extend and maintain for the future.
Drupal 7 issue page
There are 2 major changes for the D7 issue page (and a bonus):
1. Single UI for updating an issue
Instead of having two separate modes for updating things about the issue, we're going to move everything into a single mode - updating the issue (by simply editing the node):
- Key point: if you want to change anything about an issue from now on, you will need to update the issue by editing it. This includes changing the status, changing the summary, attaching additional files, anything.
- When an issue is updated, the nodechanges module will automatically generate a comment on that issue. It will include a diff of everything that was changed in the new revision. This way comments will still contain the history of all changes to the node.
- Nodechanges injects a "Reason for your change" field into the node edit form, and if that has a value it's used as the comment body of the auto-generated comment.
- There are still raw comments, that are *just* discussion about the issue. They are posted via usual comment form without any changes to the issue itself and are just naturally interleaved with the issue-update comments.
- In addition to the standard node ‘Edit’ link, we added a prominent ‘Update this issue’ button and information when issue was last updated below it.
- Simultaneous editing of nodes is normally not allowed. So, we wrote and deployed the Conflict module to try to help with this. We’re also considering if it’d be possible to do real-time notification of issue updates.
- Lastly, commits that reference the issue could trigger an automated comment. This is not in the D7 upgrade MVP, but is in our future plans.
2. The way we handle attachments
Files will always be attached to the issue nodes themselves, never to comments.
- When you update an issue to upload additional files, the auto-generated comment will reference and display those files, but they wouldn't be directly attached to those comments.
- There will be a table on the issue page showing the files attached to that issue, including a column linking to the comment that was generated when the file was attached, the user that uploaded the file, etc.
- Users can choose which files to show in the table (via “Display” checkbox on files), since showing all attached files could be overwhelming on a large issue with lots of patches.
- Hidden files, without that checkbox set will be located in a separate table, inside a collapsed “N hidden files” fieldset.
- All changes to the visibility of a file are clearly shown in the comment history.
The basic workflow for attachments is:
- Upload a patch, defaults to visible.
- If you re-roll, you update the issue again, attach the new file, and ideally remove the 'Display' checkbox from the now obsolete patch.
- A comment is auto-generated, showing that you attached the new file, and that the old one is now hidden.
- When anyone views the issue, they first see the table of relevant files.
Note: Testbot functionality hasn't been ported yet.
3. Bonus: Issue relations
This was not in our MVP however community volunteer (thanks amateescu!) decided to write the code for this new feature while we are busy with our upgrade tasks. So D7 issue pages will have issue relations.
You will be able to specify one parent for any issue. On the issue page we’ll display a parent for this issue and a list of child issues. Additionally there will be a possibility to specify multiple related issues. In the future we are planning to add metadata to this relations, such as ‘
druplicate duplicate of’, ‘blocked on’ etc., to make relations even more meaningful.
We’ve been working hard building this functionality and think it will be an improvement in many ways. But we are not done yet. Before finishing it completely, we’d like to give you an opportunity to play with this on the test site and tell us what is working for you and what isn't. The D7 upgrade is already late, and we of course don't want to delay it any further, but this piece of the site is too important to rush. So we want to get your feedback while there's still time to make changes if needed to make this work.
Test site url: http://git7site.devdrupal.org/
Use drupal/drupal to access it and your usual username/password to login.
Note that it is being rebuild every day at 08:00-09:00 UTC, during that time it is inaccessible.
Let us know what you think either here in comments or in Drupal.org site upgrade QA queue. While this is not the full Drupal.org D7 QA yet, we encourage you to open new issues there for any problems with the issue pages you might find.