dotnet/announcements best practices

[terrajobst]

This issue is a locked mirror of dotnet/core#7562. See that issue for discussion.

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

Examples:

• releases.json Breaking Change #223
• Microsoft.Diagnostics.Tracing.EventSource.Redist package support will end with .NET 6  #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