dotnet/announcements best practices

[richlander]

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.

• Canonical issue
• dotnet/announcements mirror issue

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:

• Docker
• Monthly-Update
• Breaking%20Change

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:

• .NET 6.0 + Security
• .NET 6.0 + Monthly Update

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 #7556. See that issue for discussion.

Examples:

• releases.json Breaking Change announcements#223
• Microsoft.Diagnostics.Tracing.EventSource.Redist package support will end with .NET 6  announcements#227

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: dotnet/runtime#71042

[richlander]

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

@terrajobst @mairaw @dcwhittaker @rbhanda

[KalleOlaviNiemitalo]

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

[richlander]

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

[terrajobst]

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]

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]

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 dotnet/runtime#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]

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]

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

[richlander]

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]

yes