Kentico has a long history in building open-source solutions for customers. Our ADImportService tool had its first commits back in 2015.

Today we have a growing number of open-source projects that your teams can use to make your Xperience by Kentico solutions better, faster.

But, we don't have a monopoly on open-source! Members of the Kentico community can share their contributions as well, helping to expand the breadth of integrations, tools, and experiments available to everyone. You can find some of these community authored open-source contributions on the Integrations page here on the Kentico Community Portal.

I have a great idea!

Ok, let's say you want to join your fellow community members on GitHub and begin creating your own open-source Xperience by Kentico library or tool - where do you start?

Great question!

Thankfully, I have an easy answer - start with our open-source repo-template.

This is the same template we use for our Xperience by Kentico integrations to make sure everything is laid out in a consistent way, helping with adoption and contributions from all of you.

Kentico repo-template repository landing page with "use this template" button selected

You can create a new repository from this template in the organization space of your choice. For example you could use your personal account space or your company's space if they have one on GitHub.

GitHub new repository create screen using Kentico's repo-template repository

Once you create the repository you are ready to start adding all your custom Xperience by Kentico awesomeness!

If you want an easy way to scaffold out a class library, NUnit test project, and Dancing Goat example application (more on this below 👇), just use the included Repository-Setup.ps1 PowerShell script and supply your project name.

.\Repository-Setup.ps1 -ProjectName XperienceCommunity.CoolUtils

This will populate the /src, /tests, and /examples folders of the repository and do a quick find-and-replace of various configuration files in the repo using the supplied project name.

Kentico conventions

At Kentico we use this repo-template to help us make a great developer experience for all of you in the Kentico community. We want you to feel confident about the open-source integrations we provide, understand their support policy, get the integration working quickly, and provide feedback for any bugs or challenges.

Using the same template establishes conventions that you can learn and rely on. If you look for our NuGet packages on NuGet.org you can see they all follow the same naming convention - Kentico.Xperience.*. This is intentional!

We own the Kentico.* prefix to help protect against typosquatting and to make it visibly clear which packages are coming from us. We also follow these conventions with our npm packages.

We have more conventions with .NET namespaces, C# types, and how we architect code and features.

These are all things we do to help developers, but what about Kentico community members? What can or should they do with their integrations and open-source contributions?

One of the foundations of open-source is "you are welcome to contribute, but if you want to do something different you are free to fork the code or start your own solution".

With that in mind we (Kentico) cannot force anyone to do anything with their own open-source contributions that don't violate any legal restrictions - like authoring a ransomware, bitcoin mining, trademark infringing, Xperience-source code stealing color picker integration 😏 - so all the recommendations below are just that, recommendations.

I also think following some conventions as a community can help all of you with the same goals that Kentico has with our integrations - confidence, ease of adoption, and contribution.

Community conventions

For anyone that created an open-source project before I published this post establishing a set of conventions, no worries! You don't need to go a rewrite everything you've already authored 😅. But keep this guide in mind for your future explorations 👍.

Prefix your project with XperienceCommunity

I recommend this to make it clear that the project isn't authored by Kentico and it's a contribution from the Kentico community.

It also makes it easy for developers to find community contributions on GitHub, NuGet, or npm.

You can still add your own naming convention after XperienceCommunity., like using AwesomeTools to denote all of your projects (ex: XperienceCommunity.AwesomeTools.PageBuilderPlus).

Avoid business branding in the name

In the past, it's always been a little awkward to see another business's name in your Kentico project as a dependency when that business is a competitor. This mostly happens with Kentico partner agencies but it can also happen with customers and consultants in the Kentico community.

Additionally, don't blast your business branding all over the .NET namespaces and C# types. I think that's even more awkward of a developer experience than just doing it in the project name.

Obviously, if you are building a proprietary commercial product that integrates with Xperience by Kentico, then follow your businesses' requirements and conventions, but for the rest of us a non-branded library is going to lead to the highest adoption.

So what does this mean for you? Well, follow the convention above and prefix your project name with XperienceCommunity. but don't follow that up with your company name like XperienceCommunity.AmazingAgency.PageBuilderTools.

Include screenshots

Developers think in code and technical specifications, but when you make an open-source project you are trying to get others to benefit from your contribution. You want to build interest and you want adoption - you want to think like a marketer!

A wall of text might include all the technical details a developer needs to use your integration, but screenshots will help tell the story of why they should use your integration. Even if there's not much to show, a simple screenshot of Xperience's administration highlighting the changes your integration makes has an impact.

The Xperience by Kentico repo-template is already configured to use a Kentico logo for the NuGet package that is generated for any project using it.

Having a logo adds a bit of pizzazz and makes the library easily identifiable as related to Kentico on NuGet.

Maybe in the near future we can get an "Xperience Community" specific logo that we can all share with our projects to differentiate them from the standard Kentico logo. Let me know if you think that would be cool.

If you already have a logo for your business that you want to use, here's a fine place to add that branding.

Use Source Link

Source Link is a technology from Microsoft that's been around for several years, but with .NET 8 it was turned on by default.

That means you don't have to do anything special to get it to work on the producer side of things, but it's still good to know what it is and test it out to make sure developer will have a great experience with your project if they need to debug it in their editor.

README conventions

Kentico's repo-template README.md has clearly defined sections that organize information, keeping the most important at the top and linking out to other markdown documents so that the README.md file doesn't become cluttered.

Think of the README.md like you would a home page - you don't stuff it full of everything. Instead you curate the information you place there, making it easy to understand and guiding folks to the right place based on their interest - just like a marketer would.

Use GitHub Releases

Inevitably you will want to make some updates to your project and release a new version. Not because it had some bugs... we never write bugs... but because you have even more awesomeness to share with everyone!

Developers can use GitHub's diffing between commits to see what has changed, but if they don't know which commits are represented in each version of your project this can be extremely difficult if not impossible.

Instead, use GitHub's Releases feature which is built on Git tags. Create a new Release, tag, and add some helpful release notes each time you have an updated version of your project.

Include an example project

The best way to see how an Xperience by Kentico integration works is by using it in an Xperience project. You can make things easier for folks using your project by including an example Xperience application in your project's repository.

All of Kentico's plug-and-play integrations have an examples folder that includes a Dancing Goat project using the same Xperience version the library project targets.

If you adopt this convention in your project it will have 2 benefits.

  1. You can easily show people, in code, how to add your project to an Xperience solution
  2. Any time you make a change to the project you can make sure it still works 😉

Foster a healthy community

If we create an open-source project it's because we want to share an idea and help others. We also often want contributions from others.

To help make it easy for fellow community members to contribute, the repo-template has a Contributing Setup guide and the main README.md also links to our global CONTRIBUTING guide and CODE OF CONDUCT.

These help set the standard for how we want people to approach using and contributing to our open-source projects since open-source software is inherently a public commons and social space.

I recommend you do the same for your projects. You can copy our global documents and put them in your repository or find other examples on GitHub.

Wrap up

If you want to see examples of existing open-source community-authored Kentico projects that follow the conventions above, I can recommend reviewing the following.

I heard that Kentico MVP Michael Eustace might be creating a blog post or video soon detailing how to create an Xperience by Kentico integration based on his Kentico Partner Connection presentation, so I won't go into that topic here but leave a comment for Michael if that interests you.

If you have additional questions or suggestions about the conventions please leave a comment in the discussions and we'll keep this guide updated with anything helpful to the community.

Finally, if you've authored a Kentico open-source project let us know by sharing it as community feedback.