Add tags to patches #69

jchampio · 2025-06-02T18:06:10Z

A Tag is an arbitrary label for a patch in the Commitfest UI. Other than helping users identify patches of interest, it has no other semantic meaning to the CF application. This addresses #11 and #67.

Tags are created using the administrator interface. They consist of a unique name and a background color. The color should be sent from compliant browsers in #rrggbb format, which is stored without backend validation; to avoid later CSS injection, any non-conforming values are replaced with black during rendering.

It also includes some javascript to help admins pick colors that aren't completely eye-gouging, by putting up an (ignorable) warning if we don't meet baseline WCAG recommendations on text contrast.

Notes

To avoid putting a separate name+color copy of every tag into each row of the patchlist query, I instead grab the tag IDs and look them up in a map at render time. I think this requires @transaction.atomic to tie the map and patches together, which I've added across the entire view for simplicity.
Backend validation for the color didn't make a whole lot of sense to me, since only admins can create tags and we escape at time-of-use anyway.

Screenshots

Admin interface:

User interface:

A Tag is an arbitrary label for a patch in the Commitfest UI. Other than helping users identify patches of interest, it has no other semantic meaning to the CF application. Tags are created using the administrator interface. They consist of a unique name and a background color. The color should be sent from compliant browsers in #rrggbb format, which is stored without backend validation; to avoid CSS injection, any non-conforming values are replaced with black during templating.

Add front-end soft validation to the TagAdmin form. This uses WCAG 2.2 guidelines to warn the administrator if a color choice is going to be low-contrast when compared to our text/background color of white. (The warning may be ignored.)

polobo · 2025-06-05T02:30:59Z

pgcommitfest/commitfest/views.py

@@ -531,6 +533,7 @@ def patchlist(request, cf, personalized=False):
    )


+@transaction.atomic  # tie the patchlist() query to Tag.objects.all()


I'd be inclined to define Tag as an append/update-only table - soft deletes only. Think PostgreSQL enums in recommended usage (but with a soft delete capability). No real point enforcing a transaction to read its contents in that case. Even if we got an overly fresh read the attributes of Tag that would be valid data.

Until tag usage settles, I think it should be easy for CFMs to add and remove them. (Easily worth a transaction wrap IMO, and the more I look at the complexity of patchlist() the more I think that perhaps it should have been wrapped already...)

Is there some hidden cost to @transaction.atomic that's not in the documentation, that I should be aware of?

Is there some hidden cost to @transaction.atomic that's not in the documentation, that I should be aware of?

Not that I know of. The goal of using soft deletes still stands. Don't show "hidden/deleted" tags in the UI but they are still there and can be re-enabled. With name/description separated from label so long as the purpose is deemed valid the label can be changed to better match community expectations - which I suspect would happen if we removed and then reinstated a tag. It doesn't have to a hard-and-fast rule; especially if we don't functionally depend on it.

pgcommitfest/commitfest/models.py

polobo · 2025-06-05T02:48:45Z

pgcommitfest/commitfest/models.py

 class Patch(models.Model, DiffableModel):
    name = models.CharField(
        max_length=500, blank=False, null=False, verbose_name="Description"
    )
    topic = models.ForeignKey(Topic, blank=False, null=False, on_delete=models.CASCADE)
+    tags = models.ManyToManyField(Tag, related_name="patches", blank=True)


Maybe also pre-mature, and likely reasonably added later, but I envisioned an ability for annotations to be added to the tag-patch mapping. Maybe the commit message and email threads are enough places to write stuff but, especially for something like 'Good First Issue', some commentary as to why would be expected to exist somewhere, and a tag annotation seems like a good place.

I'm also thinking we'll use the mailing list for primary discussion while this shakes out, but I think this would be a good thing to add eventually.

polobo · 2025-06-05T03:41:58Z

For the CSS I've a couple of thoughts.

Can we use "LCH" as the color specifier instead of RGB?

Python has cssutils to dynamically build stylesheets. Not sure we can fully delegate value validation but keeping the legibility check in place is nice which naturally checks the inputs.

I'd be more inclined to add data-* attributes to the html markup and build a dynamic stylesheet served from an assets URL. Solving cache busting/invalidation (version code in the virtual file name) should be straight-forward - tags aren't going to be frequently changing. I'm considering whether they should just be compiled in; do away with the creation UI altogether. Point users to an external color picker and just tell them where to copy the value. Need to do more research here though - just some thoughts for now.

jchampio · 2025-06-05T13:26:30Z

Can we use "LCH" as the color specifier instead of RGB?

I like the technical details of LCH, but does it give users something? It's hard to beat "click the button, pick a color, move on" for the price of an <input>. If the system eventually gets the smarts to pick colors for you, then I think LCH starts to make more sense.

polobo · 2025-06-05T16:45:37Z

Can we use "LCH" as the color specifier instead of RGB?

I like the technical details of LCH, but does it give users something? It's hard to beat "click the button, pick a color, move on" for the price of an <input>. If the system eventually gets the smarts to pick colors for you, then I think LCH starts to make more sense.

I would say the people using this form are designers - our users are the people seeing the results on the webpage. It should be generally easier to produce a consistent set of colors for them to see if those colors are specified in LCH, in particular with a agreed-upon "Luminosity component. Also hoping to figure out dark mode at some point which seems easier to do if using LCH. People invented it and got in into the browsers for a reason.

jchampio · 2025-06-05T17:38:30Z

Is it hard to migrate RGB to LCH later, if we eventually get to a place where we'd like to make better use of color?

polobo · 2025-06-05T18:22:54Z

I don’t have any immediate concerns about trying to migrate away from RGB in the future. This is stuff I would need to experiment with myself anyway.

JelteF · 2025-06-05T22:54:02Z

I think storing RGB is fine for now. One thing that would be nice is a "randomize color button" like github has for labels.

JelteF · 2025-06-05T22:57:31Z

pgcommitfest/commitfest/models.py

+        super().__init__(*args, **kwargs)
+
+
+class Tag(models.Model):


Can you add some entries for this to the dummy database dump: https://github.com/postgres/pgcommitfest#regenerating-the-database-dump-files Or maybe even add a few to that we know we definitely want to the migration.

Sure, I'll add some to the dummy data. (I'm hoping the initial tags will come from the mailing list during the preview.)

I think "bug", "needs-user-testing", "needs-bikeshedding", "good-first-review", "mising-docs", "missing-tests" would be a good start.

JelteF · 2025-06-09T21:29:20Z

I played around with this PR just now. I committed a few quality of life improvements on this branch for usability issues I ran into. I think now the only thing it needs is some default tags for people to start with, and then we can merge this.

polobo · 2025-06-10T03:53:58Z

The attached picture contains my current thinking regarding how tags would be setup in the medium-to-long term. The colors are approximate - as I noted above all tag values in a category simply inherit the color for the category (no borders though, too hard to see and not needed). Bugs gets its own tag, then today's sections get broken out into 4 tag categories that we can fully populate as desired with specific tags. The "Needs Request" category then covers the things authors might want to signal they need help with. I've included a "Development" tag for features either previously abandoned by their author or those that exist because they are deemed "Good First Issue". The "Reviewer Type" likewise is present to handle the expressed desire to communicate the amount of expertise the author (or whomever can edit a patch) deems needed to move it forward. I've included CFBot as an initial placeholder for communicating with the CFBot besides adding directives to the commit message. Lastly, I've included the existing statuses and suggestions for how to color them in line with the tag coloring. In particular, I've reserved Green for In Progress/Committer. I was going to reserve Red for the "failure" statuses but figured Bug Fix made sense. Blue is (for me...I know color is cultural but not sure how to act on that knowledge) neutral in nature so server feature tags and reviewing - the normal/high-volume stuff - gets that. Special/Needs/Reviewer try to draw attention. Both Bug Fix and CFBot really need something besides tags, that exist in the linking record between tag and patch, to store information. Both pre-defined as shown here, and free-form text for stuff like Reviewer Type or Needs Request.

Here is a link to the source document. It is presently editable until I regret that choice or we find a better mechanism.

polobo · 2025-06-16T02:18:34Z

Strongly believe tag names should be written like; "Help - Docs" instead of "help-docs"; "Good First Review", etc...

JelteF · 2025-06-16T06:44:54Z

Strongly believe tag names should be written like; "Help - Docs" instead of "help-docs"; "Good First Review", etc...

Curious if you have any reason why you prefer that, but changed now.

JelteF · 2025-06-16T07:49:05Z

I couldn't find a way to push the background color into a safer data-* attribute, but maybe someone knows of a way to do that? That would get rid of the CSS injection problem altogether.

I looked into this, and afaict it's impossible to do this. Even with the attr css attribute, because that doesn't support colors: https://developer.mozilla.org/en-US/docs/Web/CSS/attr

polobo · 2025-06-16T14:24:42Z

Strongly believe tag names should be written like; "Help - Docs" instead of "help-docs"; "Good First Review", etc...

Curious if you have any reason why you prefer that, but changed now.

The things people read day after day basically have the form “word word word” etc…so our brains have the least amount of work on syntax, and can hone in on content and remembering/association, when reading stuff in that form. Stuff like “word_word_word” and “word-word-word” look more like code (which given the audience suggests it wouldn’t be terrible) than something intended for polished user interface presentation. Capitalization of the first letter aids in this as well for title/label content for much the same reason.

A Tag is an arbitrary label for a patch in the Commitfest UI. Other than helping users identify patches of interest, it has no other semantic meaning to the CF application. This addresses #11 and #67. Tags are created using the administrator interface. They consist of a unique name and a background color. The color should be sent from compliant browsers in `#rrggbb` format, which is stored without backend validation; to avoid later CSS injection, any non-conforming values are replaced with black during rendering. It also includes some javascript to help admins pick colors that aren't completely eye-gouging, by putting up an (ignorable) warning if we don't meet baseline [WCAG recommendations](https://www.w3.org/WAI/WCAG22/Techniques/general/G18.html) on text contrast. ## Notes - To avoid putting a separate name+color copy of every tag into each row of the `patchlist` query, I instead grab the tag IDs and look them up in a map at render time. I think this requires `@transaction.atomic` to tie the map and patches together, which I've added across the entire view for simplicity. - Backend validation for the color didn't make a whole lot of sense to me, since only admins can create tags and we escape at time-of-use anyway. ## Screenshots Admin interface: ![image](https://github.com/user-attachments/assets/8061a2d1-1d5b-456b-99bb-4af5d6dc79fc) User interface: ![image](https://github.com/user-attachments/assets/9c95b307-c6e2-48c8-bd65-881c08429a96) --------- Co-authored-by: Jelte Fennema-Nio <[email protected]>

jchampio added 2 commits June 2, 2025 10:48

Help admins choose tag colors with contrast

02aa97f

Add front-end soft validation to the TagAdmin form. This uses WCAG 2.2 guidelines to warn the administrator if a color choice is going to be low-contrast when compared to our text/background color of white. (The warning may be ignored.)

polobo reviewed Jun 5, 2025

View reviewed changes

pgcommitfest/commitfest/models.py Show resolved Hide resolved

polobo reviewed Jun 5, 2025

View reviewed changes

JelteF reviewed Jun 5, 2025

View reviewed changes

JelteF added 4 commits June 9, 2025 22:11

Add selectize support to tag picker

180ac89

Allow filtering by tags

415c41a

Run make fix

b86c4d1

Allow clicking on a tag in commitfest overview page

1d605a0

JelteF added 7 commits June 15, 2025 21:59

Merge branch 'main' into dev/tags-2

c982722

Fix merge

c105746

Add default tags, descriptions, and raw hex code input

d1bf0fd

Add tags to patches in dummy data and fix tag display in history

7ae88ae

Add description as hovertext for tags

dfc14ea

Add description as hovertext for tags on patch page

7122202

Add tags to dashboard

f6d2396

Use spaces + title case in default tags

e8ee2bb

JelteF added 2 commits June 16, 2025 09:30

Allow filtering by multiple tags at once

e7fba3e

More default tags

a88dc7a

JelteF added 2 commits June 16, 2025 09:40

Update dummy data dump with new tags

467d483

Formatting

92e98e5

JelteF added 7 commits June 16, 2025 10:14

Add validation also to text field

9cc55f6

Auto formatting

e20ca39

Merge remote-tracking branch 'origin' into dev/tags-2

551d958

Update change messages with new tag names

b8ae995

Add comment about SQL injection consideration

31a4afc

Use repeatable read for commitfest and dashboard query

8c714bd

Merge branch 'main' into dev/tags-2

fd2c93e

JelteF merged commit a0ae045 into postgres:main Jun 16, 2025
1 check passed

This was referenced Jun 17, 2025

Tags to show which subsystem a patch is targeting #67

Closed

Make topics a "tag/label" system instead of a "category" system #11

Closed

		@@ -531,6 +533,7 @@ def patchlist(request, cf, personalized=False):
		)


		@transaction.atomic # tie the patchlist() query to Tag.objects.all()

Add tags to patches #69

Add tags to patches #69

Uh oh!

Conversation

jchampio commented Jun 2, 2025 • edited by JelteF Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Screenshots

Uh oh!

polobo Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

jchampio Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

polobo Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

polobo Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

jchampio Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

polobo commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jchampio commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

polobo commented Jun 5, 2025

Uh oh!

jchampio commented Jun 5, 2025

Uh oh!

polobo commented Jun 5, 2025

Uh oh!

JelteF commented Jun 5, 2025

Uh oh!

JelteF Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jchampio Jun 6, 2025

Choose a reason for hiding this comment

Uh oh!

JelteF Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JelteF commented Jun 9, 2025

Uh oh!

polobo commented Jun 10, 2025

Uh oh!

polobo commented Jun 16, 2025

Uh oh!

JelteF commented Jun 16, 2025

Uh oh!

JelteF commented Jun 16, 2025

Uh oh!

Uh oh!

polobo commented Jun 16, 2025

Uh oh!

Uh oh!

jchampio commented Jun 2, 2025 •

edited by JelteF

Loading

polobo commented Jun 5, 2025 •

edited

Loading

jchampio commented Jun 5, 2025 •

edited

Loading

JelteF Jun 5, 2025 •

edited

Loading

JelteF Jun 6, 2025 •

edited

Loading