-
Notifications
You must be signed in to change notification settings - Fork 10k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document custom reference resolution (#4806)
- Loading branch information
1 parent
a026e7a
commit 96ea326
Showing
10 changed files
with
135 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
Contributor documentation | ||
========================= | ||
|
||
The primary audience for documentation in this folder is contributors to ASP.NET Core. | ||
If you are looking for documentation on to *use* ASP.NET Core, go to <https://docs.asp.net>. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
`<Reference>` resolution | ||
======================== | ||
|
||
Most project files in this repo should use `<Reference>` instead of `<ProjectReference>` or `<PackageReference>`. | ||
This was done to enable ASP.NET Core's unique requirements without requiring most ASP.NET Core contributors | ||
to understand the complex rules for how versions and references should work. The build system will resolve | ||
Reference items to the correct type and version of references based on our servicing and update rules. | ||
|
||
See [ResolveReferences.targets](/eng/targets/ResolveReferences.targets) for the exact implementation of custom | ||
`<Reference>` resolutions. | ||
|
||
The requirements that led to this system are: | ||
|
||
* Versions of external dependencies should be consistent. | ||
* Servicing updates of ASP.NET Core should minimize the number of assemblies which need to re-build and re-ship. | ||
* Newer versions of packages should not have lower dependency versions than previous releases. | ||
* Minimize the cascading effect of servicing updates where possible by keeping a consistent baseline of dependencies. | ||
|
||
## Recommendations for writing a .csproj | ||
|
||
* Use `<Reference>` | ||
* Do not use `<PackageReference>` | ||
* Only use `<ProjectReference>` in test projects | ||
* Name the .csproj file to match the assembly name. | ||
* Run `build.cmd /t:GenerateProjectList` when adding new projects | ||
* Use [eng/tools/BaseLineGenerator/](/eng/tools/BaselineGenerator/README.md) if you need to update baselines. | ||
|
||
## Important files | ||
|
||
* [eng/Baseline.xml](/eng/Baseline.xml) - this contains the 'baseline' of the latest servicing release for this branch. It should be modified and used to update the generated file, Baseline.Designer.props. | ||
* [eng/Dependencies.props](/eng/Dependencies.props) - contains a list of all package references that might be used in the repo. | ||
* [eng/PatchConfig.props](/eng/PatchConfig.props) - lists which assemblies or packages are patching in the current build. | ||
* [eng/ProjectReferences.props](/eng/ProjectReferences.props) - lists which assemblies or packages might be available to be referenced as a local project | ||
* [eng/Versions.props](/eng/Versions.props) - contains a list of versions which may be updated by automation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
<!-- | ||
This file defines the versions of external dependencies used by ASP.NET Core. | ||
This file might be updated by automation. | ||
TODO: move versions from build/dependencies.props into this location. Depends on https://github.com/aspnet/AspNetCore/issues/4246. | ||
--> | ||
<Project /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters