Skip to content
This repository was archived by the owner on Jan 23, 2023. It is now read-only.

Commit 5ce5289

Browse files
weshaggardweshaggard
committed
Add documentation guidelines for adding new APIs
1 parent 5163b2f commit 5ce5289

File tree

1 file changed

+124
-0
lines changed

1 file changed

+124
-0
lines changed

‎Documentation/coding-guidelines/adding-api-guidelines.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
#Add APIs
2+
3+
- [Determining versions and targets](#determining-versions-and-targets)
4+
- [Making the changes in repo](#making-the-changes-in-repo)
5+
- [FAQ](#faq)
6+
7+
##Determining versions and targets
8+
9+
1. [Determine what library](#determine-what-library) the API goes into.
10+
2. [Determine the target framework](#determine-target-framework) for the library that will contain the API.
11+
3. [Determine the version](#determine-library-version) for the library that will contain the API.
12+
13+
###Determine what library
14+
- Propose a library for exposing it as part of the [API review process](http://aka.ms/apireview).
15+
- Keep in mind the API might be exposed in a reference assembly that
16+
doesn't match the identity of the implementation. There are many reasons for this but
17+
the primary reason is to abstract the runtime assembly identities across
18+
different platforms while sharing a common API surface and allowing us to refactor
19+
the implementation without compat concerns in future releases.
20+
21+
###Determine target framework
22+
`<latest>` is the version currently under development.
23+
24+
- If the library is [part of netstandard](#isnetstandard)
25+
- Your target framework should be `netstandard<latest>`
26+
- If it is a new API only available on .NET Core then it will be added to `netcoreapp<latest>`
27+
- If the library is not part of netstandard
28+
- If package dependencies are changed then your target framework should be the minimum target framework that supports all your package dependencies.
29+
- If your package depends directly on runtime changes or library changes that ship with the runtime
30+
(i.e. System.Private.CoreLib) then your target framework should be `netstandard<latest>` (hint: usually indicated by needing the latest Microsoft.TargetingPack.Private.* package)
31+
- If your package depends on changes in a native shim package then your target framework should be
32+
`netstandard<latest>`.
33+
- When targeting `netstandardX` your new API must be supported by all target frameworks that
34+
map to that netstandard version (see [mapping table](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/net-platform-standard.md#mapping-the-net-platform-standard-to-platforms)). If not bump the version to the minimum netstandard version that supports this API on all frameworks that map to that netstandard version.
35+
- If the library is not part of netstandard and not building against netstandard
36+
- All the rules for a library that is not part of netstandard apply but instead of having a target framework of
37+
`netstandard<latest>` it will have a target framework of `<framework><latest>`. Example `net<latest>` for desktop or `netcoreapp<latest>` for .NET Core.
38+
- It is common for a library to target multipe frameworks all the latest versions when adding new APIs.
39+
40+
###Determine library version
41+
- If targeting netstandard
42+
- Ensure minor version of the library is bumped since last stable package release
43+
- If targeting netcoreapp
44+
- No version bump necessary
45+
46+
##Making the changes in repo
47+
48+
**If changing the library version**
49+
- Update the `AssemblyVersion` property in `<Library>\dir.props` (ex: [System.Runtime\dir.props](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/dir.props#L4)). If `AssemblyVersion` is
50+
set in any of the individual csproj's remove it from them.
51+
52+
**Update ref**
53+
- If changing target framework
54+
- `NugetTargetMoniker` in `<Library>\ref\<Library>.csproj` (ex: [ref\System.Runtime.csproj](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/ref/System.Runtime.csproj#L8))
55+
- Update framework section in `<Library>\ref\project.json` (ex: [System.Runtime\ref\project.json](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/ref/project.json#L4))
56+
- Add your API to `<Library>\ref\<Library>.cs`. Use GenAPI to normalize the file.
57+
- If adding an additional target framework for the ref (ex: adding a .NET Core specific API) you may need
58+
to add a `<Library>\ref\<Library>.builds` for the new configuration (ex: [ref/System.Runtime.Extensions.builds](https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Extensions/ref/System.Runtime.Extensions.builds#L6)).
59+
60+
**Update src**
61+
- If changing target framework
62+
- Update `NugetTargetMoniker` in `<Library>\src\<Library>.csproj` (ex: [src\System.Runtime.csproj](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/src/System.Runtime.csproj#L12))
63+
- Update framework section in `<Library>\src\project.json` (ex: [System.Runtime\src\project.json](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/src/project.json#L3))
64+
- Update build configurations in `<Library>\src\<Library>.builds` if necessary (see [Project configuration conventions](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/project-guidelines.md#project-configuration-conventions))
65+
- The default build configuration(i.e. TargetGroup excluded) should build the latest version
66+
- If you need a live build of the older versions they need to be added as a new configuration
67+
- Typically only done for libraries not in netstandard that have larger amounts of code
68+
that we want to update outside of servicing events.
69+
- Make your code changes.
70+
71+
**Update pkg**
72+
- If changing the target framework
73+
- Update SupportedFrameworks metadata on the ref ProjectReference to declare the set of
74+
concrete of platforms you expect your library to support. (see [Specific platform mappings](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/net-platform-standard.md#nuget)). Generally
75+
will be a combination of netcoreapp1.x, netfx46x and/or uap10.x.
76+
- If package is not split (i.e. only one pkgproj, ex [pkg\System.Diagnostics.Process.pkgproj](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Process/pkg/System.Diagnostics.Process.pkgproj)) then it should already have a `ProjectReference` the `<Library>\src\<Library>.builds` file and so there is no additional changes needed in the pkgproj.
77+
- If package is RID split (i.e. has multple pkgprojs, ex: [pkg\any\System.Runtime.pkgproj](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/pkg/any/System.Runtime.pkgproj) and [pkg\aot\System.Runtime](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/pkg/aot/System.Runtime.pkgproj))
78+
- Update the ProjectReferences in the respective pkgproj's to align with the build configurations in the
79+
`<Library>\src\<Library>.builds` file. This may entail adding new references or removing references according to whatever changes were made to the .builds file.
80+
- If assembly or package version is updated the package index needs to be updated by running
81+
msbuild `<Library>/pkg/<Library>.pkgproj /t:UpdatePackageIndex`
82+
83+
**Update tests**
84+
- If changing target framework
85+
- Update `NugetTargetMoniker` in `<Library>\tests\<Library>.csproj` (ex: [tests\System.Runtime.csproj](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/System.Runtime.Tests.csproj#L13))
86+
- Update framework section in `<Library>\tests\project.json` (ex: [System.Runtime\tests\project.json](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/project.json#L30))
87+
- Add new build configuration in `<Library>\tests\<Library>.builds` (ex: [tests\System.Runtime.builds](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/System.Runtime.Tests.builds#L6))
88+
- Set `TargetGroup` which will generally match the `TargetGroup` in the src library build configruation. (ex: [tests\System.Runtime.builds](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/System.Runtime.Tests.builds#L7))
89+
- Set `TestTFMs` metadata to a list of target frameworks to run on, will generally match the `SupportedFrameworks` metadata in the pkgproj (ex: [tests\System.Runtime.builds](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/System.Runtime.Tests.builds#L8))
90+
- If `TestTFMs` is empty it defaults to [netcoreapp1.0](https://github.com/dotnet/corefx/commit/57af41ef1439ad2e443e42d03d55d41613e4c02e#diff-cd0fc5e0bad8102e1a45aa7575bdd102R155)
91+
- Add new test code following [conventions](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework.
92+
- To run just the new test configuration run `msbuild <Library>.csproj /t:RebuildAndTest /p:TargetGroup=<TargetGroup>`
93+
94+
##FAQ
95+
_**<a name="isnetstandard">Is your API part of netstandard?</a>**_
96+
97+
- For netstandard2.0 refer to https://github.com/dotnet/standard/tree/master/netstandard/ref.
98+
- For earlier netstandard versions refer to list at https://github.com/dotnet/corefx/blob/master/pkg/NETStandard.Library/NETStandard.Library.packages.targets
99+
100+
_**What is the difference between being part of netstandard and building against netstandard?**_
101+
102+
Things that are part of netstandard can only change when we release a new version of a platform
103+
that supports the higher version of netstandard. Whereas things that build against netstandard and
104+
ship in independent packages can be changed without an update to the platform that it is running on.
105+
That gives more flexibility to add API to things that build against netstandard because it does not require
106+
a platform update to consume.
107+
108+
_**What changes require me to update my target framework in my library package?**_
109+
110+
*Target framework of dependencies*
111+
- If any changes (ref or src) require a higher target framework of one of the dependencies then your library package target framework must be increased to match the new minimum version that supports all package dependencies.
112+
113+
*Independently shipped dependencies*
114+
- If any changes (ref or src) requires a newer runtime/platform change that ships independently(this should generally only apply to libraries that are part of netstandard). Some example dependencies include:
115+
- Runtime (aka RID) split package dependencies
116+
- Dependencies on runtime changes
117+
- Dependencies on runtime libraries (i.e. in Microsoft.TargetingPack.Private.* packages)
118+
- Dependencies on new native shim changes
119+
- .NET Native Shared Library
120+
121+
###Potential clean-up work that can be done
122+
- Remove old build configurations - The older build configurations will automatically be harvested from
123+
the last stable packages and thus can be removed.
124+
- Remove import statements - If not referencing any pre-netstandard stable packages the [imports of dotnet5.x](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Process/src/project.json#L28) are no longer needed and can be removed.

0 commit comments

Comments
 (0)