What are the private states and their expected use?

[Lenbok]

I see with the new notifications that there are three private states: pending, unread, and done.

It looks to me as though notifications initially come in as "pending" (which has a single color), but if you mark them as "unread", then there is nice visual distinction between PRs of different public states.

I don't get what the "pending" state is useful for, can someone enlighten me?

Is it possible to have them skip the "pending" state and go to "unread"?

[tarsius]

Below I'll be referring to these screenshots and the parts marked with red letters.

I see with the new notifications that there are three private states: pending, unread, and done.

We refer to that as the private status (as opposed to the public state.

I do realize that it is a bit unfortunate that these two terms, which are often used as almost synonyms, are here used to two different things. But I am not a native speaker and while I have spend considerable time looking for better terms, I could not find any.

You do not have to remember which is which, as this is shown in the UI, at (a) and (b), but when having a conversation about one of these things, it would be good to use assign the terms as I have done.

It looks to me as though notifications initially come in as "pending" (which has a single color), but if you mark them as "unread", then there is nice visual distinction between PRs of different public states.

The menu shown in the screenshot, as well as other menus, optionally show a legend (c), which explains the meanings of the various colors. This legend can be toggled using -H (d).

Issues are gray, pull-requests are colorful. The public state is shown using a shade of gray for issues, and using a color for pull-requests. The "closed" state comes in to variants "we did it" and "we have decided to not do it"; to distinguish these two, the "nope" variants additionally use strike-through.

The private status is visualized using the weight of the font and by using a box.

Note that we always combine a state face and a status face; that's why we to use different face attributes to signify different aspects of the topics condition.

A theme may of course use different colors, but they should make semantic sense, and it is probably a bad idea, to diverge too far from what I have just outlined.

You do not have to memorize this, you can just leave the legend enabled. Eventually it will become second nature but it takes a while, no need to force it.

I don't get what the "pending" state is useful for, can someone enlighten me?

The three private statuses are the same as used in the Github webinterface. Unread (e), pending [aka "read but still in the inbox"] (f) and done (click on (g) to see those).

Is it possible to have them skip the "pending" state and go to "unread"?

The initial status is unread, not pending.

This is what happens.

1. Someone creates a new issue, a feature requests.
2. You have not looked at it, so for you, your "personal status" for that issue is "unread".
3. You look at that issue You have read it, so it no longer is "unread". However you might still have to do something about it, so it also isn't "done" yet.
4. What exactly it means for an issue to be "done" is for you to decide. For now let's assume you have implemented the feature, and closed it. If a issue is "closed", it is closed for everyone, but just because you closed it, that does not necessarily mean that you are truly fully "done" with it as well. That is why closing an issue does not also mark it as "done"; neither in Github's web interface, nor in Forge.
5. So you close it because you think there is nothing left for you to do here.
6. The person who opened the issue adds another comment, reporting that there is a bug in the new feature.
7. You haven't read that comment yet, so the status goes back to "unread". It doesn't matter whether you have set the status to "done" yet before that happened or whether you had left it at "pending". If someone comments again, the status goes back "unread" and once you read it, the status automatically goes to "pending".

Unfortunately there are complications. The relevant part of Github's API is abysmal. I don't say that lightly. I generally think the API is quite good. There are of course parts that I think are suboptimal, but that's not the case here; this part is truly abysmal.

The tristate unread/pending/done is represented in the API using a boolean, unread/"either pending or done, but we won't tell you". Of course this could also be represented using two booleans unread/read and pending/done, but the API doesn't do that either.

As a result of this, Forge has to use heuristics to decide what a topics status likely is on Github. Further, when you change the status in Forge, only certain status changes can by synced back to Github, because the API has wholes too. (If I remember correctly "change to unread", is the only supported status change.)

A completely new topic always starts out "unread". However if you look at using the web interface then you have infact already read it, and the API actually lets Forge determine that that is the case, so if you later sync Forge, it will start out "pending" there.

For older topics, the heuristics are more desperate and cannot possibly always get it right.

[Lenbok]

Thank you for the comprehensive explanation (Is it worth putting a section like this in the user manual?).

I basically never use the GH web ui to notifications other than to occasionally go in and mark everything done, but for some reason forge notifications seem to start off in the "pending" status rather than "unread", but I'll look closer now I understand how it is supposed to be working.

It seems that the theme I use (ef-elea-dark, by @protesilaos) does not follow your suggestions regarding using attributes that are orthogonal to the "public state" faces, and directly sets the foreground color for "pending" status. Whereas ef-elea-dark has the "unread" status just adjust the weight, allowing the fg color from the public state to remain visible. I will file a bug with that theme.

[tarsius]

(Is it worth putting a section like this in the user manual?)

Yes, but I have actually written that section several times already, and ultimately gave up doing it before the big release to avoid indefinitely delaying that release. It is hard to find the right balance in such a text. One day I'll make another attempt.