Making awesome distributable packages
Many companies set up their own, internal package feeds these days, in addition to all the public ones out there. To create awesome packages, there are a few things you should keep in mind.
Usually for Episerver-developers, this would be NuGet-packages, but the rules apply just as well for npm, Yarn, Cargo, RubyGems, PyPI or other package systems.
-
First of all, and hopefully dead obvious: Make sure it works. If possible, create a test suite to make sure it is (automatically) tested properly before new package versions are created.
-
Proper versioning: Both built assemblies (when applicable) and package specification file (
nuspec,package.json,PKG-INFO,Cargo.toml…). Do use semantic versioning. -
Dependency management: Make sure you specify package dependencies for your packages if it has any. If possible, let it support a range of versions. Most package management systems support this.
-
A good readme. Does not have to contain much, but a short, simple description of what your package does.
- Should contain a list of known problems with the package, if any.
- An API description (or a link to one). Especially when you can’t build that into compiled assemblies for statically typed languages (like C#’s
///<summary>-comments). - Format it properly. Many source code browsers today supports things like Markdown (i.e. GitHub) - do use it to make your readme as easy on the eye as possible. Walls of (unformatted) text has no place in today.
-
Make it plug-and-play. If your ecosystem of choice supports automatic adding/transformation of config files, do it. Nothing is worse than installing a package, only to find out nothing happens or everything crashes due to missing or invalid configuration. And on top of that, having to spend loads of time figuring out what the package author should have done for you.
-
Make it clean up after itself. Remove all traces of your package when the module is uninstalled. Don’t leave configuration or static files behind after uninstalling.
Make the developer experience awesome, and your package is likely to be used far more. If your package is a pain to work with, something else will replace it sooner or later. Or your colleagues