richlander commented 2 years ago

dotnet/announcements best practices

The dotnet/announcements repo is intended to keep everyone informed about important information related to the .NET platform. It is a one-way broadcast that plays nicely with GitHub notifications, making it desirable to watch/subscribe to it.

We've come up with some best practice guidelines on how to use these announcements. Our approach to announcements enables some things to work well and requires a little extra care with others.

Design points

As a broad description, think of dotnet/announcements as an aggregated mirror of important issues and GitHub notifications as an RSS feed for it. The issues in this repo are NOT the canonical copy, but a mirror.

The key design points of dotnet/announcements:

Issues-only repo.
Only a few people can create issues.
Issues are mirrored copies of issues from other repos.
Issues are locked immediately.

These design points significantly reduce the scale of notifications from this repo, resulting in high signal to noise. It also avoid two sets of uncoordinated discussions. Discussions only occur on the canonical issue.

Note: We (ab)use "temporary interaction limits" so that only a few people can post to the repo. It would be ideal if this model (one-way broadcast) was better supported and we could just pin arbitrary org issues to an read-only announcements repo.

Best practices

The following best practices are intended to result in best overall community experience.

Don't link to dotnet/announcements from GitHub

GitHub includes references to other issues or PRs that link to an issue or PR as part of the comment/activity history. It's an excellent feature that helps us understand who else cares about a given topic. We actively rely on it and sometimes reach out to other projects to help them.

This feature doesn't work with locked issues (which makes sense). Please do not link -- from GitHub -- to the locked mirror issue on dotnet/announcements, but to the unlocked canonical issue. Your reference will be blocked by the lock. That's counter-productive.

You can see this dynamic playing out in the following matching/pair issues. The canonical issue has all the messy (and useful) activity and the locked dotnet/announcement issue is a clean replica.

You'll see the same pattern with other dotnet/announcement issues.

Prefer linking to dotnet/announcements from the web

There is value in linking to dotnet/announcements from blogs and other sites (like StackOverflow, just not GitHub). The value is that more people might discover dotnet/announcements, subscribe to it, and be better informed about .NET platform news.

From dotnet/announcements, users can quickly jump to a canonical issue should they want to. However, if you want to link directly to canonical issues, that's A-OK.

Create your own queries

It is easy to create your own queries of dotnet/announcement issues. The easiest way to do that is via labels.

Here are some good ones:

Looks like we messed up when we created the breaking change label. Team, let's try to avoid labels with spaces in future. We could change it, but ...

You can also create slightly more complex queries:

Note: This best practice creates query links to dotnet/announcements, which can be seen as violating the previous practice. The query links unavoidably target dotnet/announcements.

Subscribe to notifications

Subscribe to notifications will help keep you up to date with .NET Platform news. To subscribe, click the "Watch" button.

You will want to select "All Activity".

Bests practices for Microsoft folks

Microsoft folks should follow these practices when posting issues to dotnet/announcements

Direct reader to the canonical issue

Direct readers to the canonical issue as an immediate call out, with following pattern:

This issue is a locked mirror of https://github.com/dotnet/core/issues/7556. See that issue for discussion.

Examples:

The canonical issue should not link to the dotnet/announcements mirror issue.

Consider creating the canonical issue as a discussion

The GitHub discussion feature is very good. For issues that are sure to spark feedback and/or benefit from more discussion, you should use a discussion issue.

Good discussion example: https://github.com/dotnet/runtime/discussions/71042

richlander commented 2 years ago

I'll post a mirror copy of this at dotnet/announcements after a feedback period, possibly with changes.

@terrajobst @mairaw @dcwhittaker @rbhanda

KalleOlaviNiemitalo commented 2 years ago

If you open a discussion rather than an issue, don't you lose GitHub's "excellent" backreference feature?

richlander commented 2 years ago

Hmmmm. I think that's right. We should change that guidance. @terrajobst?

terrajobst commented 2 years ago

I guess that depends on how much you care about this. The reference is already in the description of the issue, at the very top. How much would this reference link add to the UX?

In principle I don't see a reason why it must be an issue. Discussions have unique features (threading being the big one) and so do PRs. I'd say so long the destination of the "canonical" issue allows for open discourse, either seems fine to me.

richlander commented 2 years ago

You may be missing the point, Immo. The point is that the reference (like the one just above from dotnet/announcments) would be missing. That would be unfortunate. I consider that higher value than the threading that discussions allow.

terrajobst commented 2 years ago

Maybe I am. Are we talking about the canonical issue (i.e. the one where the discussion is taking place) missing the reference to the dotnet/announcement repo, like this link in https://github.com/dotnet/runtime/issues/71231?

Assuming you want to continue with the pattern where you open the canonical issue first, allow for some discussion and then post in dotnet/announcements, then I think the value of that backlink would be fairly low because it would appear somewhere in the middle of this discussion anyway. If we care, I'd rather we follow the pattern of the text in dotnet/announcements and add a quote header pointing to that announcement.

richlander commented 2 years ago

It's not that. It's not the back-ref from dotnet/announcements. I was just using that as an example. It's the back-ref from everywhere else that we cannot predit/expect.

terrajobst commented 2 years ago

Sure, but that's a general issue with discussions; how are canonical issues for announcements different?

richlander commented 2 years ago

Because we're making an announcement that by definition affects the ecosystem. If it doesn't, then it shouldn't be an announcement. Most discussions are much more narrow.

18883703598 commented 9 months ago

yes

dotnet / core