Making WordPress.org

Opened 2 months ago

Last modified 3 days ago

#5118 new enhancement

Introduce dev-note field to Trac

Reported by: garrett-eclipse Owned by:
Milestone: Priority: normal
Component: Trac Keywords: has-patch has-screenshots dev-feedback


A thought, not sure if there's much merit. But I was wondering if it would be helpful for dev-note creation to have a field in Trac similar to the description which allowed users to collaborate on a dev-note during the work on their ticket.
In many cases work on a ticket ends days/weeks/months before it's committed. Writing a dev-note is much easier when the task is fresh in mind. If there's a field on the ticket to write your note big or small, when it's finally committed that note is then available for review/finalization and can then be pushed either into the field guide or if it's larger into a dedicated make post.
Similar to the description field any modification to the field would generate a diff and notice about the change so all parties are aware of changes.

Attachments (1)

Screen Shot 2020-03-28 at 12.04.52 PM.png (177.8 KB) - added by garrett-eclipse 2 months ago.
Example of what the field would look like.

Download all attachments as: .zip

Change History (13)

2 months ago

Example of what the field would look like.

#1 @garrett-eclipse
2 months ago

*Note: This field could be conditional on needs-dev-note/has-dev-note but feel a caveat should be in place where if there's contents it should always be visible even without those keywords set.

This ticket was mentioned in PR #11 on WordPress/wordpress.org by dd32.

2 weeks ago

This PR adds the things needed to add a Dev Note for core.trac.wordpress.org.

Ticket: https://meta.trac.wordpress.org/ticket/5118


2 weeks ago

dd32 commented on PR #11:

Ticket Description:
<img width="826" alt="Screen Shot 2020-05-22 at 5 35 03 pm" src="https://user-images.githubusercontent.com/767313/82643295-9ccaa900-9c52-11ea-8d53-512e763ffe32.png">

Ticket Property Edit:
<img width="830" alt="Screen Shot 2020-05-22 at 5 33 29 pm" src="https://user-images.githubusercontent.com/767313/82643306-a227f380-9c52-11ea-8460-dfd860d6a7f4.png">

Ticket Property Edit without DevNote content and no dev-note keywords:
<img width="834" alt="Screen Shot 2020-05-22 at 5 37 40 pm" src="https://user-images.githubusercontent.com/767313/82643526-fdf27c80-9c52-11ea-95bc-a0fe2b8aa5cc.png">

#4 @dd32
2 weeks ago

  • Keywords has-patch added

PR 11 adds the field, but I'd like to get some feedback from the Core team before deploying it.

The field doesn't show up super well in emails in my testing, it doesn't show the proper diff as it's a Property, for example:

#11: Dev Note Testing
  Reporter:  Dion Test Trac  |      Owner:  somebody
      Type:  defect (bug)    |     Status:  new
  Priority:  major           |  Milestone:
 Component:  component1      |    Version:
Resolution:                  |   Keywords:  has-dev-note
   Focuses:                  |
Dev note:
This is a Dev Note.

It has multiple lines.

Changes (by Dion Test Trac):

 * dev_note:  This is a Dev Note.  =>
     This is a Dev Note.

     It has multiple lines.

On the Ticket view, it looks something like this:

 * keywords: has-dev-note added
 * Dev Note modified
My comment here, this is NOT the dev-note, but a comment I've added at the same time.

~<del>But it does have a diff view, similar to what you'll see in this link I'm going to edit in here in a moment.</del>~ W.org trac doesn't seem to support diff'ing of properties.

I've uploaded some images of what it looks like in https://github.com/WordPress/wordpress.org/pull/11

Last edited 2 weeks ago by dd32 (previous) (diff)

#5 @dd32
2 weeks ago

  • Keywords has-screenshots added

This ticket was mentioned in Slack in #core by dd32. View the logs.

2 weeks ago

#7 @garrett-eclipse
13 days ago

  • Keywords dev-feedback added

That's awesome @dd32 thanks for creating my vision there, having it in the email and diffs available is going the extra mile. I'll bring it up in the next core chat and get some feedback for you.

My feeling is it's an awesome start and as people start using it we can iron out the wrinkles.

#8 @davidbaumwald
13 days ago

This is a great idea. FWIW, for the last couple of major releases, the list of dev notes has been compiled with third-party tools, like Google Docs/Sheets. The creating and editing of them has been the charge of a "Docs Wrangler" in the release squad with a lot of proofing by others in the group. The process has been private and not very open, for better or for worse.

This would make the process open and, as @garrett-eclipse put it, more collaborative. It may eliminate some of the mad rush at the end of a cycle to write dev notes.

Finally, this provides yet another avenue for new contributors with varying skills to get involved.

#9 follow-up: @whyisjake
13 days ago

Would it make sense to have the field collapsed normally? I can imagine a lot of comments being dumped there.

#10 in reply to: ↑ 9 @dd32
11 days ago

Replying to garrett-eclipse:

My feeling is it's an awesome start and as people start using it we can iron out the wrinkles.

My main hesitation is that if there's anything about the implementation (other than things we can fix with JS) then as it's Trac it'll be much harder to alter.

Replying to davidbaumwald:

This is a great idea. FWIW, for the last couple of major releases, the list of dev notes has been compiled with third-party tools, like Google Docs/Sheets.

I don't think this will 100% replace that flow, but it might help trigger people to fill in the notes during the dev cycle, making the end-of-release-cycle task mostly to be to pull them all together and make it flow together well.

Replying to whyisjake:

Would it make sense to have the field collapsed normally? I can imagine a lot of comments being dumped there.

It's only shown if the need-dev-note or has-dev-note keywords exist (Or, those keywords were removed and there's still content in the field from previously).

#11 @garrett-eclipse
10 days ago

Thanks @dd32 appreciate you flagging the more immutable nature of Trac. We'll raise in dev chat and get some additional eyes before making the next step.

#12 @desrosj
3 days ago

While I do like the the idea of making the process of writing, collecting, and publishing dev notes easier, I am not sure this is the best way to accomplish that.

IMO, this field will be reinventing the wheel. Google Docs is really the best way to collaborate on a document such as a post like this. There are revisions, comments, suggested changes, etc., and all of this works really well. It also creates a lot more noise within update emails. Not everyone that was interested in contributing to the ticket will be interested in contributing to the dev note.

What if, instead of a full fledged WYSIWYG field, we just add a simple text field for a URL to the draft dev note on Google Docs? It solves many of the points brought up. It makes the process more public and transparent, it's easy to know who and where the draft is, who had participated and contributed, etc. The draft can be created and linked to at any point (so the primary contributor could draft it while fresh in their mind). It also allows contributors to follow along if they wish by starring the document on Google Drive.

When the dev note is finally published, the link to the draft document can be replaced with the final Make/Core blog post.

For clarity, the field should be accompanied by a description linking to the Post & Comment Guidelines page in the Core handbook.

Alternatively, if we want to avoid embracing Google Docs as an external means to collaborate on these posts, we could encourage using draft posts on Make Core for creating and refining the post. Though I don't think I like that because a) it requires a public preview (which expires after a given time frame), and b) may cause confusion if someone shares a public preview link and someone is not aware that the post has not officially been published.

If we choose to add a URL field, we could create a report that lists all needs-dev-note tickets showing information like component, owner, and URL to the draft, etc. This could maybe help replace the spreadsheets that have been used recently.

Note: See TracTickets for help on using tickets.