lottepitcher / opinionated-package-starter

Get a head start when creating Umbraco Packages

An Opinionated Umbraco Package Starter Template

Use this dotnet new template to get a head start for creating, releasing and maintaining Umbraco Packages for v10+.

I've called it an 'opinionated' package starter template because lots of decisions have been made for you. This means that all you really have to worry about is adding your package code. A lot of the other stuff involved in releasing a package and having a well-maintained open source GitHub repository has been done already.

Of course none of these decisions are irreversible. Once you've used the template you can change whatever you need to. Please make sure you read this readme so you understand what choices you are starting with so that you can change them where necessary before you push to GitHub, and definitely before you publish to nuget!

Template details

What's wrong with the Umbraco Package template?

Nothing! You can find a link to it here. It's just that all it gives you is the actual package project. You'll need to work out how you're going to test your package, how to configure it for nuget, how you're going to release to nuget, add certain files for a well maintained repo ...

Whereas this template will create a folder with:

• A new solution (.sln)
• A package project ready for you to add your code. There's a lang .xml file in the right place to remind you to use those where feasible (instead of hard-coding text in your views)
• A test site referencing the package project
• A GitHub action for publishing to nuget
• A good start on:
  • The readme for your GitHub repository
  • The readme for your nuget package
  • The umbraco-marketplace.json file which improves how your package appears on the Umbraco Marketplace
• GitHub templates to help people create good issues and feature requests
• And more!

What key decisions have been made?

• License: MIT
• Umbraco version: v10.0.0
• nuget package Id: Umbraco.Community.YourPackageName
• 'App_Plugins' or Razor Class Library: RCL
• Initial version number: 0.1.0

Why MIT license?

Because Umbraco CMS is released with an MIT license, and I've assumed you're releasing this as an open source package too.

Why are you targeting v10?

Because it's the current Long Term Support release. I believe plenty of sites will be staying on v10 for a while ... If there is a need to restrict your package to a version of 10 higher than 10.0.0 then you should raise the dependency in your package. Refer to issue 10 for a discussion about this.

Why a 'Umbraco.Community.* nuget package id?

If you don't have a company or personal brand to use as a prefix, then this is a well used convention for Umbraco community projects.

Why are you using a Razor Class Library?

Because RCLs mean that your package assets are added virtually to your project: you don't need a targets file in your test site to physically copy the App_Plugins contents over. It also makes it easier for people who install your package as they don't have to commit your App_Plugins folder to their project repository.

If you want to understand more about RCLs, and what is involved in converting a package to be a Razor Class Library, please refer to PR 8.

Why 0.1.0 as the initial version number?

The project is created with version 0.1.0 as this fits the SemVer scheme. The version number is set in the .csproj of the package project.

Using the template

Please read the instructions for how to install the template and use it.

Contributing

Yes feedback, thoughts, issues, pull requests... are of course most welcome!

Please read the Contributing Guidelines.

Acknowledgements

A lot of the decisions were made whilst collaborating with Lee Kelleher (the creator of Contentment and many other Umbraco packages) whilst developing my Admin Only Property package. So big #H5YR for all your help Lee 🙏!

Template icon

"out of the box" by Yoyon Pujiyono from Noun Project

opinionated-package-starter's Issues

"Umbraco" is a reserved prefix on Nuget

Which version of the template have you installed?

No response

Bug description

Consider using something more like "Our.Umbraco.PackageName" since the "Umbraco" prefix is reserved and the default configuration of the package starter will error out when publishing. I ran into that myself on my first package.

Consider adding a package manifest file for telemetry

Feature summary

Would just need to be:

{
    "id": "Umbraco.Community.Templates.PackageStarter",
    "name": "PackageStarter",
    "version": "X.X.X",
    "allowPackageTelemetry": true
}

Additional details

No response

Finish the 'using the template' instructions ASAP!

Which version of the template have you installed?

No response

Bug description

No response

Using template in Visual Studio creates two .sln files

Which version of the template have you installed?

No response

Bug description

I know that there is no ide.host.json in templates.config yet to control how the parameters appear when adding in VS, but when I tried this it resulted in two .sln files being created: the one from my template and the one that VS creates when adding a 'solution'. Until that is fixed people shouldn't use VS, and so worrying about the additional details isn't relevant.

Perhaps the .sln should come out of the template and be created where VS wants to create it, and then the solution contents added by template postActions? Needs some investigation. For now, the readme clearly states to use CLI only

Allow short parameters in CLI

Feature summary

At the moment the parameters are eg. --authorName. Would be good to support -an, for example

Additional details

No response

Generate a 'friendly' name of the package

Feature summary

Some places in the solution (e.g. Title of the readmes, Title property in the .csproj) should have a 'friendly' name.

Additional details

By 'friendly' name I mean if the project is called MyNewProject, the 'friendly' name would be: My New Project

Can a dotnet new template automatically convert Pascal Case to Title case? As would be very nice to generate this.

Otherwise should the 'friendly' name be a template parameter?

Full stop in name parameter now breaks template

Which version of the template have you installed?

No response

Bug description

Now that there is a C# file in the template, if there is a full stop in the --name / -n parameter then the generated project won't compile as of course full stops in class names is not valid. I know that this is fixable, but am I going to have to refactor the 'sourceName' from PackageStarter to PackageStarter1?

Make the test site optional?

Feature summary

At the moment the template will add a test site to the solution with the correct dependency on the package project. Should it? The user still needs to go through the install process when first running the test site.

Additional details

Could remove the test site from the repo and add a bool parameter for the user to choose whether they want a test site or not. Then should test site (with reference to project, and add to solution file) it in a postAction script of the template depending on the parameter. Making sure it's the expected version of .net / umbraco, assuming you can do that in CLI

Update the template to use v13, the new LTS

Feature summary

The reasons for using v10 in the template is stated as it being the current LTS
Now v13 is the new LTS, surely new packages will be started on v13?
The current version, v1.1.0 can always be linked to for people wanting to support v10

Additional details

No response

Settle on version for the Umbraco dependencies

Feature summary

Current the template specifically targets Umbraco 10.4:

<PackageReference Include="Umbraco.Cms.Web.Website" Version="10.4.0" />
<PackageReference Include="Umbraco.Cms.Web.BackOffice" Version="10.4.0" />

But across my packages, I haven't encountered a case yet where I have to target a specific version of Umbraco 10 (although you might have to if you need to do something with the block grid).

Anyways, my point is that maybe the Umbraco version should be lowered. Eg. if the package has a dependency for 10.4.0, people with older versions of Umbraco 10 will have to update. But if the package doesn't need anything specifically from 10.4.0, it might as well be 10.0.0 instead. This then allows people to still use the package if they're on 10.0.0, but it also allows them to use a newer version of Umbraco 10.

However by adding a dependency for a version like 10.0.0, we're allowing people to upgrade to any newer version of Umbraco. A package for Umbraco 10 will very likely also work for Umbraco 10. It'll probably also work for Umbraco 12, but we don't know for sure yet as Umbraco 12 isn't out yet. And with the announced changed in Umbraco 13, it's probably not very likely that it works there. So maybe we should specify a version range instead - eg. like:

<PackageReference Include="Umbraco.Cms.Web.Website" Version="[10.0.0,12.0)" />
<PackageReference Include="Umbraco.Cms.Web.BackOffice" Version="[10.0.0,12.0)" />

This indicates that the package supports Umbraco 10 and 11, but not Umbraco 12 or newer. I think the new Marketplace also relies on this for determining the version a given package supports.

Additional details

No response

Do not use 'Generate NuGet package on build' in .csproj

Feature summary

This would slow down the build process in larger sites and also, perhaps, lead to caching issues

Additional details

If this was unticked then the nuget package would not get automatically generated when Visual Studio builds:

You should only look to test the nuget package once you've finished testing via the test site, and want to test that the nuget install itself works. So probably makes sense to use a dotnet pack command for that at the appropriate time instead.

So when you are ready to generate the nuget package for local testing use the command line with something like

dotnet pack --configuration Release /p:Version=1.0.0-rc001 --no-build --output