Wskazówki dotyczące biblioteki typu open-sourceOpen-source library guidance

Te wskazówki zawierają zalecenia dla deweloperów do tworzenia wysokiej jakości bibliotek .NET.This guidance provides recommendations for developers to create high-quality .NET libraries. Ta dokumentacja koncentruje się na co i dlaczego podczas tworzenia biblioteki .NET, a nie jak.This documentation focuses on the what and the why when building a .NET library, not the how.

Aspekty wysokiej jakości bibliotek open source .NET:Aspects of high-quality open-source .NET libraries:

  • Włącznie — dobre biblioteki .NET starają się obsługiwać wiele platform, języków programowania i aplikacji.Inclusive - Good .NET libraries strive to support many platforms, programming languages, and applications.
  • Stabilny — dobre biblioteki .NET współistnieją w ekosystemie .NET, działające w aplikacjach zbudowanych z wielu bibliotek.Stable - Good .NET libraries coexist in the .NET ecosystem, running in applications built with many libraries.
  • Zaprojektowany do ewolucji — biblioteki .NET powinny udoskonalać i ewoluować wraz z urazem, jednocześnie obsługując istniejących użytkowników.Designed to evolve - .NET libraries should improve and evolve over time, while supporting existing users.
  • Debugowanie — biblioteki .NET powinny używać najnowszych narzędzi do tworzenia doskonałego środowiska debugowania dla użytkowników.Debuggable - .NET libraries should use the latest tools to create a great debugging experience for users.
  • Zaufane — biblioteki .NET mają zaufanie deweloperów, publikując w NuGet przy użyciu najlepszych rozwiązań w zakresie zabezpieczeń.Trusted - .NET libraries have developers' trust by publishing to NuGet using security best practices.

Rodzaje zaleceńTypes of recommendations

Każdy artykuł przedstawia cztery rodzaje zaleceń: Czy, Należy rozważyć, Unikać, i nie.Each article presents four types of recommendations: Do, Consider, Avoid, and Do not. Typ zalecenia wskazuje, jak mocno należy go przestrzegać.The type of recommendation indicates how strongly it should be followed.

Prawie zawsze należy przestrzegać zalecenia Do.You should almost always follow a Do recommendation. Przykład:For example:

✔️ dystrybuują biblioteki przy użyciu pakietu NuGet.✔️ DO distribute your library using a NuGet package.

Z drugiej strony należy wziąć pod uwagę zalecenia powinny być ogólnie przestrzegane, ale istnieją uzasadnione wyjątki od reguły i nie należy czuć się źle o nie przestrzeganie wskazówek:On the other hand, Consider recommendations should generally be followed, but there are legitimate exceptions to the rule and you shouldn't feel bad about not following the guidance:

✔️ ZASTANÓW SIĘ przy użyciu SemVer 2.0.0 do wersji pakietu NuGet.✔️ CONSIDER using SemVer 2.0.0 to version your NuGet package.

Unikaj zaleceń wspomnieć rzeczy, które na ogół nie są dobrym pomysłem, ale łamanie reguły czasami ma sens:Avoid recommendations mention things that are generally not a good idea, but breaking the rule sometimes makes sense:

❌UNIKAJ nuget odwołań do pakietu, które wymagają dokładnej wersji.❌ AVOID NuGet package references that demand an exact version.

I wreszcie, Nie zalecają wskazać coś, czego prawie nigdy nie należy robić:And finally, Do not recommendations indicate something you should almost never do:

❌NIE publikuj wersji biblioteki o silnej nazwie i nieo silnej nazwie.❌ DO NOT publish strong-named and non-strong-named versions of your library. Na przykład Contoso.Api Contoso.Api.StrongNamedi .For example, Contoso.Api and Contoso.Api.StrongNamed.