Disallow orphaned VersionOverrides (opt-in)

[erikness]

See #178 for a description of the problem.

It's a small diff, but it's my first time contributing to this repo so I have some notes and concerns, listed in a comment below. I also have a way you could implement this in a code base with including this feature in the SDK; this should help us understand whether this PR is worth merging.

[erikness]

Notes and concerns:

• My item/property names are verbose, I'd really appreciate more concise ideas
• Does DisableVersionOverridesWithoutCentralVersions clearly indicate that by turning this on you're disallowing a certain kind of <PackageReference>? ("turn this on in order to turn this other thing off" can be confusing).
• DisableVersionOverridesWithoutCentralVersions must be 'true' for this feature to run, and the SDK doesn't set this anywhere, so by default it's the empty string and thus treated as false. This seems OK to me but it's inconsistent with most other properties where empty string is true because we check for != 'false'.
• Like the other Errors, these new Errors are raised at evaluation time, so they are raised early and apply to any target (Restore, Build, etc.)
• For _PackageReferenceWithVersionOverrideButNoCentralVersion, I used an Include/Exclude pattern instead of a Condition because MSBuild doesn't allow me to batch on custom metadata here (I don't know why)
• This feature is turned off when EnablePackageVersionOverride is false (even if DisableVersionOverridesWithoutCentralVersions is true)
• This feature is turned off when EnableCentralPackageVersions is false (even if DisableVersionOverridesWithoutCentralVersions is true)
• I didn't do anything about implicitly defined packages so I think the feature should apply to them too. Should I handle these specially? Do implicitly defined packages like FSharp.Core use VersionOverride or just Version? I don't know the pattern here.
• I didn't do anything about GlobalPackageReference either. My items are collected right after GlobalPackageReferences are copied to PackageReferences (an arbitrary choice). But GlobalPackageReferences are not allowed to have VersionOverrides (only Versions) so this feature would never apply to them
  • In principle, I think you can do a VersionOverride instead of Version for your GlobalPackageReference and it'll have the same effect (even though it's wrong). However, with this feature turned on, specifying VersionOverride will cause the new Error to be raised. It's kind of an indirect error message but I guess it's ok.
• Currently, this gives you one error at a time - so if there are multiple violations in a project, you'd have to build -> fix that one PackageReference -> build again -> fix the next PackageReference -> etc. We could, alternatively, use ContinueOnError="ErrorAndContinue" on the task, to spit out all the violations at once - but then the build wouldn't stop here. I prefer this alternative personally, but other task invocations above, don't do this, so I kept my new invocaton in line with the existing invocations for now.
• This doesn't have an error code so projects can't suppress it. I think this is probably fine. If developers want to have exceptions to this rule, then they should just keep this feature turned off.
• Testing:
  • I consumed this in a local repo of mine and made sure it raised errors on "bad" PackageReferences
  • 2 basic unit tests, verifying that orphaned VersionOverrides are allowed normally and disallowed when you turn this feature on

[erikness]

How to implement this yourself in a repo:

First, put this at the end of Packages.props, after all the version lines:

  <ItemGroup>
    <PackageReferenceWithoutGlobalVersion Include="@(PackageReference->HasMetadata('VersionOverride'))"
      Exclude="@(PackageReference->HasMetadata('Version'))" />
  </ItemGroup>

Second, put this target in a global build file:

  <Target Name="ErrorOnPackageReferencesWithoutGlobalVersion" Inputs="@(PackageReferenceWithoutGlobalVersion)"
    Outputs="%(Identity).unused" BeforeTargets="BeforeBuild">
    <Error Text="The PackageReference to %(PackageReferenceWithoutGlobalVersion.Identity) needs an entry in Packages.props"
      ContinueOnError="ErrorAndContinue" />
  </Target>

[jeffkl]

Sorry I was out of town last week. I'm looking at this now. The unit tests weren't running as part of the build because of something else which I've fixed via a commit. So you'll need to rebase and push when you get a chance

git fetch upstream master
git rebase upstream/master
git push

If that doesn't work, I can update the branch in the UI here and you can just pull.

[jeffkl]

Looks great, just change the name of the property.

My item/property names are verbose, I'd really appreciate more concise ideas

Other than the comment left, they look fine to me

Does DisableVersionOverridesWithoutCentralVersions clearly indicate that by turning this on you're disallowing a certain kind of ? ("turn this on in order to turn this other thing off" can be confusing).

DisableVersionOverridesWithoutCentralVersions must be 'true' for this feature to run, and the SDK doesn't set this anywhere, so by default it's the empty string and thus treated as false. This seems OK to me but it's inconsistent with most other properties where empty string is true because we check for != 'false'.

This is why I suggest naming it EnablePackageVersionOverrideWithoutCentralVersion instead

I didn't do anything about implicitly defined packages so I think the feature should apply to them too. Should I handle these specially? Do implicitly defined packages like FSharp.Core use VersionOverride or just Version? I don't know the pattern here.

Implicitly defined packages should only use Version

I didn't do anything about GlobalPackageReference either. My items are collected right after GlobalPackageReferences are copied to PackageReferences (an arbitrary choice). But GlobalPackageReferences are not allowed to have VersionOverrides (only Versions) so this feature would never apply to them

Although possible, it would be very unusual to use VersionOverride for global package references so I wouldn't worry about it.

Currently, this gives you one error at a time - so if there are multiple violations in a project, you'd have to build -> fix that one PackageReference -> build again -> fix the next PackageReference -> etc. We could, alternatively, use ContinueOnError="ErrorAndContinue" on the task, to spit out all the violations at once - but then the build wouldn't stop here. I prefer this alternative personally, but other task invocations above, don't do this, so I kept my new invocaton in line with the existing invocations for now.

Let's keep it consistent for now. If you want to send a separate PR to log all of the errors and still fail the build, I'd be more than happy to accept it 😄

This doesn't have an error code so projects can't suppress it. I think this is probably fine. If developers want to have exceptions to this rule, then they should just keep this feature turned off.

You can only suppress warnings anyway. The main point of error codes is so you can search the web for possible solutions. I think the error message is verbose enough to not need more documentation.

[jeffkl]

Remove the property default value and I'll merge, thank you for the contribution!

[jeffkl]

There's no need to default this property to any value as we'll only look for the user to turn it off by setting it to false. Let's remove this.

[erikness]

Yeah I wasn't sure whether checking for false and setting true by default was the right choice. I removed this, thanks for the guidance here.

[jeffkl]

Thanks for the contribution!