Forem: Joe Glombek

Masto-meta: Gaining insights into fediverse accounts

Joe Glombek — Sun, 24 Mar 2024 08:49:47 +0000

Authenticity in the fediverse isn't as simple as a blue tick (then again, it's not that simple on Twitter any more either!) but there are some insights we can gather from a quick glace at a profile. I often see people attempting to interact with fediverse accounts that aren't real people, so these tips ought to help.

Usernames and instances

A fediverse username has two parts, the "local username" and the "instance name". For example, my current username is @joe@umbracocommunity.social. joe is my chosen username and umbracocommunity.social is the domain name (web address) of the server or instance I signed up with. This isn't always a Mastodon server, but can be any ActivityPub compliant site.

press.coop

An account ending with @press.coop are unofficial bots which scrape RSS feeds of various news sites. They reject replies to posts (but that won't stop you tagging them!) and no replies are visible to anyone at the news organisations. All accounts are marked as bots (see below) and have a meaningless gold checkmark emoji.@BBCNews@press.coop is a popular account but has nothing to do with the BBC. Although the BBC is running a trial of Mastodon, this does not yet include any official news sources.

bird.makeup (and other domains containing `bird` or `birdsite`)

Bird.Makeup is an open-source one-way bridge from Twitter/X to the Fediverse. You cannot interact with a bird.makeup user, since the bridge is one way. There can also be sizable delays in posts appearing. There's no way to opt out or redirect from an old account to a new one, so @umbristol@bird.makeup still works even though we have an active Mastodon account at @umbristol@umbracocommunity.social - so make sure if you're tagging someone, you tag the right account! These are only good for reading posts from people not on the fediverse. Think @potus or @callumbwhyte.

threads.net

This week, Instagram Threads announced they were extending their Fediverse trial to a wider audience - including all Threads accounts in the US, Canada and Japan (at time of writing). The integration must be manually enabled is currently limited to one-way (Threads to Fediverse) meaning replies can't be seen from Threads and Threads users can't yet follow other Fediverse accounts, but Fediverse likes do show up in Threads.

Interestingly verified accounts on Threads don't show up in the Mastodon interface in any way yet. But if you want, you can now follow what @zuck@threads.net has to say!

Sites that aren't a social network

We already touched on bird.makeup not being a Mastodon server. It's its own thing. But there's nothing stopping any site being on the Fediverse - you just need to implement certain API endpoints! This means that many Wordpress blogs and other non-social network sites are followable from your Mastodon feed. Replies to posts from non-social networks can be a bit of an unknown. They may be rejected, ignored or show up as comments. Who knows!

Warren's Hack Make Do blog is followable at @blog.hackmakedo.com@blog.hackmakedo.com, or you can choose to follow the human @warrenbuckley@umbracocommunity.social.

Checkmarks

You might see some accounts with checkmarks in the names of accounts. These are simply custom emoji on the instance the account lives on and means nothing special. Some instances may restrict which accounts they allow to have a certain emoji, but there's no guarantee.

Bot accounts

Mastodon has a feature to clearly show whether an account is automated (a bot) or not. This isn't a bulletproof system - it generally relies on folks being honest about it. But if a profile displays a "Bot" or "Automated" flag (depending on the client you're using), don't expect a human reply if you get a reply at all!

@umbfyi@umbracocommunity.social is a bot account.

Link verification

The best way to tell if a profile is genuine is through checking for verified links. Umbraco's official account is a great example of this. Since we already trust umbraco.com to be owned by Umbraco, the fact that @Umbraco@umbracocommunity.social has a verified link for umbraco.com in their profile shows they have editorial control over that page. You can verify multiple links using the rel="me syntax in any page you can edit (your blog, Github profile, etc).

The first verified link shows up in search results on the default Mastdon client:

and all links, verified or not, show up in the bio, although the verified links show in green with a checkmark:

How to tell a user is genuine

So, in summary, to check you're interacting with the correct account:

Check for validated links
Do you trust the server?
Are they a bot?
Check their bio (sometimes they'll state they're unofficial)

What do we mean when we say “Umbraco”?

Joe Glombek — Thu, 07 Dec 2023 08:00:56 +0000

Spoiler: we don’t always mean the CMS.

If you’re reading this article, there’s a high chance you're acquainted with Umbraco, but perhaps you're not fully aware of the nuance that comes with the phrase. So what exactly do we mean when we say “Umbraco”?

The term encompasses more than just a CMS; it embodies a rich, open-source ecosystem consisting of the Umbraco CMS, the vibrant Umbraco Community, and our custodian and driving force, Umbraco HQ. Let's delve into all things “Umbraco” to uncover the multifaceted meanings and explore the intriguing interplay between these components.

“Unbrako” the contraption

Unbrako is the Danish name for an Allen key - that’s a “hex wrench” if you want the real name - and although to most of you reading this article this one is unlikely to cause any confusion Umbraco HQ say they do occasionally get Allen-key purchase requests. But that’s not really what this article is about!

Photo by Anton Savinov on Unsplash

“Umbraco” the CMS

According to Umbraco HQ (we’ll get onto that!):

“Umbraco is a CMS that’s fully extendable, highly customizable, and user-friendly.”

Umbraco CMS is the product all this “Umbraco” hangs off of. Created in 1999 by Niels Hartvig and open sourced in 2005, Umbraco has undergone significant transformations, evolving from a basic CMS to a sophisticated platform that powers websites of all sizes.

Umbraco has always (at least since I’ve been around) been pitched as “The Friendly CMS” which, as well as hinting at it’s user- and developer-friendliness and open-source nature, indicates how welcoming the community is. Community is a large part of what makes Umbraco, Umbraco. But it’s sometimes important to make the distinction between the two.

“Umbraco” the community

The first Codegarden in 2005 is our first indication of the beginnings of the Umbraco Community and it’s grown hugely from there. Communities often form around open source projects as people from across the world problem-solve and learn together to produce something that benefits themselves and other users, all with a shared philosophy for free (as in beer and as in speech) software. But I’ve heard Emma Burstow, Director of Developer Relations at Umbraco HQ, proudly state that people refer to Umbraco as “the one with the community”, which surely shows we have something special going on!

The Umbraco Community is also set apart from other software communities because of who make up our community. In a recent conversation with Carl Sargunar, he pointed out:

“Very unusually Umbraco isn’t a community of developers, it’s a community of people who use the platform”

The Umbraco Community is so much more than the occasional developer making the odd code contribution - it’s a lifestyle choice! And I only mean that partially as a joke! Codegarden, community-run conferences, unconferences, meetups, gaming sessions, social media, podcasts, a whole digital magazine, a federated social network instance, and even daily Wordle-sharing mean we’re never far away from our friends in the community.

Although largely developers, the community very actively includes agency owners, account and project managers, CMS administrators, end users and Umbraco HQ employees - the Umbraco Community is more about the lifestyle surrounding Umbraco than the code.

Repeat ~~offenders~~ contributors are acknowledged by Umbraco HQ through the MVP programme.

Umbraco community members call each other “Umbracians” (um-brak-ians or umb-raishe-ans).

“Umbraco” the company

Umbraco, Umbraco HQ, or just “HQ” is the name we use for the company, Umbraco A/S (and Umbraco, LLC in the US). HQ are the maintainers of the Umbraco CMS but also own the Umbraco commercial products Cloud, Heartcore, Forms, Commerce, Deploy, Workflow and UI Builder. They also monetize Umbraco through the sale of support plans.

HQ hires a developer relations team including developer advocates (also called developer avocados 🥑) whose role is to encourage and grow the community.

Members of staff at HQ are “HQers”.

Just to confuse things even more “HQ” can also refer to the physical office locations of Umbraco A/S and Umbraco, LLC.

Where paths cross

Community recognition

It surprises me how often a community-run conference, meetup or package gets attributed to Umbraco HQ or assuming organisers, speakers or community teams members are paid for their efforts.

Although I consider open-source as part of my job (and I’m lucky enough to have an employer who agrees), even I pour more emotional and time effort into community contributions than I do into the rest of my day job (it’s hard to get too emotionally invested in C#, eh?). And I’m one of the lucky ones: many community members are dedicating evenings and weekends to make their contributions.

The community can benefit itself by acknowledging non-profit community effort. Acknowledgement and appreciation go a long way to making a contribution feel worthwhile.

Not all heroes wear capes, but this one does have a shield. Photo by Umbraco HQ on Flickr.

But also, open source is work and employers who profit from the Umbraco CMS and community should do more to support their own employees’ contributions as well as sponsor open source packages and community events that directly benefit their business. Umbraco co-founder, community member and Director at Docker, Per Ploug, has written about this and his Codegarden talk is available to watch online.

Money for “nothing”

Umbraco CMS, being open source, is free to anyone who wants to download and use it. This makes things difficult for open source maintainers, like Umbraco HQ, who need to sustain a business while giving their primary product away for free.

Rumour has it people like free things. Photo by Umbraco HQ on Flickr.

Since 2021 Umbraco HQ has been owned by Monterro, a growth investor. Open source maintenance is an unusual business model, and since the Monterro investment, we’ve seen a larger push for commercial offerings from Umbraco but there remains a huge focus on open-source offering and the community.

Traditionally, open source maintainers make money by providing services and Umbraco HQ is no different. HQ sell Umbraco Cloud as a SAAS offering along with additional premium packages and support. Although Umbraco tends to avoid these situations, this business model can result in priorities misaligning with the community.

Community as a Commodity

It’s sometimes important to attach a business case to the value of a community to ensure a business like Umbraco HQ can continue to invest in their communities. And as pointed out by Emma Burstow, businesses are finally starting to see value in community because

“People are less inclined to buy things from sales people and far more likely to buy things from people like them”.

Are bats on a board a “commodity”? Photo by Umbraco HQ on Flickr.

However, the attitude of community members and their contributions being seen as commodities can be difficult for community members.

“Venture capitalists are actually using community activity as one of the metrics that they’re going to measure against before they acquire companies”

Contributions aren’t made to keep Umbraco HQ valuable and afloat, they’re made for the betterment of the open-source product, to encourage the progression of individuals within the community and to grow the community itself. But in doing so, contributors provide value to HQ. And although we all see value in Umbraco HQ doing well, a volunteer contribution benefiting a profitable company can feel uncomfortable.

It is important to comprehend that businesses understanding the value of community does mean that they can justify investing more time and money into fostering the community. And Umbraco HQ does put a lot of time and effort into fostering the Umbraco Community: Umbraco now has a dedicated developer relations team and fund community-run events. A strong community (as a commodity) can ensure their stewardship of the open source portions of the platform for many more years to come.

Accountability

“Stewardship” is an important word there. Umbraco HQ own the trademarks around the name Umbraco, but the CMS itself is in the public domain. Under the MIT License, people are free to “use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies” of Umbraco CMS. If Umbraco HQ ceased to be, or made a questionable product decision, the Umbraco CMS would likely continue to exist under a different name, possibly along with the community.

This has happened before, with the death of Umbraco 5, members of the community split off from Umbraco and created RebelCMS. The CMS was short-lived, with the last commit now almost 12 years ago, but it does show that it can be done.

This is an important thing to remember because, although it’s very unlikely to happen, it makes Umbraco HQ accountable to the community - they can’t do something strongly against what the community wants and need to listen to the community’s requests to keep their stewardship. This fact helps to ensure that community-effort, although benefiting Umbraco HQ, means that HQ’s profitability benefits the community, in a circular way.

A delicate balance

I don’t mean for this article to cause any controversy, but believe the discussion around profitability and open source is an important one and needs to be had out in the open. The Umbraco CMS can continue to provide a valuable product for both Umbraco HQ and the Umbraco Community, but it’s a delicate balance and as a community we need to acknowledge where conflicts of interest may arise.

As contributors we should know who our contribution benefits, and ensure we’re getting enough value for ourselves from that interaction to prevent feeling cheated or burning out.

It’s also vital that Umbraco HQ continue to recognise the value of the community in steering the direction of the Umbraco CMS.

Together, we’ve build something great and are continuing to build something even better.

Azure DevOps Pipelines breaks my "additional arguments" when using Deploy to Azure

Joe Glombek — Thu, 16 Nov 2023 12:21:55 +0000

Recently, something in the Azure DevOps Pipelines "Deploy to Azure" flow has been messing up parameters in the "additional arguments" field under "Additional Deployment Options".

We historically had parameters to skip the umbraco and umbraco_client folders:

-skip:objectname=filePath,absolutepath="\\(umbraco|umbraco_client)\\" -skip:objectname=dirPath,absolutepath="\\(umbraco|umbraco_client)\\"

However, somewhere along the lines, this was being corrupted to produce the following command:

msdeploy.exe [...] -skip:objectname=filePath,absolutepath="\\\(umbraco|umbraco_client)\\" -skip:objectname=dirPath\,absolutepath=\\(umbraco|umbraco_client)\\

And thus, the error:

##[error]Error: 'umbraco_client)\\' is not recognized as an internal or external command, operable program or batch file.

It looks like Pipelines is doing some of the work to escape backslashes (\) and double quotes (") itself but getting confused, removing some, and adding them back in all the wrong places!

We tried various variations of removing and escaping with different characters, trying to reverse-engineer what Pipelines was doing to our simple text string until Fernando suggested removing the (required) quotes altogether, which worked!

Additional arguments:

-skip:objectname=filePath,absolutepath=\\(umbraco|umbraco_client)\\ -skip:objectname=dirPath,absolutepath=\\(umbraco|umbraco_client)\\

Generated command:

msdeploy.exe [...] -skip:objectname=filePath,absolutepath="\\(umbraco|umbraco_client)\\" -skip:objectname=dirPath,absolutepath="\\(umbraco|umbraco_client)\\"

If anybody has any further insight into this, please do to get in touch via social media - I'd love to expand on the details here.

Umbrastodon: the Umbraco Community in the Fediverse and on Mastodon

Joe Glombek — Fri, 15 Sep 2023 02:29:11 +0000

A guide to getting started with Mastodon and the Fediverse tailored to the Umbraco Community.

Following on from discussions around how distributed our online communities have become since the ongoing fall of Twitter/X on Owain's blog and UmbraCoffee #292, Mastodon has been raised as one of the locations the community is slowly moving to. As an established Fediverse user, and admin of the UmbracoCommunity.social Mastodon instance, some people have been asking me Mastodon questions and I thought a blog post might be a good way to communicate these tips to a wider audience.

I've mentioned before how I hope Federation is the future of social networking and how Mastodon may well fit the needs of the Umbraco Community going forwards, and I truly believe we need something analogous to "old" Twitter, that's less instant than chat tools such as Discord, more social than the Forums and shorter form than blog posts. Mastodon can be just that.

What is the Fediverse?

This blog post is tailored to the Umbraco Community, so I won't go into all the details here, but will keep to the relevant parts.

The Fediverse is generally used to refer to a group of servers that conform to the ActivityPub standard. Each of these servers pushes content out to the Fediverse and wider internet. The content could be blog posts, microblogs, photos, comments or anything else we as people create on the internet.

These servers within the Fediverse are subcategorised by the software they run. The software is generally analogous with a "traditional" social media platform. For example, Mastodon focusses on microblogging (think Twitter), Pixelfed is all about social image sharing (think Instagram) and Lemmy hosts communities (think Reddit). You can follow a Lemmy community or Pixelfed account from your Mastodon account too - because they all use the same protocol.

What is Mastodon?

I've explained how Mastodon is the ActivityPub-compliant software running on a server., but the concept is much greater than that! Because the ActivityPub protocol allows these servers to talk to one another and because Mastodon is free and open source, you don't have to sign up to Mastodon's own server - you can join a community (server or instance) of your choice.

This can be a barrier to entry for those unsure about how Mastodon works, but in practice this architecture helps us build a more resilient and tailored social media platform.

Because Mastodon is distributed across multiple servers, usernames take the format @[local-username]@[server-domain], for example, my username is @joe@umbracocommunity.social.

Why does it fit so well with the Umbraco Community?

I've already used the phrases "open source" and "communities" when describing Mastodon, and this is a large reason I believe Mastodon could be a large part of the future Umbraco Community: our ethea align.

An Umbraco-focusses Mastodon instance allows Umbraco to be the primary focus of an instance with additional Umbraco-related content easier to discover for users. But the way that federation works, means that the common interests of Umbracian's on the Umbraco Mastodon also become discoverable by the community, such as .NET, open source and Lego.

How do I join?

So, if you want to become a part of the Fediverse, you first choose a server. It's not the be-all and end-all if you change your mind later, you can move (although your ~~Tweets~~ posts (or "Toots") don't come with you) your account to a different server at a later date (see below).

Which server(s)?

Mastodon instances tend to cater to interests. Although there are generic instances too.

The more generic and larger your instance, the closer to a Twitter experience you get. But that's not where the power of Mastodon lies, in my opinion you're better off joining a niche.

Personally, I find UmbracoCommunity.social a fantastic compromise - the community is niche enough to mean the public feed (see "Getting the most out of Umbrastodon") is relevant to me but not so small as to limit it, although as an admin there, I may be biased!

Popular interest-specific servers within the Umbraco Community

If a lot of what you do online is techy, these instances may work better for you:

UmbracoCommunity.social is a Mastodon server set up specifically for the Umbraco Community and is hosted by Steve Temple
Hachyderm, pronounced hack-a-derm (that's right, it's a mastodon/pachyderm pun!) is a hugely popular generic-tech instance
Fosstodon is dedicated to open source software
Infosec.exchange for you infosec folk
front-end.social for you frontenders

You can also find your own niche by checking the Mastodon server listing where you can filter by language, hosting country and interest.

Popular generic instances

From the UmbracoCommunity.social statistics, here are the most popular generic instances used by the Umbraco Community:

Mastodon.social is the original server operated by Mastodon, its hugely popular and a great place to start if you can't find a niche
mstdn.social another generic instance with a shorter URL
Mastodon.Green a paid-for server who run off renewable energy and plant trees with 20% of the monthly fee

Host your own

If none of these take your fancy, you can also host your own instance and be in full control of your own data - Seb has a server just for his account. Mastohost is a simple and affordable way to set up your own instance. Be aware, though, it can get lonely on your own - you lose a lot of discoverability by being on a single-person server.

Already a Mastodon/Fediverse user?

If you're already in the Fediverse but want more Umbraco in your feed, here are some options:

Use your existing Mastodon account and follow whoever you want from UmbracoCommunity.social by looking at the directory to find accounts
Create a second Mastodon account on UmbracoCommunity.social if you want to keep your Umbraco Fediverse account separate from your other account
Migrate your account to UmbracoCommunity.social. Your old account gets redirected, but beware your old posts will stay put.
Make use of the public feeds on UmbracoCommunity as it’s quite a good mix of Umbraco and .NET devs: the local feed (all posts on UmbracoCommunity instance) and the federated feed (all posts from people followed by anybody on the UmbracoCommunity instance). Some mastodon clients let you add these feeds into your app too!

Getting the most out of Umbrastodon!

As above, Seb suggests making full use of the use of the public feeds to find relevant content.
Make use of a browser plugin (like Graze for Mastodon) to make your web browsing experience of Mastodon easier
Find apps that works for you - I personally like Ice Cubes on iOS and Elk for desktop but the app directory has loads of options
Follow me! I'm @joe@umbracocommunity.social on Mastodon and @joe@expl.red on Pixelfed.

See you in the Fediverse!

Umbracadabra! Defence Against the Dark Arts of Magic Strings in Umbraco

Joe Glombek — Mon, 06 Dec 2021 09:00:00 +0000

I'm sure many of us have been told at some point in our careers that "magic strings are bad" but why exactly is that and what could go wrong? And what alternatives are there to improve our code?

Why are magic strings so bad?

We use the phrase "magic strings" (and, to a lesser extent, "magic numbers") to refer to a constant string used directly in your code. An example of this that we, as Umbraco developers, may be all too familiar with is Model.GetPropertyValue("bodyText"). Here, "bodyText" is the magic string. The text can be used in multiple places (maybe in the meta tags as well as the page body, or on different templates), has to be in this exact format (I can't swap it out with "Can I have the text for the body please?", as polite as that is) and refers to an external entity (the Umbraco database via the Umbraco APIs in this case). These things make it a particularly code-smelly example of a magic string that needs replacing.

Magic strings is a term used to cover multiple scenarios of when a string is used in place of a more robust method.

Typos: the arch enemy of magic strings. If we're having a particularly productive, Hollywood-hacker-style afternoon, smacking away at those keys, you'd be excused for mis-hitting the odd one.

Clip from NCIS showing two people typing manically on one keyboard

They can be particularly difficult to spot too: depending on your font, "bodyIext" could easily go unnoticed. The folks that write our IDE's know this, and will correct us where possible. A string, however, cannot be autocorrected because any value of string is a valid string. As far as the IDE knows, you meant to type "bossyTRex". These cause runtime errors rather than the easier-to-spot compile-time issues.

Fat-fingered-ness aside, magic strings can be exclusive to those who speak a different first language or people who have difficulty reading and writing. Even if you speak the same language issues can arise when trying to agree how to spell "colour"!

Or how about a piece of logic that sets this.ValidationMethod = "none". We then later decide we need to change the validation method, but it's not obvious what the other possible values are. Magic strings aren't self-documenting and so we rely on reference documents or "there's a comment that explains how to use it somewhere" or "didn't I put that in the README file". This is far from ideal.

And if all that wasn't enough, magic strings make it more difficult to replace a value, test your code or change logic on your test environments compared to production. We can do better!

Is there such thing as a muggle string?

Are there cases when a string is non-magic? Or perhaps when a magic string is ok? Yes, not all strings are magic strings and not all magic strings are nescessarily bad.

If you're typing a string value in code, the blog do you even code, bro? has boiled it down to 4 questions you need to ask yourself:

Can you reuse this constant?

Can you easily change a few values at once?

Does it improve readability?

Is it part of configuration?

This won't cover all scenarios, but it's a good place to get started. If any of your answers to these questions is "yes", it's time to look into alternatives.

Did you just casually drop the term "magic numbers" too? I've only just got to grips with magic strings!

Ah, yes. Sorry about that!

Yes, magic numbers are the lesser talked about sibling of magic strings. But they can cause the same sorts of issues.

Take this code as an example:

public void PrepareForCheckout() {
    if(Customer.Country == "United Kingdom") {
        FinalValue = Value * 1.175;
    }
}

It's not immediately obvious what this 1.175 is. You might have picked up that it's the old tax rate in the UK of 17.5%, but it could easily be missed, especially by a non-British developer.

Now that we know this is the VAT rate, we also know it's wrong. The UK changed their VAT rate to 20% a few years back. Correcting this value could be difficult too - we need to replace all instances, but if it's written as value = value + value * (17.5/100) (someone has gone about code clarity in an odd way!), a simple find-and-replace won't suffice.

If, for example, we had a constant of this value somewhere that we reference from everywhere, it would be both clearer what the code was doing and easier to update.

public void PrepareForCheckout() {
    if(Customer.Country == "United Kingdom") {
        FinalValue = Value * UkVatRate;
    }
}

Now, there are many other tweaks we could make to this code, but I've just solved the one we've been talking about.

ModelsBuilder to the rescue

The first example I gave in this article was Model.GetPropertyValue("bodyText"), which, back in the Umbraco 7-days of 2013, Stephan Gay aka ZpqrtBnk identified as a problem and developed the ModelsBuilder package. ModelsBuilder is now a part of Umbraco and if you're not using already, you really should be. It removes the need for magic strings when interacting with IPublishedContent across our Umbraco solutions by generating models for each document type. Dave Woestenborghs wrote an article on Getting started with Umbraco Modelsbuilder back in 2016 which still holds up well.

A constant problem

I mentioned creating a constant just now. And that's probably one of the simplest methods of avoiding magic strings. Depending on the size and complexity of your project, it can be as simple as pulling your strings up to constant declarations in your class.

public class Cart {
    private const string BodyTextKey = "bodyText";
    private const decimal UkVatRate = 1.175;

    //...
}

In .NET, constants (const declarations) are actually pretty efficient - at compile-time, they're not allocated any memory like variables are, so it's equivalent performance-wise to directly using the string in each location. It does, however, help us out a lot pre-compilation by removing the magic strings.

To make constants reusable across your project you might find it useful to create a Constants.cs file in your project and stick all your relevant strings in there. This can get pretty cluttered on bigger projects, so you may need to categorise your constants further, grouping them into logical classes and namespaces or adding your constants to related services like so:

public static class VatHelper {
    public const decimal UkVatRate = 1.175;

    //...
}

In fact, with a helper, we could go even further in case we need to apply VAT to other countries in the future:

public static class VatHelper {
    public decimal GetVatRate(string country) {
        switch (country) {
            case Countries.UnitedKingdom: 
                return 1.175;
            default:
                return 1;       
        }
    }
}

//...

public class Cart {
    private const string BodyTextKey = "bodyText";
    private const decimal UkVatRate = 1.175;

    //...

    public void PrepareForCheckout() {
        FinalValue = FinalValue * VatHelper.GetVatRate(Customer.Country);
    }

    //...
}

(OK, so in most real-world examples the country and it's respective VAT rate would probably both live in a database somewhere, but it works as an example!)

Enum-ber of other solutions

Constants are great and all, but they can get a little bit repetitive. Enumerated types (that's enums to you and me) are useful for a finite number of constants that won't change.

Enums are a great solution to our ValidationMethod setting we were talking about earlier. We could create an enum with all the possible values and use this enum in place of our strings:

public enum ValidationMethod {
    None,
    Required,
    EmailAddress,
    PhoneNumber,
    Numeric
}

//...

this.ValidationMethod = ValidationMethod.None;

//...

switch (field.ValidationMethod) {
    case ValidationMethod.Required:
        return !string.IsNullOrEmpty(field.Value);
        // ...
}

Enums also work well for statuses:

public enum OrderStatus {
    Draft,
    Paid,
    Pending,
    Shipped,
    RecievedByCustomer
}

//...

Order.Status = OrderStatus.Paid;

//...

if(Order.Status == OrderStatus.Paid) {
    ProcessOrder();
}

Magic numbers and enums

Under the covers, enums actually store integers for each value. In the case of our OrderStatus enum, Draft is equivalent to 0, Paid is 1, Pending is 2, etc. You can even explicitly set the number applied to each value which can be useful if you need to map a readable name to a number, or if you need to add a value to an existing enum.

public enum OrderStatus {

    /// We want to add a new status at the top,
    /// but also to maintain the mapping of the original enum
    /// so we specify the values

    Cancelled = -1,
    Draft = 0,
    Paid = 1,
    Pending = 2,
    Shipped = 3,
    RecievedByCustomer = 4
}

//...

/// Readable definitions for all possible
/// response codes from the ACME API docs
public enum AcmeApiResponseCodes {
    Ok = 200,
    BadRequest = 400,
    Unauthorized = 401,
    InvalidClientId = 490,
    ExpiredClient = 491
}

JSON and enums

As a side effect of the underlying value being an integer, you might notice that by default if you return an enum as a JSON result, you'll end up returning the number rather than the pretty enum.

{
    "orderNumber": 51138461315,
    "status": 2,

    "...": "..."
}

JSON (and JavaScript too, without some workarounds) don't support enums. So we have two choices here: return the number, or return the string. You've got a few options if you want to convert the enum to and from a string if you'd rather.

You can set the converter for your individual property with a simple attribute:

public class Order {

    public long OrderNumber { get; set; }

    [JsonConverter(typeof(JsonStringEnumConverter))]
    public OrderStatus Status { get; set; }

    //...
}

Alternatively, set the attribute it on the enum definition if you want it to be serialized to a string every time you use it. While we're here, you'll notice you can also customise how the enum is rendered as a string with the EnumMember attribute.

[JsonConverter(typeof(JsonStringEnumConverter))]  
public enum OrderStatus {
    Draft,
    Paid,

    //...

    [EnumMember(Value = "Recieved by customer")]
    RecievedByCustomer
}

Or finally, you can set the behaviour globally for all enums by modifying the ConfigureServices method in Startup.cs. We need to add AddMvcAndRazor to get ahold of the MVC config before adjusting the default JSON options.

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddUmbraco(_env, _config)

        // Here's the good stuff

        .AddMvcAndRazor(mvc =>
        {
            mvc.AddJsonOptions(json =>
            {
                json.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
            });
        })

        // That's all, folks!

        .AddBackOffice()
        .AddWebsite()
        .AddComposers()
        .Build();
}

Your configuration may differ slightly if you're using Umbraco 8 or below (with .NET Framework) or if you're using Newtonsoft.Json (rather than System.Text.Json) in your Umbraco 9+/.NET 5+ app, but the principles are the same.

Flagged enums

Simple enums work fine for things like statuses, where only one can be true at any one time. But how about where multiple values make sense?

Our ValidationMethod example from earlier applies here. It may be possible to have a field that needs validating as Required but also EmailAddress. With strings, we could have done this as an array and we can do the same with enums if we want...

// How we might have allowed multiple values with magic strings
field.ValidationMethods = new string[] { "email address", "required" };

// We can do the same when using enums too
field.ValidationMethods = new ValidationMethod[] { ValidationMethod.EmailAddress, ValidationMethod.Required };

But we can also do one better with flagged enums to allow an enum to have multiple values.

[Flags]
public enum ValidationMethod {
    None = 0,
    Required = 1,
    EmailAddress = 2,
    PhoneNumber = 4,
    Numeric = 8
}

//...

this.ValidationMethods = ValidationMethod.EmailAddress | ValidationMethod.Required;

//...

if(this.ValidationMethods.HasFlag(ValidationMethod.Required)) {
        return !string.IsNullOrEmpty(field.Value);
}

In this example, you can see we've added the [Flags] attribute to the enum and assigned each enum a value - this bit is important. We can then assign multiple values using the "bitwise OR operator" or pipe character (|) it's the same we use two of in an or statement ( this || that).

To check if an enum has a flag, we can use the HasFlag on the enum value. I've had to refactor our switch statement from earlier to use an if statement for each value we want to check for.

You might notice the integer I've assigned to each number isn't in order. Well, it is in order, but using a doubling sequence: 1, 2, 4, 8... etc. Each number is double the previous value. This is important because a flagged enum still only stores one integer!

It works by using bitwise operations (there's that word again) which, simply put, is looking at the individual "bits" (and I mean that in the technical term!) of a binary number and applying an "OR" operation - if any of the bits in that column is 1, it returns a 1, otherwise it returns a 0.

For those curious, let's look at the numbers in the doubling sequence in binary.


0000 (0)
0001 (1)
0010 (2[\*](#footnote))
0100 (4)
1000 (8)

...etc

You'll notice, that because they're all powers of 2, each column only ever contains a single 1. Therefore, no matter what combination we make of these in a bitwise OR, we can work out which initial enum values went into creating it.

var a = ValidationMethod.EmailAddress | ValidationMethod.Required;
/// That's 1 and 2
///
/// 0001
/// OR 0010
/// -------
/// 0011 (the last two columns have a 1 in the first number OR second number)

var b = ValidationMethod.Required | ValidationMethod.EmailAddress | ValidationMethod.PhoneNumber| ValidationMethod.Numeric;
/// That's 1 and 2
///
/// 0001
/// 0010
/// 0100
/// OR 1000
/// -------
/// 1111

In both examples above, to check the value has the flag Required, which is 0001, we simply need to check for a 1 in the last column - the HasFlag method is actually using the bitwise AND flag (&) under the covers which does this check.

this.ValidationMethods.HasFlag(ValidationMethod.Required);

// is the same as

(this.ValidationMethods & ValidationMethod.Required) == ValidationMethod.Required;

// is the same as

// Binary literals in C# are prefixed with 0b (C# 7+)
0b0000011 & 0b0000001 == 0b0000001;

/// 0011
/// AND 0001
/// --------
/// 0001 (the last column has a 1 in the first number AND second number)

Because of this behaviour, we can also add a value for common combinations or all into our enum by adding all the values of the combining values together (adding and bitwise operations provide the same result in this case because they're all powers of two, but not normally!)

[Flags]
public enum ValidationMethod {
    // Regular items
    None = 0,
    Required = 1,
    EmailAddress = 2,
    PhoneNumber = 4,
    Numeric = 8,

    //Combinations
    RequiredEmail = 3 // 0001 | 0010 = 0011 or cheat by doing 1 + 2 = 3
    All = 15 // 0001 | 0010 | 0100 | 1000 = 1111 or cheat by doing 1 + 2 + 3 + 4 + 8 = 15
}

Not that an "All" value makes any sense in this case, but it's good to know!

Config your way out of it

One of the questions we asked at the beginning was "is it part of configuration?" This is a good question to ask because it may well change how we deal with it. What is configuration? I like to think of anything that can alter an application's behaviour. This value will have been flagged (in a specification or by yourself) as something that's likely to change - be that in the future or per environment. A URL to an API endpoint is a good example of a configuration variable:

it sits outside the control of your application and could conceivably change
or you may want to point your staging site at a sandbox version of the API.

Now we're in the land of .NET 5, we can even get rid of some of the magic strings we have historically used to pull values out of config by mapping whole configuration sections to C# objects. I've also used a constant to get the configuration section name, to avoid that as a magic string.

public class AcmeConfig
{
    public const string Section = "ACME";

    public string ApiBaseUrl { get; set; }

    //...
}

//...

public class AcmeClient {
    public AcmeClient(IConfiguration configuration) {
        var config = configuration.GetSection(AcmeConfig.Section).Get<AcmeConfig>();

        //...
    }

    //...
}

Umbracadabra! Magic-less code

Hopefully I've been able to explain a little of why avoiding these magic strings might be necessary and how we can improve upon them. Don't go crazy - there's no need to replace every variable in your code, but its worth thinking about in the future each time you open those double-quotes!

Happy const-ing.. and enum-ing... and Model Building!

*There are 10 types of people in the world: those who understand binary and those who don't.

Why are you being such a git about it?

Joe Glombek — Tue, 05 Oct 2021 11:00:00 +0000

Are your git repos a dumping ground for code? I'm really fussy about how people use git - and that's a good thing. We'll take a look at branching strategies, the importance of commit messages and how often should you commit, anyway? Let's investigate how, with 5 simple tips, we can turn a code dump into a glorious archive of software and how this can save time, frustration and money.

Let's start really simple: what is git? Git is the most popular Source Control Management (SCM) system. It can ensure your code is backed up, versioned and accessible to other developers. Used properly, however, it can be so much more - helping ease complex processes such as release management, feature development and multiple people working concurrently.

I can, though, be a bit of a git about it: I'm really fussy about how people use git - and that's a good thing. I've worked with a fair few organisations and development teams over the years, and poor git utilisation is a more common issue than you might think. People use git as a dumping ground for code rather than a well-managed archive of software. Today we'll take a look at 5 simple tips which will, with any luck, improve your git practice.

0. Source Control yourselves

// Detect dark theme var iframe = document.getElementById('tweet-1432414619310739463-485'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1432414619310739463&theme=dark" }

This isn't one of the 5, but there are seriously some organisations out there not using SCM yet. SCM is not the same as a backup and if you've emailed some code to a colleague, you're probably doing it wrong!

For all the reasons I gave previously, SCM is essential for modern day software development.

Mercurial (hg), Team Foundation Version Control (TFVC) and Subversion (SVN) are all examples of SCMs but Git has really taken over in the software world and is the industry standard - I'd recommend it for that on its own: there's no point teaching your team a SCM system which is (or may become) redundant.

As for git clients, there are so many out there. Some like to use the command line - and that's great... if you're a git pro! But why overcomplicate? And there are times when being able to visualise the commit history in tree form can be a life-saver even for confident git-users. My favourite tree visualisation (and therefore favourite overall git client) is GitKraken (this is a referral link - I want a GitKraken t-shirt!). It's free for open source projects, but you'll need to pay for private repositories. I'll be using GitKraken for examples in this article as it's the client I'm most familiar with - but you can use any client you like but I'd strongly recommend not using a stripped-back client such as Visual Studio or GitHub Desktop as you get into more complex git usage and processes. If GitKraken isn't your bag, you may want to investigate Fork (also paid, available for Mac and Windows), Git Extensions or, at the very least, Oh My Posh and Windows Terminal.

1. Commit Messaging is everything

This xkcd comic highlights the problem perfectly.

I'd like to say that was just a joke in a comic strip, but it can be all too real...

// Detect dark theme var iframe = document.getElementById('tweet-1405424992121131010-204'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1405424992121131010&theme=dark" }

Imagine being in Dennis' situation and:

you've discovered a bug and you can't find the commit where it likely happened
you see something odd in the codebase, there's no comment so you use a blame/annotate tool to see who changed it and why... but Andy is on holiday and his commit message says "test" 😱
some piece of code has changed since you last saw it - why? You could revert it back to how you like it but maybe it was changed for a reason? You fire up the blame tool again, "Fixes date formatting issue in Chrome" - better leave it as it is! Saved by a good commit message!

Some people will tell you that good commit messages should be written as if answering the question "what does this commit do?" and that's good advice! Starting your commit message with a verb like "Fixes ...", "Reverts ..." or "Integrates ..." is a good practice too.

But these alone are not enough. "Fixes bugs" or "Reverts broken changes" are still useless. Detail, detail, detail!

GitKraken (and many other GUI git clients) give you two fields for your commit messages - a title and a description. It's best to keep your title short (GitKraken recommends 72 characters) but you can add even more detail in the description field.

You can even do this on the command line: git commit -m "Title" -m "Description"

Fixes date formatting issue in Chrome

Chrome always assumes the MM/DD format no matter what locale the browser is set to*

*it doesn't, this is just a made up example

Reverts new "Paytastic Checkout" checkout flow

Customer has changed their mind and wants to revert to using LegacyCart

Integrates SMS API

Sending an SMS to customers when their order ships using the "Simple SMS Sender" API

If you have a ticketing system or to-do list, it sometimes helps to include the title of the item in your commit and an ID or link to the initial issue can prove very useful.

GitKraken (and many other GUI git clients) let you hook up your issue tracker to your git repos so you can automatically stick an issue number into the branch name (and it'll therefore be in the merge commit too!)

2. Push Little and often

I've seen a lot of different tactics when it comes to how often people commit, but the most persuasive argument I've heard is for "little and often". Don't forget git acts as a backup of your work and progress. There's no point only committing when something is feature complete: what happens if your hard drive packs up overnight? Or you're off sick tomorrow and somebody else is left to pick up your work? It's far more useful to have partially complete work committed than not. Although it's generally good practice to ensure each commit is in a buildable state - it's ok if your work-in-progress (WIP) commits don't build.

You can also use your tiny commits to help you revert unwanted pieces of functionality, while it can be a real pain to pull small chunks of code out of a bigger commit.

Perhaps changing the colour-scheme to green text on a red background was a bit much...? It would have been all too easy to bundle "Change colour-scheme to green on red" in with "Reorder slides", but separating these out made it a lot easier to revert one of them at a later date.

3. Squash rackets

But don't all these "little and often" commits start to make a racket after a while? (See what I did there?) That's where squash and amend come in. As I mentioned, I'm a big fan of a WIP (Work -In-Progress) commit at the end of the day. But, come tomorrow morning and I've finished that small segment of work off, I don't want two commits "WIP - Restyle footer" and "Restyle footer". So I can amend my "WIP" commit to include all changes and rename it to "Restyle footer".

Or in the command line git commit --amend -m "Restyle footer". Atlassian has a great tutorial about rewriting git history from the command line.

If you want to combine multiple commits, or you've already committed your second round of changes, you can look into "squashing" the commits.

In GitKraken, this is done by selecting the multiple commits you want to combine, right clicking and selecting "Squash". There are some scenarios when squashing won't be available - in this case you might be best just leaving the history as-is!

If I'm doing some DIY at home, things can get pretty messy with tools and dirt around the place. Before I go to bed, I might do a quick tidy up but the next day, once I've finished the piece of work, all the tools go away and I vacuum up the mess I made. I'll definitely have it clean and tidy before I let anybody else in the house! Treat your branches the same way. It's OK for them to be a bit messy while you've got things in progress, but as soon as you're finished or ready to merge into a shared branch, you ought to tidy it up - nobody wants to see your messy branch!

One thing to note, though: don't squash your mistakes! Your mistakes and reworkings tell a story. It could provide valuable explanation to a future developer and documents your mistakes and learnings. Use amend and squash to tidy up, not to sweep under the rug!

4. A branching Strategy is key

There are many branching strategies out there and I don't really mind which one you use. My personal favourites are GitHub flow and Common Flow (or a combination of the two) but there are many more. Generally, these follow the feature-driven development pattern, with a branch for each feature and some notion of the state of a particular release (generally using branches or tags).

I also like to ensure only one person is committing to any single branch at one time - if two people are working on a feature, break that feature down into sub-features. This is the only way my "messy work-in-progress branch" method works!

GitHub flow, put very simply involves creating a branch for your feature (mapped to a GitHub issue), adding your commits to that branch and then opening a Pull Request. You discuss and review your code changes with your colleagues before deploying your changes for test. Once everyone is happy, your Pull Request is merged into the main branch. The GitHub flow tutorial goes into a little more detail.

It's worth noting that if none of these git flows make sense to you, you can take inspiration from them. I don't know of many companies who strictly follow any one particular strategy. So pick one as a baseline and adapt it for your organisation.

5. Rebase and merge - the best of both worlds!

Alright, so you've got your branching strategy and you've completed your feature - we're ready to merge!

But on larger projects with multiple concurrent workflows, you can end up with a real tangle of branches and merges.

So what other options are there for merging these features?

GitHub provides these 3 options on completion of a Pull Request:

Create a merge commit (which creates the mess you see above)
Squash and merge
Rebase and merge

Now, some people like to squash and rebase: your entire feature gets squashed into one commit and plopped straight onto the develop or main branch -it's kind of an extreme alternative to GitHub's "squash and merge". This is very neat and tidy, I'll give you that! However, you lose a lot of the documentation of when, how and why code changes were made. I'd much rather keep this history where we can.

Which leaves us with "Rebase and merge". This option allows us to avoid losing data while keeping the tree clean and tidy so is, of course, my favourite. (If you're using Azure DevOps, you can set this method as the merge type too - they call it a "semi-linear merge").

Rebasing is the act of "replaying" each commit in a branch (our feature branch) on top of the target branch (main or develop in this case) as if they were happening at this newer point in time.

As you can see, this method removes the muddle of criss-crossing merges, while maintaining the whole branch structure and all the detail in every commit. Each feature makes a neat "D" shape with the main or develop branch, with no crossovers.

You can also enact this process without a Pull Request utilising the individual tools rebase your feature onto main and then merge your feature into main in any git client of your choosing.

A note on rewriting history

Both tips 4 and 5 do something controversial in the git world: rewriting history. Not "rewriting history" as in the act of whitewashing a historical atrocity, but simply changing what's been pushed to the git repository (AKA history) after its happened (rewriting). Squashing, amending, rebasing and patching are all examples of git history being rewritten.

And I've just been actively advocating for 3 of these!

Maintaining your "true history" certainly has its merits: it can be useful for learning and code reviews. It's also impossible to mess up your history if you never tamper with it!

However, the way I see it is that this shouldn't at the cost of the readability of your repo. I prefer to maintain what I like to call my "feature history" where the order of our feature development is true, even if we're tweaking the timelines a little of when each feature was developed relative to each other.

I don't advocate for complete rewriting, just a quick tidy up.

As for that "risk" I mention when rewriting history, just make sure you've pushed your repository before you start messing with history. Then double check before your force push.

From code dump to stunning archive of software

And that's it. That's our stunning archive of software. We're source controlled with small incremental commits, each having a meaningful and detailed commit message sat comfortably in feature branches with no distracting noise and complicated merges. It reads easily from bottom to top, with no detail hidden or mistakes masked.

A clean history allows for features to be rolled back easily, while detailed commit messages create a better understanding of a repositories history leading to fewer mistakes and a branching strategy can clarify what code is deployed to which environment at any point in time. It's now plain to see how git discipline can provide benefits to developers, managers and the end client - saving time, frustration and money for all involved in a project.

I moved my website to Umbraco Cloud, this is how I got on

Joe Glombek — Mon, 21 Dec 2020 05:00:00 +0000

One weekend. One website. One rebuild.

I have a confession to make. Up until this weekend, my website was hosted on Squarespace.

This may seem counter-intuitive, for a software developer to use a service like Squarespace, but it made a lot of sense at the time. I needed a website fast while I was working full-time and didn't have the time or energy to build a site from scratch.

I've mentioned in the past how I'm not opposed to using third-party services where it makes sense, and this was certainly one of those occasions.

Squarespace is, however, not without its faults: accessibility is poor and there aren't many ways to improve it; the drag and drop designer is a pain when you want consistency and repetition; and my CV on the Squarespace site never looked quite right on mobile. So, combined with the fact that I'm an Umbraco developer without an Umbraco website, it was time for a change.

Trial signup

Investing evenings and weekends in building something I do for my day job has never really appealed to me, so I thought I might try out Umbraco Cloud. I like the idea of patch upgrades happening automatically and other upgrades possible without cloning locally. This means that going forwards I have less admin to do to keep my site up and up-to-date. Using Umbraco Cloud also meant that I'd have more recent practice using Cloud, so I was at least learning something from my endeavour (I haven't used Cloud since it was in preview and called UaaS!)

Signing up for the trial was fairly easy and promised 14 days to get my site in order before launching and paying for it. I had a repo up in no time.

Developing locally

Although Cloud allows fully-online development (more on that later), I'm stuck in my ways. So decided to try out developing the Umbraco site locally. Developing locally enables compiled libraries for custom helpers and extension methods and installing packages via Nuget (sorry, Umbraco Packages!) which is all good practice as far as I'm concerned.

Cloud is built around Git. Any changes you make are committed to Git and this automatically triggers a deployment to the Cloud site. In theory, this means working locally is as simple as cloning the URL Cloud provides and hitting run. But it's not quite that simple because Cloud runs ASP.NET Websites rather than their Web Application counterpart, meaning there is no Visual Studio Solution that's source controlled. Umbraco, therefore, provide UaaS.cmd to help simplify this process.

Foolishly, I initially only skim-read the documentation here before diving in. But after following the official guidance, this process was actually quite simple.

Then, after configuring my two (that's how it works!) git repos (and also setting up a mirror for the Umbraco Cloud repo because, although not necessary, I couldn't help feeling it was better practice somehow), I hit the run button...

Well, that didn't work. It's at this point I'd usually document the steps I went through to get it working properly but, in all honesty, I had no idea what I did to get it happy again. It was a bit of trial and error and likely specific to my setup, so we shan't dwell on this! The important thing is that it's working now!

Project setup

Let's take a moment to discuss the setup when developing locally.

UaaS.cmd sets up two Git repositories, one at the root (that you need to source control yourself) and one in *.Web (where * is the name of your project).

*.Web contains your Umbraco site as an ASP.NET Website (not Web Application - there is no .csproj file).

The root directory contains the solution file as well as a folder and csproj file called *.Core which, according to the docs, is where controllers, models, data access and extension methods should ideally live.

Models!?

Using ModelsBuilder is a bit of a pain. To get Intellisense working, the docs recommend using ModelsBuilder mode AppData (classes are generated upon request) or AppDataLive (classes are generated automatically when models change) and then overriding the path to place them in the App_Code folder, where they'll get compiled on the fly. This is quite clever. Visual Studio can pick these up automatically as ASP.NET Websites include files automatically (some of the time... it involves a lot of hitting the "Refresh" menu option) and they're compiled dynamically meaning you can change models on Umbraco Cloud (not developing locally) and they'll update dynamically.

However, this means that the *.Core project has no access to any ModelsBuilder models, which makes writing some of my common extension methods difficult. Normally I'd create a SiteSettings() extension method on IPublishedContent to get the settings node but, without access to models, I resorted to a generic method GetSite<Settings>() where Settings is the model for my Settings node.

public static T GetSite<T>(this IPublishedContent page) where T : class, IPublishedContent
{
    return page.Root().FirstChild<T>();
}

There are other options here but they all have their own downsides. You can the *.Core project altogether and put all your code in the ~/App_Code folder, but this means you miss out on any compilation ahead of time. You can also set your models to be generated within the *.Core project, but then you won't be able to utilise the ability to develop on the live site (more on that later). A third option may be (I've not yet tested it) to use the Dll or LiveDll ModelsMode (in the full version of ModelsBuilder) and reference the generated DLL in your *.Core project. This allows for development on the live site, but means you'll have to either manually generate models (Dll) or have site restarts every time you change a document type (LiveDll).

Website vs. Web Application

As indicated above, a website is mildly annoying to have as opposed to a web application. I've always seen applications as more superior, but the only reason I think this would be is because an application can generate DLLs, while websites can only have C# in the App_Code folder, where it's only compiled on application startup (think of it as the opposite of precompiled views).

Being a git about Git

And now, lets get onto the Git setup. This is a little weird. If you want to use Visual Studio to build your Umbraco site, the docs suggest you'll need two git repositories (although if you're feeling brave I'm sure you could use one and then use subtree or submodules and mirror to the Cloud repo... but that's a story for another day!): one for the *.Web folder, and one for everything else. The *.Web repo is hosted by Cloud (and is where it deploys from), while you'll need to create your own repo for the rest. Although I'm sure it's unnecessary, I also decided to mirror the Cloud repo because it feels like the right thing to do!

It's not really an issue, just a mild niggle. I'm sure someone more confident with Git than I could find a nicer way to handle this setup, but this one will do for now.

Umbraco Deploy

I've heard bad things about it but so far, for me, Umbraco Deploy has just worked. When Umbraco releases Deploy for non-cloud projects, I'm sure I'll have to do a full comparison between Deploy and uSync.Publisher, but for now I'm happy to use Deploy for Cloud and uSync for everything else.

Ability to develop on the live site! 🤠

I've always found the Settings area of Umbraco a bit odd, personally I'd rather do all my development within my IDE not partially in the browser. Working in a CI/CD world, I'd also have to disable the Settings section in any environment except locally.

But in Cloud, the Settings section makes so much sense for the simple reason that any changes you make on your Cloud environments and committed to the Git repo automatically. This makes my inner "cowboy coder" very happy. If I need to hotfix a live site, I can! If I want to tweak code from my phone, halfway up a mountain, I can! If I'm too lazy to open up Visual Studio to make a minor change to my personal site, I can!

Cloud is where Umbraco seems most at home, largely because of this.

Domain configuration... AKA 9 hours of downtime

I assume due to how Umbraco Latch works, domains will need to be configured to point to the Cloud site before an SSL certificate is generated. Unfortunately for existing sites, this means there will be a short moment of downtime while your domain points to a site with an invalid HTTPS certificate. However, in my case, basic authentication was not automatically disabled when I purchased my Cloud license (and by the time I realised it was too late!)

I decided to leave the setup overnight in the hope the problem would resolve itself with time, which it, unfortunately, did not. Support was, however, very helpful and resolved the issue quickly after I notified them of the issue.

Azure Web Apps allow domains to be preconfigured (with DNS text records) prior to mapping the domain, which may mean as Umbraco Cloud moves to Web Apps and uses Cloudflare in place of the existing Latch process for HTTPS, we may see an improvement here.

Umbraco cloud issues

I don't think it's unfair to say that Umbraco Cloud has a bit of a reputation when it comes to stability... and not a good one. And so far, I'm not helping that reputation, having already detailed an issue I had with my site not coming out of trial mode.

I did also experience a short amount of downtime on Saturday night.

But that's it so far. And support has been great at fixing the issues I have had.

I also had an issue with a bug in Umbraco Forms, which the support team fixed without having to delve into the database myself.

The price is right... sometimes

So who is this for? It's a question that's asked again and again. And I wasn't sure until I tried it properly myself.

I think the answer is, Umbraco Cloud is great for me. My use case is that I have a small low-traffic site which I don't want to have to invest huge swathes of time keeping patched and up to date, but I do want to quickly develop and launch new features.

It's not ideal for complex custom setups, or sites requiring "four-nines" of uptime. It might also outprice individuals or small charities. But for those in the middle, it seems to suit quite well. I won't be recommending Cloud to every client, but I think I now know who the target market is, and will recommend to those clients going forwards.

It will be interesting to see how the new planned infrastructure for Cloud will affect this target demographic and whether we'll see a more stable platform going forwards.

As for the relatively high cost vs self-hosting, I think this comes down to the quality and speed of the support team. If you consider the month price as a time-saver, it's easily worth it in my opinion.

How to set Windows Terminal as GitKraken's default terminal

Joe Glombek — Fri, 11 Dec 2020 06:34:00 +0000

GitKraken allows you to open the current repository in the terminal by hitting Alt + T but by default, this won't be the new Windows Terminal.

The new Windows Terminal has many benefits over the Command Line or Powershell applications but you won't find Windows Terminal as an option for the default terminal in GitKraken's settings.

There is a simple fix, however. Open up GitKraken's preferences (File > Preferences) and scroll down to and check "Use Custom Terminal Command" (below "Default Terminal" dropdown). Then, in the "Custom Terminal Command" field that appears above, enter:

wt -d %d

wt is the command for Windows Terminal, to which we're passing the -d directory parameter. The value of %d is then swapped out by GitKraken for the directory of the current repository.

It's as simple as that!

At the time of writing, there is a bug in GitKraken which launches the terminal twice when using the File > Open Terminal option, but Alt + T works just fine.

Taking Friendly to the masses

Joe Glombek — Thu, 10 Dec 2020 08:00:00 +0000

Umbraco is "The Friendly CMS" and, as a community, we aim to be warm and welcoming, greeting everyone we encounter with a Friendly high-five. But how can we inject some of this Friendliness into our work and make the websites we craft as Friendly as possible?

friendly

behaving in a pleasant, kind way towards someone

To be Friendly to everyone, we need to make sure everyone can use our websites. This simple concept is the whole premise behind, what may initially sound daunting, accessibility. Contrary to popular belief, accessibility isn't all about screen-readers, it's about the usability of your website to anyone, no matter their personal needs.

accessibility

the quality or characteristic of something that makes it possible to approach, enter, or use it

Accessibility of the Umbraco back-office has started to take shape over recent months: in any new Umbraco release, there’s been a whole section of the release notes dedicated to accessibility improvements. This has brought the concept of accessibility to more and more community members, but to some, an accessible website still seems like a distant pipedream - at best a low priority ticket on a backlog and at worst dismissed in the planning stages.

But I’m here to challenge that and show you how building a more accessible site is easier than you might think, whether you're a developer, designer or working in management, sales and delivery.

Accessibility as a priority

Of course, time and budget dedicated to making your website as accessible as possible is the best option and there are many reasons to do so, morally and financially.

We think of the web as open-access and a level playing field giving everyone access to the same information. And it is. For the most part. Building accessible websites is a very simple way to open up information and services to more people, ensuring people are not unfairly restricted by their circumstances.

It’s also important to remember that these are customers. Just as a shopkeeper wouldn’t put a barrier across their entrance only serving those who could jump it, why should a website put up these virtual hurdles for a percentage of potential customers?

I’m sure you’re all aware of the Domino's Pizza lawsuit that hit the US Supreme Court last year, but other big names like Nike, PornHub and Beyonce also got taken to court in America with other countries catching on. Web accessibility will soon be a must-have for all big corporations and any website built today should be taking this seriously.

It’s just UX

User experience (that’s UX to those in the know) designers pride themselves in designing great experiences for users (I guess the clue is in the name!) rather than something that simply looks good.

No surprises here, that this way of thinking generally includes those with access issues. As the word “accessibility” implies, this kind of UX doesn’t exclusively help those with specific needs - it’ll help everyone.

Any user of a shiny phone screen on a bright sunny day will appreciate high contrast ratios between text and the background, while any person who’s had an exhausting day will appreciate concise language and clear actions. Not to mention the 1 in 8 men who are colourblind (myself included) and the huge proportion of us who will develop motor, sight or hearing-related issues in later life.

Accessibility is vital for some and useful for everyone. Accessibility is a part of UX, so let’s be sure to embrace it and hold it in as high regard as visual appearance.

As a designer, thinking about how a user might interact with your design is a part of the job and accessibility fits right in with the other best practices you’re already following. There’s nothing extra here except a few additional things to think about and the more accessible designs you produce, the easier it becomes.

Coding is key

As developers, the way we code our sites makes all the difference. Even if there's no special budget set aside or we've received a design that hasn't fully considered accessibility (or there's no design at all!), we can still make all the difference.

It's not that different from coding without considering accessibility: just as we support browsers by writing valid markup, we can support as many people as possible by writing valid, semantic markup. The key to accessibility for developers is that actually, most HTML we write is probably accessible already. HTML renders in an easy to read and understand way and if we’re using the right semantic markup, it goes a long way to being understood by screen-readers too. It’s good practice to use the right elements for the right things: a nav for all navigation areas; main for the primary content of your site; header, footer and section elements for splitting up the page; and by using headings correctly*.

The trouble comes with JavaScript and CSS.

When styling, a good indication of breaking some bad practice is if you set a style to none or inherit. Browsers almost always have a reason for styling something a certain way, and if you’re undoing that it could make it harder to use.

Accessible accessibility tips

For you designers, developers and testers reading this, here are some of my top tips for starting on your accessibility journey. There is a lot more to learn out there (Jeffrey and Jorgen's article from 2015 is a good place to look for expanding your knowledge next) but this is a good place to get started.

I have 3 golden rules for styling accessibly.

1. Let me outline this for you

An outline is the browsers’ default way of showing focus - by removing this, it might make navigating your site by keyboard impossible! Consider changing the outline colour rather than removing it completely, or use some other clear styling to highlight focus.

2. Which links nicely onto...

By removing the colour and underline from a link, you make it less clear that the text is actually a link! Even changing a link from blue to any other colour can make navigation confusing to some users.

If you’re trying to make your link look like a button, you might confuse people even more.

3. Things that look like things they are not

Using elements for things they are not is another red flag. Using a link as a button or button as a link means the user doesn’t get the functionality they expect from that kind of element - links navigate you to somewhere else, while a button interacts with the current page. A checkbox is a form field, not a toggle for a menu.

It’s not necessarily wrong to use an element for something different, but it is a warning sign. So if you are, you should be sure to try using the component with a screen-reader (I recommend using NVDA over Windows Narrator - it's free and very popular) and only using keyboard navigation. If something is unclear or doesn't function as expected, use ARIA attributes and JavaScript to correct any confusing behaviour.

Don't label me a cynic

Moving on from styling, another really quick tip to make your site accessible is to label things. If an input has no label, or a section has no heading, consider adding one that's “visually hidden” or through aria-label. Similarly, if you have an icon with no text, it’s generally worth adding some text to help people understand its meaning (it might not be as obvious as you think), but if your design prohibits this, aria-label it!

Conversely, an icon that has no semantic meaning, can be aria-hidden so that it’s not read out by a screen-reader. An example of this would be an icon with a label next to it - the icon adds no additional meaning to the label, so a screen-reader doesn’t need to read it out.

Alternative thinking

Alternative text (alt attribute) on images have a couple of really handy uses. Firstly, if your image can't be loaded for whatever reason, it is replaced by the alt text to give an idea of the context it was meant to provide. Secondly, alt text can provide an audible description of the image for blind users and more clarity to a partially sighted user.

*A note on headings

Although it’s valid HTML to use an h1 per section, some screen-readers (as well as search engines) struggle to understand the structure of the content like this so it’s still considered best practice to use one h1 element per page.

In inconclusive conclusion

These are just a few pointers to start you on your accessibility journey. I'm by no means an expert and this is by no means all there is to know but I am keen to make my sites as accessible as possible and learning more every day, which I hope I have managed to rub off on you too! Don't hesitate to reach out to me if you have any accessibility queries or get involved with the Accessibility Team, we're all quite Friendly.

Easily open uSync Sync-Pack files

Joe Glombek — Tue, 16 Jun 2020 11:38:03 +0000

uSync Sync-Pack files (with the .uSync extension) are simply ZIP files and can be viewed in any ZIP viewer, including the one built into Windows.

One option is to rename your Sync-Pack to have a .zip extension and then open it as you would any compressed folder.

The other option, however, which is very useful if you’re looking inside uSync files more often, is to let Windows know that the .uSync file is a ZIP file and to treat it as such.

There’s no point-and-click setting for this like there is for associating a filetype with a program, because we’re doing something subtly different: telling Windows this file is a ZIP file.

All you need to do, though, is open a command prompt as administrator and run:

assoc .uSync=CompressedFolder

Integrate, don't imitate - when an API beats rolling your own

Joe Glombek — Wed, 06 May 2020 22:14:30 +0000

It wasn’t long ago that every agency and freelancer had their own custom CMS they’d use for client projects. We decided that was a bad idea. But we’ll often be seen writing custom code within that standardised CMS. Are we making the same mistakes again?

This blog accompanies my talk at the Thames Valley Umbraco User Group on 30 April 2020. I also have the slides for my talk available.

Let’s start with a couple of scenarios.

Scenario 1: John the roller coaster enthusiast

Meet John. He’s a rollercoaster enthusiast and he’s decided that he wants to ride a roller coaster at least once a week. He’s got a good budget and money is no object.

How could we solve his problem?

Option 1: Build a roller coaster in John’s back garden

We could recommend to John that we build a roller coaster in his back garden. This could be quite fun and he could ride the roller coaster as often as he liked, with no need to queue. But on the downside, the estimated cost of this solution is £2.5 million to £25 million (source: BBC).

Option 2: Go to a theme park

Alternatively, we could just recommend that he goes to his local theme park. He’d have his choice of various rides with no build-time, planning permission, health and safety, insurance, etc.

As for cost, a “premium season pass” at a well known theme park costs £85 (notice the lack of the word “million” as a suffix), plus the cost of fuel (which, no matter how far you’re travelling is negligible, again due to the lack of the “million” suffix).

I’ll let you decide which option to pitch to John.

Scenario 2: National Bushcraft Association website

Some of you may know about the time I lived in the woods for 6 months and taught wilderness survival skills to school children. So, I've created a scenario around the fictional National Bushcraft Association, a membership organisation for bushcraft instructors.

Members pay an annual fee to gain benefits such as networking, client referrals, news sharing capabilities and the obligatory newsletter. They want a Content Management System (CMS) with member management functionality to manage membership fees, expiry of unpaid memberships and mass mailing.

So the obvious solution?

Umbraco! That’s my go-to CMS, and I love working with it. Of course simply being my favourite CMS doesn’t justify the choice on its own, Umbraco is open source with an enthusiastic community meaning its free and actively developed. Umbraco will easily cover the requirement the Bushcraft Association has for content management. It also has a highly extensible membership management system.

The membership management functionality in Umbraco by default, however, is comparatively basic. So we’d need to build custom functionality to allow sending newsletters, membership payment and expiring members who haven’t paid.

But wait! Isn’t this the theme park scenario all over again; are we building a roller coaster? And if so, what are our other (“season pass”) options here?

As for membership management, there are dozens of pre-built systems available that have this down to a tee, and many of them have an API we could integrate with. A third party system would handle the membership fees, expiry and renewal reminders in the requirements, but also take GDPR off our hands and give us extra functionality to, for example, allow members to manage their own details and upgrade their membership tier as they need to, without phoning up the office team.

Similarly, a newsletter sending platform would handle sending newsletters and managing subscriptions and unsubscriptions as required while also handling GDPR and providing the Bushcraft Association with analytics.

In this scenario, I think building a basic CMS site and integrating with some third party services is the clear winner.

The problem solver mindset?

But where does this “backyard roller coaster” attitude in developers come from?

Personally, I think it’s due to the problem solver in us. We’re in this career because we like to solve problems and when someone gives us a brief we like to find an “ideal” solution, built exactly the way we think it should work.

As well as this, as a premium service provider, we might feel it’s our duty to build everything bespoke rather than “cheating” by using other people’s work.

It seems to take some maturity as a developer to realise we’re not taking the easy way out by using other people’s work, but standing on the shoulders of giants.

We’re all too keen to use open source packages to speed up development and provide our users with a better experience, so why not complete services too?

Benefits of integration

For us developers, integrating makes life less repetitive, I get to spend more time writing new code rather than making poor imitations.Being honest, I just find building integrations more fun; I don't get too excited about another document type or building another news page. Writing more in depth C# is more interesting to me!

But how do we sell an integration to higher ups, project managers or the client?

Over-delivery and extra features

Integrating with more complete systems can result in over-delivery. Third party systems likely have more features built into them over the years than you could do with the budget, the client’s going to get an industry-standard application, rather than the bare minimum.

Not to mention the fact that the client may get extra features “for free” as the third party developer continues to improve their application over time.

Less scope creep

Since a client is buying into an existing system, chances are they can trial that system before they commit to using it. Since the client knows exactly what they’re getting and has already taken part of the system for a test drive, the requirements are less likely to change, reducing scope creep.

Less support

Since you’re building less, it means you handle less of the support after launch. There can be positives to this for the client too such as a reduced retainer cost and perhaps a better response rate than your team could provide. This also means that the client is less reliant on you or your company in the future, which could go a long way towards easing their minds!

A solid platform

By buying into an existing ecosystem, some of your application has been built and tested already.

A balancing act

Of course, it’s not always as simple as integrating. If nobody built their own roller coasters, there wouldn't be a theme park to buy an annual pass for!

It wasn’t long ago that every agency and freelancer had their own custom CMS they’d use for client projects. We decided that was a bad idea. But equally, not every website should be built with Wix, Squarespace or Shopify. There’s often a trade off between bespoke and prebuilt. Every project needs an evaluation. Integration may not always be the answer, but it should always be considered.