Category: open source

OpenSource library- conclusion

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

Following the guidance from https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/ it is somehow simple. Most of the rules are already implemented, other are easy to implement into a DevOps Continous Integration workflow( such as Azure DevOps) and others are hardly one half a hour.

It will be nice if we have a badge for this – I will consider making this some day ….

OpenSource library- Breaking changes

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

Following guidance from https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/breaking-changes

Nr

Recomandation

AOP Roslyn

1

DO think about how your library will be used. What effect will breaking changes have on applications and libraries that use it?

2

DO minimize breaking changes when developing a low-level .NET library.

3

CONSIDER publishing a major rewrite of a library as a new NuGet package.

4

CONSIDER leaving new features off by default, if they affect existing users, and let developers opt in to the feature with a setting.

5

DO NOT change an assembly name.

6

DO NOT add, remove, or change the strong naming key.

7

CONSIDER using abstract base classes instead of interfaces.

8

CONSIDER placing the ObsoleteAttribute on types and members that you intend to remove. The attribute should have instructions for updating code to no longer use the obsolete API.

9

CONSIDER keeping types and methods with the ObsoleteAttribute indefinitely in low and middle-level libraries.

Unfortunately, AOP Roslyn is not in the stage of breaking changes. But I have had another library, Exporter, and I have had made  3:  CONSIDER publishing a major rewrite of a library as a new NuGet package

OpenSource library-versioning

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

Following recommendations from https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/versioning

Nr

Recomandation

AOP Roslyn

1

CONSIDER using SemVer 2.0.0 to version your NuGet package.

NO

2

DO use the NuGet package version in public documentation as it’s the version number that users will commonly see.

Yes

3

DO include a pre-release suffix when releasing a non-stable package.

No

4

CONSIDER only including a major version in the AssemblyVersion

Yes

5

CONSIDER keeping the major version number of the AssemblyVersion and the NuGet package version in sync.

Yes

6

DO NOT have a fixed AssemblyVersion

Yes

7

CONSIDER including a continuous integration build number as the AssemblyFileVersion revision

Not needed

8

AVOID setting the assembly informational version yourself.

Yes

For 1: I do not like SemVer. It is putting some pressure on the developer of the OpenSource. So I decide to follow Calendar versioning https://calver.org/ 

For 2: Yes, it is normal.

For 3: No, I do not like pore-release.

For 4: Yes – the year is major

For 5: Yes, done by CI process

For 6: Yes, done by CI in Calendar Versioning

For 7: NO. And , because of Calendar versioning, it is already done, if I do not publish 2 versions in the same day

For 8: Do nothing – and it is done.

OpenSource library- Source Link

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

The documentation at https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/sourcelink says to enable source link.


Nr

Recomandation

AOP Roslyn

1

CONSIDER using SourceLink to add source control metadata to your assemblies and NuGet packages.

Modified(1)

2

CONSIDER including symbol files (*.pdb) in the NuGet package.

Done already(2)

For (1) : I have followed the instructions at https://github.com/dotnet/sourcelink/blob/master/README.md

For(2): It was done already by csproj configuration.

OpenSource library–Dependencies

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

Now trying to respect what it says at https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies .

Nr

Recomandation

AOP Roslyn

1

DO review your .NET library for unnecessary dependencies.

Done manually(1)

2

DO NOT have NuGet package references with no minimum version

Done already(2)

3

AVOID NuGet package references that demand an exact version

Done already(2)

4

AVOID NuGet package references with a version upper limit

Done already(2)

5

CONSIDER referencing shared source packages for small, internal pieces of functionality

N/A(5)

6

CONSIDER making your package a shared source package if it provides small, internal pieces of functionality.

N/A(5)

7

DO reference shared source packages with PrivateAssets=”All”.

N/A(5)

8

DO NOT have shared source package types in your public API.

N/A(5)

9

DO NOT publish shared source packages to NuGet.org.

N/A(5)

For (1): Reviewing .NET library for unnecessary dependencies is practically a manual process. Could be a dotnet global tool – but for the moment I just inspected the .csproj for references and see that all are ncessary

For (2): As I read from documentation “Typically, the package reference version in the project file is the minimum version and there’s no maximum.” .So doing nothing I am at the good point

For (5), I usually put a new dll or NuGet package – I do not share code source. So this is done also without friction.

OpenSource library – Cross-platform targeting

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

At https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/cross-platform-targeting there are the recommendations  for Cross platform. Let’s see what needs to be done for https://github.com/ignatandrei/AOP_With_Roslyn

Let’s see:

 

Nr Recommandation AOP Roslyn
1 DO start with including a netstandard2.0 target. Done – the main dll, AOPRoslyn, is already .netstandard2,0
2 AVOID including a netstandard1.x target. Not needed
3 DO include a netstandard2.0 target if you require a netstandard1.x target. Not needed
4 DO NOT include a .NET Standard target if the library relies on a platform-specific app model. Not needed
5 CONSIDER targeting .NET implementations in addition to .NET Standard. Not needed
6 AVOID using multi-targeting with .NET Standard if your source code is the same for all targets. Not needed
7 CONSIDER adding a target for net461 when you’re offering a netstandard2.0 target. OK> see later point 9

 

8 DO distribute your library using a NuGet package. Done

https://www.nuget.org/packages/dotnet-aop

 

9 DO use a project file’s TargetFrameworks property when multi-targeting Struggle to implement/ partially done – modified AOPRoslyn.csproj
10 CONSIDER using MSBuild.Sdk.Extras when multi-targeting for UWP and Xamarin as it greatly simplifies your project file. Not needed
11 DO NOT include a Portable Class Library (PCL) target. OK
12 DO NOT include targets for .NET platforms that are no longer supported. Not needed

I tried to modify to include

<TargetFrameworks>netstandard2.0;net461</TargetFrameworks>

( Attention: Framework, not Framework)

First , you should publish the .csproj

dotnet publish <path to csproj>

should be modified with -f=”netstandard2.0″

Then , each dependency should support it :

error NU1202: Package PortableConsoleLibs 1.0.0 is not compatible with net461 (.NETFramework,Version=v4.6.1). Package PortableConsoleLibs 1.0.0 supports: netcoreapp2.0 (.NETCoreApp,Version=v2.0)

So you should contact the owners to support it – or re-compile the sources, if you have.

So I will stick with

“DO NOT include targets for .NET platforms that are no longer supported.” including NET461.

Conclusion: 11 / 12 it is a good score.

Implement Open-source library guidance

Part 1

Implement Open-source library guidance

Part 2

OpenSource library – Cross-platform targeting

Part 3

OpenSource library-Dependencies

Part 4

OpenSource library- Source Link

Part 5

OpenSource library-versioning

Part 6

OpenSource library- Breaking changes

Part 7

OpenSource library- conclusion

I have written previously a booklet about “Making Open Source Component from idea to deploy With examples from .NET Core” .

Now  Microsoft and contributors make a library guidance for OpenSource projects at https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/  . I will take as a working point my component, https://github.com/ignatandrei/AOP_With_Roslyn , and see where it goes and how many things I already implemented.

The items are:

Cross-platform targeting   
Strong naming   
NuGet and open-source libraries   
Dependencies   
SourceLink   
Publishing   
Versioning   

I will implement each one in one blog post

Andrei Ignat weekly software news(mostly .NET)

* indicates required

Please select all the ways you would like to hear from me:

You can unsubscribe at any time by clicking the link in the footer of our emails. For information about our privacy practices, please visit our website.

We use Mailchimp as our marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp's privacy practices here.