Generation of references will generate several changes

[tlakollo]

Description

This document provides the steps you need to take to update the reference assembly when adding new public APIs to an implementation assembly. The problem with executing the commands currently (no changes added to the API surface) will generate the following info

1 file changed, 1849 insertions(+), 1863 deletions(-)

They are three things that I think could be happening:

• The command generates the wrong code, and the command needs to be changed
• The command generated some code, but intentionally we want to override that behavior (maybe we could use an exception list to avoid changing that code)
• The generated code is correct and was just wrongfully added (they just need to be fixed)

Reproduction Steps

Go to runtime\src\libraries\System.Runtime\src and execute dotnet build --no-incremental /t:GenerateReferenceSource

Expected behavior

The experience should be:

• Someone changes an API
• Run the command to update the ref file
• Verify the change and commit

Actual behavior

The experience now is:

• Someone changes an API
• Run the command to update the ref file
• Look for his changes between the ~1800 lines
• Cherry-picks those changes
• Revert the command execution to get the original reference file
• Add the changes from the script manually
• Commit

Notice that every added step is prone to add something that is wrong in the reference, they are several diffs that are flagged because they were added manually and contain some sort of error.

Regression?

No response

Known Workarounds

No response

Configuration

No response

Other information

No response

Tagging subscribers to this area: @dotnet/area-infrastructure-libraries
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Description

This document provides the steps you need to take to update the reference assembly when adding new public APIs to an implementation assembly. The problem with executing the commands currently (no changes added to the API surface) will generate the following info

1 file changed, 1849 insertions(+), 1863 deletions(-)

They are three things that I think could be happening:

• The command generates wrong code, and the it needs to be changed
• The command generated some code, but intentionally we want to override that behavior (maybe we could use an exception list to avoid changing that code)
• The generated code is correct and was just wrongfully added (they just need to be fixed)

Reproduction Steps

Go to runtime\src\libraries\System.Runtime\src and execute dotnet build --no-incremental /t:GenerateReferenceSource

Expected behavior

The experience should be:

• Someone changes an API
• Run the command to update the ref file
• Verify the change and commit

Actual behavior

The experience now is:

• Someone changes an API
• Run the command to update the ref file
• Look for his changes between the ~1800 lines
• Cherry-picks those changes
• Revert the command execution to get the original reference file
• Add the changes from the script manually
• Commit

Notice that every added step is prone to add something that is wrong in the reference, they are several diffs that are flagged because they were added manually and contain some sort of error.

Regression?

No response

Known Workarounds

No response

Configuration

No response

Other information

No response

Author:	tlakollo
Assignees:	-
Labels:	area-Infrastructure-libraries, untriaged
Milestone:	-

[ViktorHofer]

cc @tannergooding as you just recently opened dotnet/arcade#8769. Are you aware of the diff being reported here? I wasn't.

[tannergooding]

System.Runtime has always been special and explicitly calls out the document (https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/updating-ref-source.md#for-systemruntime):

2. Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.

There are a number of inconsistencies, particularly around attributes, that haven't been a priority for anyone to go look at or resolve. It would likely require some non-trivial work in GenAPI and working around various out of date issues with CCI (most of which would go away if we were using the Roslyn APIs instead). -- CCI is extremely out of date and isn't, afaik, being updated anymore. It isn't aware of and likely will never become aware of many of the new Roslyn features/functionality.

[ViktorHofer]

@tlakollo I'm closing this issue as the current behavior is documented. Even though it's not ideal, it's the best that we currently have based on the tooling that we use underneath to generate these reference source files.