opdavies/oliverdavies.uk-drupal
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
oliverdavies.uk-drupal/tools/scripts/daily.json

3686 lines
796 KiB
JSON
Raw Blame History

{
"emails": [
{
"title": "Make it easy",
"date": "1716940800",
"permalink": "/daily/2024/05/29/make-it-easy",
"text": "<p>What can you do to make your current task easier to achieve?<\/p><p>Can you refactor the existing code to make it easier to change?<\/p><p>Are there requirements that are no longer needed and can be de-scoped to make the code simpler or smaller?<\/p><p>Is there a more minimum-viable version that you can release now and iterate on it later?<\/p><p>Is there an existing solution, such as a library, module or plugin you can use instead of implementing it yourself?<\/p><p>Is there a different or simpler implementation that satisfies most of the requirements that you can use?<\/p><p>Taking an easier option means less code to maintain and a more stable application.<\/p>",
"cta": "d7eol",
"tags": ["software-development"]
}, {
"title": "Why is everyone moving to SQLite?",
"date": "1716854400",
"permalink": "/daily/2024/05/28/why-is-everyone-moving-to-sqlite",
"text": "<p>I've noticed a lot of Developers recently adopting SQLite for their database and I wonder why this is.<\/p><p>Laravel changed their default database to SQLite for local development.<\/p><p>It simplifies the development environment as there's no need for a separate database like MySQL or MariaDB but, if you'll be using one of those in production, won't that cause more issues when you migrate your local application?<\/p><p>Drupal supports using SQLite, but, other than for <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">my automated testing course<\/a>, or when running automated tests, I've always used a MySQL or MariaDB database.<\/p><p>Maybe this is something to keep an eye on and potentially use more for some scenarios in the future.<\/p>",
"cta": "d7eol",
"tags": ["software-development"]
}, {
"title": "Why do you still write Sass?",
"date": "1716768000",
"permalink": "/daily/2024/05/27/why-do-you-still-write-sass",
"text": "<p>Yesterday, I asked <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/26\/is-it-time-to-stop-writing-sass\">if it's time to stop writing Sass<\/a>.<\/p><p>If you still use Sass and are writing new styles with Sass, I'd like to know why.<\/p><p>Reply to this email and let me know.<\/p><p>I'm working on a project and migrating from the existing Sass styles to Tailwind CSS-generated utility classes, but with CSS custom properties (variables) and other Sass-like features now supported by browsers, writing vanilla CSS again is an interesting option.<\/p>",
"cta": "",
"tags": ["software-development","css"]
}, {
"title": "Is it time to stop writing Sass?",
"date": "1716681600",
"permalink": "/daily/2024/05/26/is-it-time-to-stop-writing-sass",
"text": "<p>I've seen a lot of recent posts that ask questions like \"Is it time to stop writing Sass?\".<\/p><p>I haven't written a Less or Sass stylesheet since I adopted utility classes and Tachyons, and then Tailwind CSS, and I moved to PostCSS.<\/p><p>But, with recent native browser support added for some Sass features, such as <a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/CSS\/CSS_nesting\">CSS nesting<\/a> and <a href=\"https:\/\/developer.mozilla.org\/en-US\/docs\/Web\/CSS\/Using_CSS_custom_properties\">CSS custom properties<\/a> (variables), people are considering moving from Sass to regular CSS.<\/p><p>Using regular CSS also makes it easier to onboard new Developers onto your project, which is particularly helpful in open-source projects, as <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/11-mark-conroy\">Mark Conroy and I discussed<\/a> on the Beyond Blocks podcast.<\/p>",
"cta": "",
"tags": ["software-development","css"]
}, {
"title": "Testing is a reusable skill",
"date": "1716595200",
"permalink": "/daily/2024/05/25/testing-is-a-reusable-skill",
"text": "<p>I like skills and technologies that I can re-use.<\/p><p>If there's a solution that's only available in one framework and another that is framework-agnostic, I'll use the agnostic one, if possible.<\/p><p>I'd rather invest my time learning something I'll be able to re-use and get the most benefit from.<\/p><p>Automated testing is an example of something re-usable.<\/p><p>Regardless of the CMS, framework or language, how to write and structure automated tests is the same, and you still get the benefits from writing them and\/or doing test-driven development.<\/p><p>Whilst the syntax can be different, even in the PHP space comparing PHPUnit, Pest and Behat, the fundamentals and approaches are the same.<\/p>",
"cta": "testing_course",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Don&#039;t put HTML in your body field",
"date": "1716508800",
"permalink": "/daily/2024/05/24/dont-put-html-in-your-body-field",
"text": "<p>I often see Drupal projects where people have put raw HTML code into their body or other rich-text fields.<\/p><p>Whilst it can be useful for short-term prototyping, I don't think it should be done for content that will be reused or kept for a period of time.<\/p><p>If you have structured HTML code in multiple nodes, you can't make changes without editing each instance.<\/p><p>What if you need to fix a bug and have hundreds or thousands of instances?<\/p><p>If you have inline styles, they won't be updated or affected by changes to your stylesheets, such as changing colour or font family.<\/p><p>Instead, create first-class components that use templates that are easier to change and maintain and have a single source of truth that adheres to your design system.<\/p><p>In Drupal, use structured data in fields with Paragraphs or Layout Builder and build the templates around them.<\/p><p>This makes it easier to maintain and also for people to add and edit content.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal"]
}, {
"title": "Why I use long parameter names in scripts",
"date": "1716422400",
"permalink": "/daily/2024/05/23/why-i-use-long-parameter-names-in-scripts",
"text": "<p>The other day, <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/21\/which-commit-has-the-largest-message\">I posted about a script I'd written<\/a> that found the longest commit message in a repository.<\/p><p>As I couldn't find a native way to do this with Git, the script loops over each commit in the repository, calculates its length and stores the length and commit SHA in a file.<\/p><p>The lines in the file are sorted so the longest commit is first.<\/p><p>Whilst I commonly use short parameters, such as <code>git add -p<\/code> when typing commands, in scripts, I prefer to use the equivalent longer parameters, where possible.<\/p><p>For example, in the script, I execute this command to sort the lines:<\/p><pre><code class=\"bash\">sort \"${result_file}\" --reverse --numeric-sort --output \"${result_file}\"<\/code><\/pre><p>This could be re-written as:<\/p><pre><code class=\"bash\">sort \"${result_file}\" -rn -o \"${result_file}\"<\/code><\/pre><p>Whilst the original is more verbose and longer to type, I prefer its verbosity which makes it easier for me or others to read and understand in the future.<\/p>",
"cta": "",
"tags": ["software-development","bash","zsh","linux"]
}, {
"title": "`git revert` is your friend",
"date": "1716336000",
"permalink": "/daily/2024/05/22/git-revert-is-your-friend",
"text": "<p>Imagine you've made a commit and want to undo it, or a particular commit is causing issues in production and you want to roll it back.<\/p><p>Instead of having to change it back manually, <code>git revert<\/code> can do it for you.<\/p><p>You specify the commit SHA you want to revert and Git will automatically try and revert that commit.<\/p><p>It creates its own commit message which includes the original commit message and <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/20\/referencing-other-commits-in-commit-messages\">the reverted commit SHA<\/a>, so you can easily find or navigate to the original commit.<\/p><p>For example:<\/p><blockquote> <p>Revert \"Sort talks only by the event date\"<\/p> <p>This reverts commit cbd1417b24a608df8b451a3ab5c9f888de41e758.<\/p><\/blockquote><p>Next time, instead of manually reverting a commit, give <code>git revert<\/code> a try.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Which commit has the largest message?",
"date": "1716249600",
"permalink": "/daily/2024/05/21/which-commit-has-the-largest-message",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/17\/why-i-dont-commit-with--m\">I write and advocate for others to write<\/a> detailed Git commit messages within the subject body to provide context and information about why the commit was needed, what other options were considered, any consequences or knock-on effects there could be, or even code snippets or pseudo code.<\/p><p>Recently, I was curious to know which commit in a repository has the longest commit message, what code has changed in that commit, and who wrote it.<\/p><p>I was hoping for a command like <code>git shortlog --summary --all<\/code> (which shows all authors to a codebase and their number of commits), but couldn't find one, so <a href=\"https:\/\/github.com\/opdavies\/git-commit-length-counter\">I wrote a script to do it<\/a>.<\/p><p>It's a bash script that loops over the commits in the repo, calculates the length of each message, sorts them and shows the commit with longest message.<\/p><p>It was an interesting task and shows examples of using various UNIX commands and Linux coreutils, such as <code>find<\/code>, <code>cut<\/code>, <code>sort<\/code> and <code>wc<\/code> in combination with Git.<\/p><p>The longest in this website's code base is <a href=\"https:\/\/github.com\/opdavies\/oliverdavies.uk-drupal\/commit\/cbd1417b24a608df8b451a3ab5c9f888de41e758\">546 characters<\/a>, which is fairly small compared to some of my messages in other projects.<\/p><p>What's the longest commit message in the repository you're working in?<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Referencing other commits in commit messages",
"date": "1716163200",
"permalink": "/daily/2024/05/20/referencing-other-commits-in-commit-messages",
"text": "<p>Last week, I asked <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/15\/should-you-include-issue-ids-in-your-commit-messages\">whether you should include issue IDs in commit messages<\/a>.<\/p><p>Another thing I like to reference in a commit message is the commit ID (or SHA) of a related commit.<\/p><p>For example, when I run <code>git log<\/code> in my website repository, I see commits like this:<\/p><pre><code class=\"plain\">commit 0c91825c16217d0fe7eff4ea100a67550051c4a9Author: Oliver Davies &lt;oliver@oliverdavies.dev&gt;Date: Sat May 11 15:32:07 2024 +0200 Create a cached talk counter Create a cached version of the talk counter service that returns a cached result of the talk count for that day. This uses the Decorator design pattern to decorate the existing `TalkCounter` service and works as they both implement the same `TalkCounterInterface`.<\/code><\/pre><p>The sha for this commit is <code>0c91825c16217d0fe7eff4ea100a67550051c4a9<\/code>.<\/p><p>If I was to make another commit that was related to this one, I can include this commit sha in my new commit message.<\/p><p>I also don't need to include the entire thing - only enough for it to be unique (usually five or six characters).<\/p><p>Once pushed, the commit IDs should never change, so this will be a permanent reference to the first commit.<\/p><p>Helpfully, websites like GitHub, GitLab and Bitbucket will identify it as a commit sha and make it clickable so you can easily navigate to the referenced commit.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Better commit messages means better pull requests",
"date": "1716076800",
"permalink": "/daily/2024/05/19/better-commit-messages-better-pull-requests",
"text": "<p>If you're working on a team or project that uses pull or merge requests, then <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/17\/why-i-dont-commit-with--m\">writing commit messages with detailed descriptions<\/a> using the message body and not just the subject line, will result in better pull requests.<\/p><p>Whatever text you put in the message body will be used as the description for your pull or merge request, as well as the subject line being used for the title.<\/p><p>So, instead of writing the message after completing the work, when you may forget important details, write it at the time in the message when writing the commit and re-use it in the PR or MR.<\/p><p>Pull or merge requests with more information and detail are more likely to be accepted and merged.<\/p><p>The text will also remain in the pull or merge request, even if <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/11\/don-t-delete-my-commit-messages\">someone squashes your commits and deletes the old messages<\/a>.<\/p><p>The issue then is, <a href=\"https:\/\/www.oliverdavies.uk\/daily\/2024\/05\/15\/should-you-include-issue-ids-in-your-commit-messages\">what if you move to a different Git hosting service<\/a>?<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Should you strictly enforce the 50/72 rule?",
"date": "1715990400",
"permalink": "/daily/2024/05/18/should-you-strictly-enforce-the-5072-rule",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/05\/17\/why-i-dont-commit-with--m\">Yesterday<\/a>, I mentioned the 50\/72 rule when writing Git commit messages.<\/p><p>The first line in the commit message is the subject line and should be no longer than 50 characters.<\/p><p>Any additional lines are the message body and should be wrapped at 72 characters.<\/p><p>As I said, I have Neovim configured to format my commit messages based on these rules, although they're more like guidelines.<\/p><p>There's no hard limit on the number of characters in the subject line or the number of characters in the body.<\/p><p>The commit will work and not be rejected when pushing to your remote repository.<\/p><p>There are likely post-commit <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/16\/what-are-git-hooks-why-are-they-useful\">Git hooks<\/a> to do this, but by default, things will work.<\/p><p>A commit message to Drupal core today was 178 characters long, including the issue ID and contributors.<\/p><p>When working on project teams, ideally, everyone would follow the 50\/72 rule, but if they don't consistently, I don't think it's an issue.<\/p><p>I'd rather they focused on writing a good and descriptive commit message and if it's formatted correctly, that's a bonus.<\/p><p>Whilst I could automate checks for this, I don't think it's the best use of everyone's time and, especially for Junior Developers who already have enough to learn already, not where their focus should be.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Why I don&#039;t commit with -m",
"date": "1715904000",
"permalink": "/daily/2024/05/17/why-i-dont-commit-with--m",
"text": "<p>A lot of tutorials show using <code>git commit -m<\/code> to create commits using an inline message.<\/p><p>I don't do that, though.<\/p><p>Using the <code>-m<\/code> option to specify an inline commit message encourages writing short one-line commit messages instead of using the subject and body effectively to document more about the change, such as why it was needed, any other approaches taken and the consequences of the change within the commit.<\/p><p>Alternatively, people could write a longer commit message in one line and not follow the 50 character limit for the subject line.<\/p><p>Whilst it's possible to write multi-line commits on the command-line, I use my editor (Neovim) to write my commit messages.<\/p><p>I can write as much information as I need, I have coloured columns for the 50 character subject limit and the 72 characters for wrapping the body message and, if I write more than that, it will either wrap for me, or I can format the message for it to be compliant.<\/p><p>These are rules that aren't also enforced in some Git tools, so I prefer knowing my setup is configured correctly.<\/p><p>Though, whether you use <code>-m<\/code> or not, capture as much information in the message as you can, as future Developers on the project (including you) will thank you for it.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "The first test is the hardest",
"date": "1715817600",
"permalink": "/daily/2024/05/16/the-first-test-is-the-hardest",
"text": "<p>Whether you're writing tests before the implementation code or not, the first test is always the hardest to write.<\/p><p>What will the arrange and act phases look like?<\/p><p>What dependencies will you need?<\/p><p>What do you need to mock or create fakes of?<\/p><p>In a Drupal test, what other modules and configuration do you need to install?<\/p><p>What installation profile and default theme do you need to use?<\/p><p>What other unknown or complicated setup steps are there?<\/p><p>Do you need to configure your environment to run the tests and get the expected output?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>The hardest part is getting the arrange\/setup phase working and getting to when the test is running your business logic.<\/p><p>Once you've got the first test running, adding more for similar use cases will be much easier.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","automated-testing","test-driven-development"]
}, {
"title": "Should you include issue IDs in your commit messages?",
"date": "1715731200",
"permalink": "/daily/2024/05/15/should-you-include-issue-ids-in-your-commit-messages",
"text": "<p>It's shown in the examples of the <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/11\/24\/are-conventional-commits-worth-it\">conventional commits specification<\/a> as part of the optional footer data.<\/p><p>But is it useful?<\/p><p>It can be if your issue tracker is linked to your Git repository and you can click the issue ID in a commit message and see the issue.<\/p><p>But, how often do teams change issue-tracking software or the project is passed to a different company that uses a different issue tracker?<\/p><p>That makes the issue IDs that reference the old IDs useless as no one has access to the issues it references.<\/p><p>I'd recommend putting as much information in the commit message itself and not relying on it being in an external source, like an issue tracker.<\/p><p>The Git log and commit messages will remain even if a different issue tracker is used, or a different team starts working on the project, and that additional information isn't lost.<\/p><p>I'm not against putting the issue ID in the commit message but don't do it instead of writing a descriptive commit message.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Free code reviews",
"date": "1715644800",
"permalink": "/daily/2024/05/14/free-code-reviews",
"text": "<p>Do you want to contribute to open-source software, such as Drupal core or one of the thousands of modules or themes?<\/p><p>Are you worried about receiving negative comments or feedback?<\/p><p>Instead, think of it as free code reviews.<\/p><p>Contributing to open-source is a great way to gain experience and learn from other Developers, and something that I still do often, 17 years after starting to develop software.<\/p><p>I'm also happy to review people's open-source for free. If that would be of interest, reply and let me know.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "DrupalCamp Ghent",
"date": "1715558400",
"permalink": "/daily/2024/05/13/drupalcamp-ghent",
"text": "<p>Last Friday and Saturday, I was happy to attend and present two sessions at DrupalCamp Ghent in Belgium.<\/p><p>I was able to present talks on automated testing and Tailwind CSS, which were my 99th and 100th talks, respectively!<\/p><p>The sessions were streamed live, or the slides and previous recordings <a href=\"https:\/\/www.oliverdavies.uk\/dcg\">are on my website<\/a>.<\/p><p>It was a great event and it's always nice to see and meet new people within the Drupal community, to see new places and share knowledge by giving presentations.<\/p><p>Reply and let me know if you have any feedback on the sessions or if you'd like me to present a talk or workshop at your event.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","drupalcamp"]
}, {
"title": "Merging without merge commits",
"date": "1715472000",
"permalink": "/daily/2024/05/12/merging-without-merge-commits",
"text": "<p>Since I posted about <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/05\/10\/optimise-for-revertability\">optimising for revertability<\/a>, I've received a few questions about how I avoid merge commits when working with Git.<\/p><p>This is an extract from my <code>.config\/git\/.config<\/code> file:<\/p><pre><code class=\"ini\">[merge] ff = \"only\"[pull] ff = \"only\" rebase = true<\/code><\/pre><p>This changes the behaviour of when I run <code>git pull<\/code> to always include <code>--rebase<\/code> by default and to only allow fast-forward merges and pulls.<\/p><p>Only allowing fast-forward merges avoids merge commits as Git can just move the pointer for the branch to the latest commit.<\/p><p>If I can't do a fast-forward merge, I need to rebase first to update everything and bring it up to date.<\/p><p>Sometimes, when working in team, merge commits will still creep in sometimes and there are situations where you can only create a merge commit.<\/p><p>In this situation, I can do <code>git merge --ff<\/code> to allow a merge commit temporarily, but this is the exception instead of the default.<\/p><blockquote> <p>Hint: there's a lot more information on the configuration and arguments if you run and read <code>man git-merge<\/code>.<\/p><\/blockquote><p>When working with online tools such as GitHub and GitLab, I avoid any options like <code>Squash and merge<\/code> or <code>Create a merge commit<\/code> and will use rebase options, although I've seen where different commit IDs have been generated when merged in the UI, which is why I prefer to do merges locally.<\/p><p>Or use <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/06\/17\/avoid-git-merge-hell-with-trunk-based-development\">trunk-based development<\/a> and don't work on topic branches at all.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Don&#039;t delete my commit messages",
"date": "1715385600",
"permalink": "/daily/2024/05/11/don-t-delete-my-commit-messages",
"text": "<p>Another reason I don't like squashing commits within pull\/merge request is losing detail within the commit messages.<\/p><p>As someone who usually writes detailed commit messages that explain why the change is being made, any gotchas or alternative approaches that were tried, etc, I want that information to be retained.<\/p><p>Previously, when working on a team and doing merge\/pull requests, when merging a feature or release branch, either the tool or reviewer would delete all the messages from the squashed commits.<\/p><p>The time I spent writing the messages was wasted, and the information was lost.<\/p><p>I'd rather <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/05\/10\/optimise-for-revertability\">keep the original commits intact<\/a> but, if you need to squash commits, please don't remove the previous messages as they could be useful in the future.<\/p><p>People can see the changes by viewing the commits, but the information within the commit messages are valuable, too.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Optimise for revertability",
"date": "1715299200",
"permalink": "/daily/2024/05/10/optimise-for-revertability",
"text": "<p>There are two things I avoid when merging changes in Git.<\/p><p>Merge commits and squashing commits.<\/p><p>Both make it hard to revert changes if needed once they've been merged, such as a major bug in production and you quickly need to roll back.<\/p><p>Merge commits are difficult to revert and if a commit has been squashed into one larger commit, you can't revert it without also reverting everything else.<\/p><p>Working with small, unsquashed commits makes it simple to revert a specific one and only that one.<\/p><p>If I need to revert something, I want to be able to do as simply and specifically as possible.<\/p><p>Optimise for revertability.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Do you have a deadline?",
"date": "1715212800",
"permalink": "/daily/2024/05/09/do-you-have-a-deadline",
"text": "<p>Does your task or project have a deadline for completion?<\/p><p>Is there a date that it must be completed by?<\/p><p>Or, is your \"deadline\" an arbitrary date that can be moved?<\/p><p>If so, you don't have a deadline.<\/p><p>You have a goal.<\/p><p>Understand and be clear whether you have a fixed deadline or a flexible goal.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Assertions aren&#039;t just for tests",
"date": "1715126400",
"permalink": "/daily/2024/05/08/assertions-arent-just-for-tests",
"text": "<p>If you've written or seen automated tests in PHP, you'll have seen lines like this:<\/p><pre><code class=\"php\">self::assertTrue(FALSE);<\/code><\/pre><p>But, did you know assertions can be used outside of tests.<\/p><p>PHP has an <code>assert()<\/code> function that can be used anywhere.<\/p><p>For example, if I had this code:<\/p><pre><code class=\"php\">$node = Node::load(1);assert($node instanceof NodeInterface);assert($node-&gt;bundle() === 'page');<\/code><\/pre><p>I know <code>$node<\/code> is a node with the correct bundle type and I can continue.<\/p><p>I've made my assumptions explicit.<\/p><p>If <code>$node<\/code> is not the correct type or returns an unexpected bundle, the assertion will fail and an Exception will be thrown.<\/p><p>I think this is better than assuming or hoping the values are as you expect, and it also makes the intent of the code much easier to see and understand.<\/p><p>If you haven't tried <code>assert()<\/code> before, give it a try.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","automated-testing"]
}, {
"title": "Drupal 7.100.2",
"date": "1715040000",
"permalink": "/daily/2024/05/07/drupal-7-100-2",
"text": "<p>In <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/04\/30\/will-we-see-drupal-7-100\">April 2023<\/a>, I wondered if we'd see a 7.100 release of Drupal.<\/p><p>I just noticed that we did.<\/p><p>It was released on the 6th of March.<\/p><p>From the release notes:<\/p><blockquote> <p>Maintenance release of the Drupal 7 series. Includes bug fixes and small API\/feature improvements only (no major, non-backwards-compatible new functionality). Unusually, this release does include a new core module.<\/p><\/blockquote><p>This is also the first Drupal release to be affected by the Year 2000 problem, a.k.a. the Y2K problem, or the Millennium Bug:<\/p><blockquote> <p>Note that this is the first Drupal 7 release with 3 digits. If you receive a report that your version of Drupal is over a decade out of date, see https:\/\/en.wikipedia.org\/wiki\/Year_2000_problem.<\/p><\/blockquote><p>According to the usage figures on Drupal.org, there are at least 316,843 active Drupal 7 websites and, with only 243 days left until D7 is end-of-life, hopefully most of them will be upgrading to Drupal 10 (or 11) soon.<\/p><p>If you're stuck on Drupal 7, I can help! Reply to this email and let's start a conversation.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "Interactive staging",
"date": "1714953600",
"permalink": "/daily/2024/05/06/interactive-staging",
"text": "<p>A major addition to my Git workflow has been the ability to interactively add hunks of code to be committed.<\/p><p>There's <code>git add -i<\/code> to interactively add, though I usually go straight to <code>git add -p<\/code> to use <code>patch<\/code>.<\/p><p>This will ask you to confirm if you want to add each hunk to the commit (a.k.a. the staging area) or not.<\/p><p>For example, here's the prompt I get whilst working on the post for this email:<\/p><pre><code class=\"shell\">diff --git a\/source\/_daily_emails\/2024-05-06.md b\/source\/_daily_emails\/2024-05-06.mdindex 42fe48f..ef36a2b 100644--- a\/source\/_daily_emails\/2024-05-06.md+++ b\/source\/_daily_emails\/2024-05-06.md@@ -4,10 +4,12 @@ date: 2024-05-06 permalink: daily\/2024\/05\/06\/interactive-staging tags: - software-development- # - drupal- # - php- # - podcast+ - git cta: ~ snippet: | TODO ---++A major addition to my Git workflow has been the ability to interactively add hunks of code to be committed.++There's `git add -i` to interactively add, though I usually go straight to `git add -p` to use `patch`.+There's `git add -i` to interactively add, though I usually go straight to `git add -p` to use `patch`.(1\/1) Stage this hunk [y,n,q,a,d,s,e,?]?<\/code><\/pre><p>I can add the whole hunk, split it into smaller hunks, add all the hunks in the file or ignore this hunk and later hunks in the file.<\/p><p>Then the process is repeated for any following hunks.<\/p><p>This means I can add the relevant hunks to craft the commit I want and I can keep my commits small and meaningful, and easy to revert if there is an issue.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Making PHPStan stricter",
"date": "1714867200",
"permalink": "/daily/2024/05/05/making-phpstan-stricter",
"text": "<p>Continuing yesterday's thought on <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/05\/04\/strict-typing-in-php\">strictness in PHP<\/a>, today I want to talk about adding more strictness to PHPStan.<\/p><p>Adding the <a href=\"https:\/\/github.com\/phpstan\/phpstan-strict-rules\">PHPStan Strict Rules extension<\/a> makes PHPStan stricter by adding new, more opinionated rules.<\/p><p>For example:<\/p><ul><li>Require booleans in if, elseif, ternary operator, after !, and on both sides of &amp;&amp; and ||.<\/li><li>Use the <code>$strict<\/code> parameter with <code>in_array<\/code>, <code>array_search<\/code>, <code>array_keys<\/code> and <code>base64_decode<\/code>.<\/li><li>Disallow empty().<\/li><li>Require calling parent constructor.<\/li><\/ul><p>You can enable and disable rules as needed but, like setting the PHPStan level, ideally I like to enable them all by default and see how strict I go.<\/p><p>It depends on the code being tested and the preference of the team, though I find the stricter the rules, the less bugs there are.<\/p>",
"cta": "",
"tags": ["software-development","php","phpstan"]
}, {
"title": "Strict typing in PHP",
"date": "1714780800",
"permalink": "/daily/2024/05/04/strict-typing-in-php",
"text": "<p>I prefer writing and working with strictly typed code.<\/p><p>One of the major improvements in PHP has been the option to enable strict types.<\/p><p>For example, this code will usually not error and give the result:<\/p><pre><code class=\"php\">function add(int $a, int $b): void{ var_dump($a + $b);}add(1, '1');<\/code><\/pre><p>However, I'd prefer if it failed as I'm passing the function an integer and a string, but specifying they should both be integers.<\/p><p>Fixing this is simple, by adding this line to the top of the file:<\/p><pre><code class=\"php\">declare(strict_types=1);<\/code><\/pre><p>I add this to every PHP file by default.<\/p><p>I want my code to be as strict and predictable as possible, and to error when I want it to and make any bugs more explicit and easier to find and fix.<\/p>",
"cta": "",
"tags": ["software-development","php"]
}, {
"title": "Don&#039;t add boolean arguments",
"date": "1714694400",
"permalink": "/daily/2024/05/03/dont-add-boolean-arguments",
"text": "<p>A convention I like from the Laravel framework is to avoid adding boolean arguments to methods.<\/p><p>For example, if I have this function:<\/p><pre><code class=\"php\">public function getPosts() { ... }<\/code><\/pre><p>If I wanted to only get published posts, one way would be to add a boolean argument:<\/p><pre><code class=\"php\">public function getPosts(boolean $onlyPublished) { ... }<\/code><\/pre><p>Then, I'd need to use that within the method body to add another condition (this is referred to as control coupling, where one method affects another).<\/p><p>The non-boolean approach would be to create a separate method with its own distinct name.<\/p><p>For example, <code>getPosts()<\/code> could be named <code>getAllPosts()<\/code> and there could be a separate <code>getPublishedPosts()<\/code> method for only getting published posts:<\/p><pre><code class=\"php\">public function getAllPosts() { ... }public function getPublishedPosts() { ... }<\/code><\/pre><p>Whilst we have two methods now instead of one, it's much clearer what each does and there aren't any random <code>true<\/code> or <code>false<\/code>s wherever the method is used.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Re-evaluating old tools",
"date": "1714608000",
"permalink": "/daily/2024/05/02/re-evaluating-old-tools",
"text": "<p>It's been a while since I used Ansible.<\/p><p>I used it for automating infrastructure and deploying applications.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\">I gave a talk about it<\/a> on several occasions, including remotely for the Ansible London meetup during COVID.<\/p><p>I haven't had to use it recently but, today, I <a href=\"https:\/\/github.com\/opdavies\/oliverdavies.uk\/commit\/cd6575c6fcc091a0b7c98b6985b3a92b85e279e3\">brought it back<\/a> out of my toolkit.<\/p><p>I was reviewing how I manage my website's configuration and files and Ansible seemed to be a perfect choice.<\/p><p>The files need to be uploaded to the server and, to handle redirects, I also have a custom NGINX virtual host configuration that needs to be uploaded if I change it and the NGINX service reloaded.<\/p><p>Ansible is a great tool for this type of task and, just because it's a tool I haven't used it for a while, that doesn't mean I can't re-evaluate it and see if fits my current requirements.<\/p><p>It's still in my toolkit, just in case I need it.<\/p>",
"cta": "",
"tags": ["software-development","devops","ansible"]
}, {
"title": "Broken pipeline? Fix or revert it.",
"date": "1714521600",
"permalink": "/daily/2024/05/01/broken-pipeline-fix-or-revert-it",
"text": "<p>If you're doing trunk-based development where multiple people are committing and pushing work to the same branch, what do you do if you've pushed a commit that fails the checks and breaks the pipeline?<\/p><p>This is a bad state and needs to be solved as soon as possible as it's causing a problem for everyone else.<\/p><p>If the pipeline is failing, someone else could push a change and have it fail for a different reason, but wouldn't know.<\/p><p>The responsibility is on the person who pushed the failing commit to resolve it and get the pipeline passing again as soon as possible.<\/p><p>You break it, you bought it.<\/p><p>Hopefully, the changes in the failing commit are small and it's something you can resolve quickly and push a fixed commit.<\/p><p>If you can't fix it within a few minutes, revert the failing commit and try again.<\/p><p>What if someone's pushed a failing commit and hasn't fixed it in a timely manner?<\/p><p>Revert it for them, fix the pipeline and unblock the rest of the team.<\/p>",
"cta": "",
"tags": ["software-development","continuous-integration","trunk-based-development"]
}, {
"title": "Stepping back into debugging",
"date": "1714435200",
"permalink": "/daily/2024/04/30/stepping-back-into-debugging",
"text": "<p>In PHP, we have functions like <code>var_dump()<\/code>, <code>dump()<\/code> and <code>dd()<\/code> that are used to debug code and print output to the screen.<\/p><p>In Drupal, we have functions like <code>dpm()<\/code> and <code>kint()<\/code>, too.<\/p><p>These functions are great for simple debugging but sometimes I need more, which is when I reach for a step debugger - namely, Xdebug.<\/p><p>This is common when working in complex legacy code, where you need to be able to see a breakpoint and step through the code to see what path it takes and what the state is at each step.<\/p><h2 id=\"enter-xdebug\">Enter Xdebug<\/h2><p>Xdebug is a tool I use fairly often and something I have configured on an individual project basis.<\/p><p>This week, I spent some time adding it to a new project and ensured my notes and documentation still worked.<\/p><p>I use Docker and Docker Compose on Linux, so there are slight changes compared to running PHP natively, so I wanted to make sure it still works.<\/p><p>I've added my latest setup to my <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal\">Drupal Docker Example repository<\/a> and plan to add it to my standard <a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">Build Configs<\/a> setup for Drupal projects.<\/p><p>If you use Docker Compose on Linux, it may be useful for you.<\/p><p>If you haven't tried Xdebug before, I suggest giving it a try and see if improves your debugging.<\/p>",
"cta": "",
"tags": ["software-development","php"]
}, {
"title": "Some kind words",
"date": "1714348800",
"permalink": "/daily/2024/04/29/some-kind-words",
"text": "<p>I recently received these kind words from Frank Landry, who recently completed my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">Drupal automated testing email course<\/a>:<\/p><blockquote> <p>The course was very informative.<\/p> <p>One of the biggest pain points with Drupal testing was that there was no clear and definitive guide on setting up the php unit XML file to get functional and kernel tests working right away.<\/p> <p>Your guide was fantastic and I will definitely be using it going forward in my module development for work.<\/p><\/blockquote><p>Thanks, Frank, for your feedback.<\/p><p>It's great to get feedback on my content and to know it's helping and providing value to people.<\/p>",
"cta": "atdc",
"tags": ["software-development","drupal","automated-testing","test-driven-development"]
}, {
"title": "Replicating a bug with a test",
"date": "1714262400",
"permalink": "/daily/2024/04/28/replicating-a-bug-with-a-test",
"text": "<p>When fixing a bug, can you write a new failing test to replicate the bug?<\/p><p>If so, you verify the bug exists, you know when it's fixed (the test passes), and you know you won't introduce the same bug again - otherwise, the new test will fail.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing"]
}, {
"title": "Can you make a test fail?",
"date": "1714176000",
"permalink": "/daily/2024/04/27/can-you-make-a-test-fail",
"text": "<p>Can you make an automated test fail when you want it to?<\/p><p>If not, how do you know it's testing the correct thing?<\/p>",
"cta": "",
"tags": ["software-development","automated-testing"]
}, {
"title": "Don&#039;t cherry-pick features from a branch to deploy",
"date": "1714089600",
"permalink": "/daily/2024/04/26/don-t-cherry-pick-features-from-a-branch-to-deploy",
"text": "<p>I previously worked on a project where, after a code change had been reviewed and merged, it was pushed to a UAT environment for the client to test.<\/p><p>This usually resulted in a group of changes pushed to the UAT environment, waiting for the client to test them.<\/p><p>They would, and then decide which changes they wanted to be moved to production.<\/p><p>Maybe changes 1, 2 and 4 would be asked to be deployed, but not 3 or 5.<\/p><p>Someone would then cherry pick the relevant commits onto the mainline branch and deploy them to production.<\/p><p>But, if the code isn't the same as on that UAT environment, how do you know it still works?<\/p><p>Could a commit have been missed or could not including a non-selected commit have caused a regression or unintended side effects?<\/p><p><code>git cherry-pick<\/code> isn't a command I use often, and definitely not in this scenario.<\/p><p>If you want to select which changes go live, feature flags are a better option as you don't need to change the commits or code you're pushing.<\/p><p>You push all the commits from UAT to production and enable the feature flags for the things you want to release.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "If everyone branches, no-one gets the updates",
"date": "1714003200",
"permalink": "/daily/2024/04/25/if-everyone-branches-no-one-gets-updates",
"text": "<p>A common response I get when debating topic branches is \"I regularly pull <code>develop<\/code> or <code>main<\/code> and get the latest changes.<\/p><p>But if everyone is working on individual topic branches instead of the mainline branch, where do the changes come from?<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Testing topic branches in isolation",
"date": "1713916800",
"permalink": "/daily/2024/04/26/testing-topic-branches-in-isolation",
"text": "<p>I was recently asked about setting up different testing environments based on topic (a.k.a. feature) branches.<\/p><p>When a feature or bug fix was finished, it would create a new environment for it to be tested.<\/p><p>If it passed testing, the topic branch was merged and it would be included in the next release.<\/p><p>But, there's no guarantee it still works once it's been merged.<\/p><p>It could conflict with changes from a different topic branch and no longer work - even if it worked when it was tested in isolation on its own branch.<\/p><p>To ensure it still works, it will need to be tested again.<\/p><p>So, what is the benefit of testing it in isolation if it needs to be tested again once it's merged?<\/p><p>This is why I prefer continuous integration and delivery (CI\/CD), as I always know all changes work together and not just in isolation.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Why use a static site generator",
"date": "1713830400",
"permalink": "/daily/2024/04/23/why-use-a-static-site-generator",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/04\/22\/building-websites-with-php-and-sculpin\">In February<\/a>, I spoke at the PHP South West meetup about Sculpin - a static site generator written in PHP.<\/p><p>Sculpin uses Twig, HTML and Markdown to generate static HTML files that you can upload to any web server.<\/p><p>You don't need PHP or a database server - making it simpler and cheaper to host compared to a CMS-powered site.<\/p><p>There's also no database for people to hack into and, as they're just static HTML pages, they are very quick to load.<\/p><p>The downside is that files need to be created and edited locally or editing Git files on GitHub, etc, as there's no CMS to log into.<\/p><p>Still, for some projects, static site generators are a great option.<\/p><p>For Drupal, there's Tome - a module that creates a static website from a Drupal installation, and something I plan to investigate.<\/p>",
"cta": "",
"tags": ["software-development","php","sculpin"]
}, {
"title": "Building websites with PHP and Sculpin",
"date": "1713744000",
"permalink": "/daily/2024/04/22/building-websites-with-php-and-sculpin",
"text": "<p>The video of the most recent version of my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-static-websites-sculpin\">Building static websites with PHP and Sculpin<\/a> from February's PHP South West meetup <a href=\"https:\/\/youtu.be\/axy6ltc9meA?si=FtR4DZ5BVi_Se60J\">has been released<\/a>.<\/p><p>In the talk, I explain what Sculpin is and how it works before a live demo where I rebuild part of the PHPSW website (which I worked on originally).<\/p><p>If you have any feedback or questions, reply to this email and let me know.<\/p>",
"cta": "",
"tags": ["software-development","php","public-speaking"]
}, {
"title": "Almost at 100 talks and workshops",
"date": "1713657600",
"permalink": "/daily/2024/04/21/almost-at-100-talks-and-workshops",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/talks\">My talks page<\/a> on my website says I've presented 98 talks and workshops at different events since September 2012.<\/p><p>Next month, I'm giving two talks at DrupalCamp Ghent.<\/p><p>One on <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">automated testing and test-driven development<\/a> and another on <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Tailwind CSS<\/a>.<\/p><p>This means that these will be my 99th and 100th presentations!<\/p><p>I enjoy speaking at events such as meetups and conferences, and I hope people have learned from them as well.<\/p>",
"cta": "",
"tags": ["software-development","drupal","drupalcamp","php","public-speaking"]
}, {
"title": "Speaking at DrupalCamp Belgium",
"date": "1713571200",
"permalink": "/daily/2024/04/20/speaking-at-drupalcamp-belgium",
"text": "<p>I'm happy to be speaking at DrupalCamp Belgium next month, on the 10th and 11th of May in Ghent.<\/p><p>I'll be presenting two sessions on <a href=\"https:\/\/www.drupalcamp.be\/en\/drupalcamp-ghent-2024\/schedule\/friday\">automated testing in Drupal<\/a> (Friday) and <a href=\"https:\/\/www.drupalcamp.be\/en\/drupalcamp-ghent-2024\/schedule\/saturday\">Tailwind CSS<\/a> (Saturday).<\/p><p>I spoke about testing most recently at DrupalCon Lille, and I'm looking forward to updating my Tailwind talk again to include the latest features within the framework.<\/p><p><a href=\"https:\/\/www.drupalcamp.be\/en\/drupalcamp-ghent-2024\/tickets\">Tickets are still available<\/a> and it would be great to see you there.<\/p>",
"cta": "",
"tags": ["drupal","drupalcamp","public-speaking"]
}, {
"title": "When should you tag 1.0?",
"date": "1713484800",
"permalink": "/daily/2024/04/19/when-should-you-tag-1-0",
"text": "<p>Something I've seen, both with contributed Drupal modules and other open-source projects, over the past few years is they spend a lot of time in the 0.x versions or releasing alpha and beta versions rather than releasing a 1.0 or stable version.<\/p><p>I presume it's a concern around backward compatibility and maintaining that once a stable version is released.<\/p><p>But, if you want people to use your module or upgrade it to the latest version, that's much easier to do once there's a stable version.<\/p><p>Some organisations prohibit using alpha or unstable versions of projects so, if there isn't a stable version, they wouldn't be able to use it.<\/p><p>Personally, if I'm using one of my open-source modules, plugins or libraries in production, there should be a stable 1.0 version tagged.<\/p><p>Once it's in production, I'm already making an implied commitment that it's going to be stable and I won't break everything in the next release, so why not make that explicit and tag a stable release?<\/p><p>Version numbers are free and nothing is stopping you from deprecating code and releasing a new major version with breaking changes in the future, so go ahead and tag that stable version.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "I made my first commit to LocalGov Drupal Microsites",
"date": "1713398400",
"permalink": "/daily/2024/04/18/first-commit-localgov-drupal-microsites",
"text": "<p>This week, I submitted <a href=\"https:\/\/github.com\/localgovdrupal\/localgov_microsites_project\/pull\/43\">my first change<\/a> to the LocalGov Microsites project.<\/p><p>It was a small change - correcting a typo that I spotted within the README file.<\/p><p>It's OK to start small, especially when first working on a new codebase.<\/p><p>It was a good introduction to the project and the first of what I hope to be numerous contributions to the Microsites distribution and LocalGov Drupal in general.<\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","localgov-drupal","open-source"]
}, {
"title": "Regular releases encourage contribution",
"date": "1713312000",
"permalink": "/daily/2024/04/17/regular-releases-encourage-contribution",
"text": "<p>As well as writing and maintaining my open-source software projects, I regularly contribute to other people's - including PHP libraries, Drupal modules and Tailwind CSS plugins.<\/p><p>I'm more likely to contribute to your project if you release new versions regularly.<\/p><p>Why would I if my changes may sit on a development branch for a long time or not be released at all?<\/p><p>If I can see that my changes are likely to be released soon, I'm more likely to spend the time and effort to contribute instead of looking for a different solution.<\/p>",
"cta": "d7eol",
"tags": ["software-development","open-source"]
}, {
"title": "Regularly releasing open-source software",
"date": "1713225600",
"permalink": "/daily/2024/04/16/regularly-releasing-open-source-software",
"text": "<p>As with client applications, I recommend releasing new versions of open-source software as often as possible.<\/p><p>This makes it easier for users to update to newer versions as they can easily see the changes, and less risky as it's easier to roll back or diagnose the problem if there is an issue.<\/p><p>If you've added a feature or fixed a bug, fewer people will likely use it if it's not within a released version of your project and sat on a development branch or waiting for a tagged release. This means they're not benefiting from the changes and getting value from them.<\/p><p>You can add feature flags to hide work-in-progress features that you don't want people to use yet, but you don't want to block yourself from releasing a new version until it's complete.<\/p><p>Regular releases encourage smaller and simpler changes rather than larger and more complex - and potentially breaking - changes.<\/p><p>I like to have a release day each month to release new versions of my open-source projects, which works well for me.<\/p><p>I have a recurring task on my To Do list to review my projects and tag and release any new versions that are needed.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "A note to open-source software maintainers",
"date": "1713139200",
"permalink": "/daily/2024/04/15/a-note-to-open-source-software-maintainers",
"text": "<p>I recently updated a website to the latest version of Drupal.<\/p><p>Doing so introduced a bug in a contributed module I was using.<\/p><p>A fix was committed to the 2.x branch of the module, which is still in an unstable alpha phase, and the issue was closed.<\/p><p>There was no fix for the stable 1.x branch.<\/p><p>There was no fix backported to the 1.x branch.<\/p><p>There are breaking changes between the 1.x and 2.x branches that require me to update custom code that uses the module, which I don't want to do yet, and I don't want to update to an unstable version.<\/p><p>If you maintain open-source software, don't force people to update too quickly.<\/p><p>If you can, make it easy for people to update to the next major version by keeping breaking changes to a minimum and providing time and clear instructions for doing so.<\/p><p>If these are too difficult, it could discourage or prevent people from using your software.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","open-source"]
}, {
"title": "What about updating custom modules and themes?",
"date": "1713052800",
"permalink": "/daily/2024/04/14/what-about-updating-custom-modules-and-themes",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/04\/12\/drupal-rector-and-the-project-update-bot\">Yesterday's email<\/a> was about using Drupal Rector and the Automated Project Update bot to update contributed modules.<\/p><p>But what about custom modules within your application?<\/p><p>To do this, I use the <code>drupal-check<\/code> tool, which is built on PHPStan, and the Upgrade Status module.<\/p><p>They scan your custom modules and themes and report any deprecated code within your custom projects - i.e. code that will be removed in a future major version - and tell you what new code to use instead.<\/p><p>Once you've removed any deprecations, your module or theme will be ready for the next major version of Drupal.<\/p><p>This is the approach I've used to upgrade numerous websites between major modern versions of Drupal, making small updates to existing code instead of having to rewrite it from scratch.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "Rector is not just for Drupal",
"date": "1712966400",
"permalink": "/daily/2024/04/13/rector-is-not-just-for-drupal",
"text": "<p>I like framework-agnostic tools.<\/p><p>I like to reuse knowledge and tools across projects, whether I'm working with Drupal, Symfony, Laravel or Sculpin.<\/p><p>Rector is one of those tools.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/04\/12\/drupal-rector-and-the-project-update-bot\">Yesterday<\/a> I said I use it to create automatic updates to my Drupal module code, but it can be used for other PHP projects, too.<\/p><p>If you're upgrading a PHP library and want to use promoted constructor properties, for example, Rector can do that for you - and a lot more.<\/p><p>You define which rules or presets you want to use, run Rector on the code, and it will make those changes.<\/p><p>Having Rector do this work leaves me free to stay focused on other tasks.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Drupal Rector and the Project Update Bot",
"date": "1712880000",
"permalink": "/daily/2024/04/12/drupal-rector-and-the-project-update-bot",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/04\/10\/resurrecting-the-speakerdeck-field-module\">In Wednesday's email<\/a>, I said I was resurrecting the Speakerdeck Field module, and the same version works on Drupal 8, 9, 10 and 11.<\/p><p>How do I know this?<\/p><p>One of my favourite PHP libraries is Rector - a tool for upgrading code to the newest versions of PHP or, in this case, Drupal using Drupal Rector.<\/p><p>It runs automatically on modules, including Speakerdeck Field, via the Project Upgrade Bot and generates a set of updates to apply.<\/p><p>CI pipelines with GitLab CI and a reliable test suite make it much easier to upgrade modules to the latest Drupal version and ensure they still work.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "Over 100 ATDC subscribers",
"date": "1712793600",
"permalink": "/daily/2024/04/11/over-100-atdc-subscribers",
"text": "<p>Since launching my Automated Testing in Drupal email course, over 100 people have subscribed and received the free ten daily lessons where I explain how to start from scratch to build a Drupal module with automated tests and test-driven development.<\/p><p>Thanks to everyone who has taken the course so far and those who have provided feedback.<\/p><p>Automated testing and test-driven development were game changers for me and enabled me to deliver better projects.<\/p><p>If you'd like to take the course and learn how to do automated testing in Drupal, you can <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">register for free<\/a> and get them direct to your inbox.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","automated-testing","test-driven-development"]
}, {
"title": "Resurrecting the Speakerdeck Field module",
"date": "1712707200",
"permalink": "/daily/2024/04/10/resurrecting-the-speakerdeck-field-module",
"text": "<p>This week, I've resurrected the <a href=\"https:\/\/www.drupal.org\/project\/speakerdeck_field\">Speakerdeck field Drupal module<\/a>.<\/p><p>It's a module I wrote in 2017 for the Drupal 8 version of my website to embed Speakerdeck slides on my talk pages.<\/p><p>My website now runs on Drupal 10, but the great thing is that the same code that worked for Drupal 8 also works for Drupal 9 and 10.<\/p><p>There was no rewrite for each major version, and as I'm not using any deprecated code, the same code works for all the modern versions mentioned, and it looks like it will for Drupal 11, too.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","open-source"]
}, {
"title": "Paying it forward",
"date": "1712620800",
"permalink": "/daily/2024/04/09/paying-it-forward",
"text": "<p>As well as building applications with PHP and Drupal, I spend a lot of time helping others and \"paying it forward\".<\/p><p>I write and contribute to open-source software and offer free online pair programming sessions to work on open-source projects.<\/p><p>I speak at conferences and meetups.<\/p><p>I create content, including videos and coding live streams.<\/p><p>I mentor at in-person events, such as DrupalCon, and for bootcamps, such as School of Code.<\/p><p>I've organised events, such as PHP South Wales and DrupalCamp Bristol, and reviewed session submissions for DrupalCon.<\/p><p>But I wouldn't have been able to do this without others doing the same when I was learning and getting into software development.<\/p><p>In July 2008, when I was evaluating technologies, I posted a question on a forum (I was learning HTML, PHP and MySQL then).<\/p><p>Someone replied and recommended using Drupal, which is how I learned about the project.<\/p><p>If they hadn't done that, I may not be in the position I am now.<\/p><p>I might not have found Drupal, contributed to it, worked for the Drupal Association, or spoken at DrupalCon.<\/p><p>Now, it's my turn to pay it forward.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Come for the software, stay for the community",
"date": "1712534400",
"permalink": "/daily/2024/04/08/come-for-the-software--stay-for-the-community",
"text": "<p>One of my favourite Drupal phrases is \"Come for the software, stay for the community\".<\/p><p>I started using Drupal so I could build a website for the Tae Kwon-Do school I was training at, and then started to get involved with the community online and at events, such as local meetups and conferences, such as DrupalCamps and DrupalCon.<\/p><p>I started to contribute code to Drupal core and contrib projects and was a contribution mentor at my first DrupalCon in Prague in 2017 as well as others since, helping first time Drupal contributors.<\/p><p>I've got jobs and projects from my involvement with the community, including working for the Drupal Association itself.<\/p><p>I've met people and travelled to places I otherwise wouldn't have because of the Drupal community, as well as the wider PHP, open source and software development communities,<\/p><p>I came to Drupal for the code, and stayed for the code and the community.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Avoiding nesting",
"date": "1712448000",
"permalink": "/daily/2024/04/07/avoiding-nesting",
"text": "<p>One of my goals when coding is to reduce the amount of nesting in the code I write.<\/p><p>I mean both in my PHP code where if conditions and foreach loops can be nested within each other, and CSS and Sass files, which support nesting CSS rules.<\/p><p>My aim is to have a maximum of two or three levels of indentation, though sometimes this isn't possible.<\/p><p>Doing so where I can, though, makes my code easier to read and understand and encourages other clean code approaches, such as having small and well-named functions.<\/p><p>In CSS or Sass, avoiding nesting makes it easier to find a rule I'm looking for instead of having to find how rules have been nested or names have been concatenated - making it hard to search or grep for a string.<\/p><p>This approach is part of \"object callisthenics\", which was introduced by Jeff Bay and includes other approaches that I like to follow, such as not using the <code>else<\/code> keyword and other good practices that I like to try and implement when possible.--<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Drupal is a content management framework",
"date": "1712361600",
"permalink": "/daily/2024/04/06/drupal-is-a-content-management-framework",
"text": "<p>There used to be a saying:<\/p><p>If you want to build a website, use <enter CMS name here>. If you want to build <CMS name>, use Drupal.<\/p><p>I think I've heard it used with all the other content management systems, and it isn't about saying one is better.<\/p><p>It highlights that Drupal isn't just a content management system - it's a content management framework.<\/p><p>A framework you use to build your content management system to meet your needs.<\/p><p>Straight away after installing Drupal, you can create as many content types as you want with as many fields as you want to build as simple or complex a content model as you need.<\/p><p>You aren't restricted to the default page and article content types or a fixed set of fields.<\/p><p>That, along with Views - a built-in query builder to build pages and blocks of your content, user login and registration, and JSON:API to allow other applications, such as mobile apps, to access your data, to name a few things, makes Drupal a very powerful option.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "One Drupal fits all",
"date": "1712275200",
"permalink": "/daily/2024/04/05/one-drupal-fits-all",
"text": "<p>Two of the main things I like about Drupal are its flexibility and scalability.<\/p><p>It works well for basic applications, such as personal websites and blogs (like mine) and for large, complex applications such as Drupal.org itself and many others.<\/p><p>I don't need to learn one tool for small or simple projects and another for large or complex projects.<\/p><p>Drupal is one size fits all.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "PHP attributes: coming soon to a Drupal version near you",
"date": "1712188800",
"permalink": "/daily/2024/04/04/php-attributes--coming-soon-to-a-drupal-version-near-you",
"text": "<p>Since Drupal 10.2, the framework has started to adopt PHP attributes - a new feature since PHP 8 - as an alternative to annotations when defining plugins, such as blocks and queues.<\/p><p>From the 10.2 release notes:<\/p><blockquote> <p>Drupal core has started adopting PHP attributes, a modern PHP language feature, to provide better developer experience for plugin annotations. Contributed and custom code can begin adopting this improved API for their plugins, and Block and Action plugins can all be converted to the new API.<\/p><\/blockquote><p>It seems that what's been added so far is the first phase of converting the core's plugins, with more to follow in future versions.<\/p><p>There are also discussions about supporting both attributes and annotations in Drupal 11.<\/p><p>I love to see Drupal continuing to evolve and adopt new features from the PHP language and Symfony framework (such as autowiring and autoconfiguration), and I'm looking forward to using attributes in my projects.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Switching web servers using Build Configs",
"date": "1712102400",
"permalink": "/daily/2024/04/03/switching-web-servers-using-build-configs",
"text": "<p>Have you been in a situation where you needed to switch something in a project, like the type of database or a payment provider?<\/p><p>Today, I decided to switch a project from NGINX to Apache.<\/p><p>Usually, this would involve using a different base Docker image, creating new configuration files, and changing things like the root directory for my project.<\/p><p>But, because I'd built this into <a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-build-configs\">Build Configs<\/a>, I was able to change a few lines in one file, and when I re-generated the configuration files, this project was running Apache.<\/p><p>This is an excellent example of why I built this tool: to save time and reduce duplication across my projects.<\/p><p>For this change, it did both.<\/p>",
"cta": "",
"tags": ["software-development","build-configs"]
}, {
"title": "Releasing a new project one page at a time",
"date": "1712016000",
"permalink": "/daily/2024/04/02/releasing-a-new-project-one-page-at-a-time",
"text": "<p>How do you release a new project?<\/p><p>Do you build everything and release everything at once?<\/p><p>I've used the strategy of building and releasing it a page at a time and running two versions simultaneously.<\/p><p>The main live version stays running, and you use a tool like NGINX or Cloudflare as a gatekeeper to direct traffic to the correct application - either the current one or the new one - based on the requested page.<\/p><p>When a page is ready, you add it to the list of pages to serve from the new application to put it live.<\/p><p>If there's an issue, it is also easy to revert to the original page.<\/p><p>I've used this approach with my website and for client Drupal upgrade projects, where some pages are on Drupal 7 and some on Drupal 10.<\/p><p>It's not the right approach for every situation, but it's a useful one to have in the toolkit.<\/p>",
"cta": "",
"tags": ["software-development","drupal"]
}, {
"title": "I&#039;m attending LocalGov Drupal Camp",
"date": "1711929600",
"permalink": "/daily/2024/04/01/i-m-attending-localgov-drupal-camp",
"text": "<p>On the 24th of April, I'll be attending a LocalGov Drupal Camp in Birmingham, UK.<\/p><p>As someone keen to get more involved and contribute more to the project, and who's <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/25\/newport-city-council-running-localgov-drupal\">local council recently switched to LocalGov<\/a>, I'm looking forward to the chance to learn and contribute on the day and afterwards.<\/p><p>If you want to attend also, there are a few remaining tickets available and you can <a href=\"https:\/\/www.eventbrite.co.uk\/e\/localgov-drupal-camp-2024-tickets-847025314517\">register on Eventbrite<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","drupal","localgov-drupal","drupalcamp"]
}, {
"title": "Making Git work the way you want",
"date": "1711843200",
"permalink": "/daily/2024/03/31/making-git-work-the-way-you-want",
"text": "<p>Another question that followed my recent Git emails was, \" I assume you use rebase over merge?\"<\/p><p>The short answer is \"yes\". I like to keep the history of my repositories clean and simple to read by keeping the logs linear and not full of merge commits.<\/p><p>The longer answer is that I do merges, but only fast-forward merges, at least by default.<\/p><p>If, when merging, Git can fast-forward my branch to the latest commit without creating a merge commit, it will do so.<\/p><p>If not, I can then rebase my changes to make them linear and fast-forwardable. Alternatively, if the commits have already been pushed and cannot be overwritten, I can explicitly allow a non-fast-forward merge in that situation.<\/p><p>I have Git configured to work this way as that's how I want it to work, and that configurability is something I like about Git.<\/p><p>If you want to see how I have Git configured, my settings are in <a href=\"https:\/\/github.com\/opdavies\/dotfiles.nix\/blob\/462eff64f227332d58c7c3652eeaa88b692c064d\/lib\/shared\/modules\/git.nix#L95-L135\">my dotfiles repository<\/a> (note this file is written in the Nix language as I use Nix to manage my configuration).<\/p><p>If you're working in a team, I'd suggest having a common configuration for everyone and defined rules for how you're going to use Git (branch names, merge or rebase, etc) to avoid inconsistencies.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Leaving a trail of breadcrumbs",
"date": "1711756800",
"permalink": "/daily/2024/03/30/leaving-a-trail-of-breadcrumbs",
"text": "<p>A great thing about committing often is that you leave a trail of breadcrumbs for yourself, and you can easily find your way back.<\/p><p>If you are trying to get a test to pass or fix a bug and you get a bit lost, you can see what you've changed since your last commit instead of everything since you started working on your task.<\/p><p>If needed, you can discard your changes and reset to your last working commit to try again, similar to using the \"test and commit or revert\" approach.<\/p><p>If I commit too often, I can squash them before pushing.<\/p><p>If I don't commit often enough, I can regret not committing more regularly if I get stuck or lost.<\/p><p>I'd rather do the former.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "How I Git",
"date": "1711670400",
"permalink": "/daily/2024/03/29/how-i-git",
"text": "<p>After <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/27\/hotfixing-without-branches\">Wednesday's email<\/a>, someone said, \"It sounds like you and I use git very differently.\" So, I wanted to explain what my typical Git workflow is.<\/p><p>I used to use Git Flow, but now, I almost never create a new branch when starting a new task.<\/p><p>I keep my workflow as simple as possible by using trunk-based development and working on a single branch as much as I can.<\/p><p>Before I start, I make sure any uncommitted changes are committed or reset and that the automated tests, static analysis, coding standards checks, etc., are passing so I know I'm starting from a good place.<\/p><p>Then, I start working on the task.<\/p><p>I like to work in small steps and make small, regular commits, but I don't always push each individual commit to the remote repository.<\/p><p>Sometimes, I'll make a number of \"work in progress\" commits and squash them into one before pushing them.<\/p><p>I want the time between making and pushing the commit to be as short as possible, and I want each commit to be deployable.<\/p><p>If I'm doing test-driven development, I'll typically commit each time a test is passing - whether it's adding a new test or extending one.<\/p><p>I run any tests often whilst writing code to ensure they pass, either using a watch command or a keybinding in Neovim.<\/p><p>I won't push a commit that would cause the code to not work, a test to fail, or block any other (potentially more urgent) changes from being pushed to production.<\/p><p>If I push a commit that breaks the CI pipeline, I'll fix it quickly, which is usually possible as the changes are small.<\/p><p>If not, I'll revert the commit to get back to a deployable state as quickly as possible.<\/p><p>If I'm going to add a feature flag, I'll usually know that in advance and avoid rushing to add one later if a more urgent task comes in.<\/p><p>By keeping each commit in a working and deployable state, a change can be feature flagged and deployed but not activated until the feature flag is enabled.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Starting to sprinkle JavaScript with Simulus",
"date": "1711584000",
"permalink": "/daily/2024/03/28/starting-to-sprinkle-javascript-with-simulus",
"text": "<p>I've been watching the new \"Cosmic Coding with Symfony 7\" series on SymfonyCasts, and today's video was about Stimulus - a \"modest JavaScript framework for the HTML you already have\".<\/p><p>As I'm comfortable with other frameworks, such as Vue.js and Alpine.js, I've usually skipped videos about Stimulus, but today, it caught my eye.<\/p><p>I was intrigued by it and experimented with it by refactoring a component from a project I am working on.<\/p><p>I like the organisation Stimulus provides by using JavaScript classes and controllers while keeping things simple in the HTML code.<\/p><p>I initially did this in Fractal but then created <a href=\"https:\/\/github.com\/opdavies\/stimulus-esbuild-example\">an example project<\/a> using Stimulus with esbuild. It's now on my GitHub profile and includes other tools such as Nix, just, and Tmuxinator.<\/p><p>After this short evaluation, I like Stimulus and will use it on other components in this project, maybe using third-party Stimulus controllers - either directly or for inspiration.<\/p><p>Hat tip to Ryan Weaver and SymfonyCasts for showing Stimulus and Nick Janetakis for showing me esbuild.<\/p>",
"cta": "",
"tags": ["software-development","symfony","stimulus"]
}, {
"title": "Hotfixing without branches",
"date": "1711497600",
"permalink": "/daily/2024/03/27/hotfixing-without-branches",
"text": "<p>Last month, I wrote an email explaining <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/28\/why-i-dont-branch\">why I don't create branches<\/a>.<\/p><p>After sending that email, I received this question from a reader (shared with permission):<\/p><blockquote> <p>I'm trying to work at one feature at a time, so I usually don't need feature branches.<\/p> <p>There's one thing that's difficult for me, maybe you could tell us something about this in one of your upcoming posts:<\/p> <p>How do you deal with hot fixes?<\/p> <p>I know, there's keeping features small, commit often and early. But sometimes this isn't possible, and a feature will take e.g. 3 days of work. Now, if there's an urgent bug in production that should be fixed asap, what are you doing?<\/p> <p>Git stash probably won't help here, as there might be commits already that would deliver an incomplete feature.<\/p><\/blockquote><h2 id=\"option-1%3A-worktrees\">Option 1: Worktrees<\/h2><p>Whilst I don't create branches, I do use <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/12\/git-worktrees-docker-compose\">Git worktrees<\/a>, which allows me to have multiple versions of the code checked out at the same time - similar to having multiple clones of a repository.<\/p><p>Having multiple worktrees, you don't need to stash the code for your incomplete feature or worry about commits you haven't pushed yet.<\/p><p>You can create a new worktree, fix the urgent bug and switch back to your <code>main<\/code> worktree when you're finished.<\/p><p>You'll still need to update the original worktree with your new changes which may result in conflicts - the same as merging or rebasing onto a branch.<\/p><h2 id=\"option-2%3A-feature-flags\">Option 2: Feature Flags<\/h2><p>My preferred approach is to use <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/12\/07\/separating-releases-from-deployments-with-feature-flags\">feature flags<\/a>, a.k.a. feature toggles.<\/p><p>My wrapping the incomplete feature in a feature flag, it can be deployed but won't be active until the flag is enabled - similar to writing a new Drupal module but not enabling it.<\/p><p>This is a technique I use often as it works well with trunk-based development and continuous integration and delivery.<\/p><p>When the incomplete feature is feature-flagged, you can fix the bug and deploy the hotfix without stashing or rebasing any changes, and you can leave the flag disabled.When the feature is ready, enable the feature flag to activate it and, if you need to turn it off again (maybe that's causing the next bug), you can easily disable it without needing to revert and deploy the code again.<\/p><p>You can just turn the feature flag back off.<\/p><p>I hope that helps!<\/p>",
"cta": "subscription",
"tags": ["software-development","git"]
}, {
"title": "Let someone else do the work",
"date": "1711411200",
"permalink": "/daily/2024/03/26/let-someone-else-do-the-work",
"text": "<p>Yesterday, I was investigating a CSS issue.<\/p><p>It's a known issue due to some legacy code in the website's CSS that I'd fixed before but now needed to extend.<\/p><p>Instead of blindly following the same path and extending my previous fix, I decided to rethink the problem and my approach.<\/p><p>I re-read my documentation and re-reviewed potential solutions I'd evaluated previously.<\/p><p>I decided to take a different approach to solving the problem and found an open-source plugin that someone else had written that gave me the functionality I needed instead of writing it from scratch.<\/p><p>I read the code and did a short spike to see if it worked with the existing configuration.<\/p><p>After some experimentation, I got it to work and added it to the project.<\/p><h2 id=\"here%27s-the-thing\">Here's the Thing<\/h2><p>The plugin I used was only 34 lines of code, but these are lines I didn't need to write or will need to maintain.<\/p><p>If it works, why would I write it myself?<\/p><p>I'd rather use what someone else has written and contribute if I find a bug or need a new feature.<\/p><p>That's the benefit of open-source software, and why I use Drupal, PHP, Sculpin, Tailwind CSS, Nix, and others.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","open-source"]
}, {
"title": "Newport City Council running LocalGov Drupal",
"date": "1711324800",
"permalink": "/daily/2024/03/25/newport-city-council-running-localgov-drupal",
"text": "<p>Last week, it was announced that Newport City Council's (my local council) website is now running on LocalGov Drupal - a distribution for council websites.<\/p><p>This increases the total to 44 councils in the UK and Ireland.<\/p><p>Newport is the first Welsh council to use it and the first LocalGov website to be bilingual, serving content in both English and Welsh.<\/p><p>It's great to see Drupal adoption continue to grow in Wales and within the Welsh public sector, and LocalGov being adopted by more councils across the UK and Ireland.<\/p><p>I think LocalGov Drupal is a great project and one <a href=\"https:\/\/github.com\/localgovdrupal\/localgov_alert_banner\/pull\/225\">I've contributed to previously<\/a>, and I plan to do more in the future.<\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","php","localgov"]
}, {
"title": "Why I don&#039;t use a GUI for Git",
"date": "1711238400",
"permalink": "/daily/2024/03/24/why-i-dont-use-a-gui-for-git",
"text": "<p>I've been a Git user since my first full-time Developer position in 2010.<\/p><p>I've used other version control systems, too, early in my career, but I settled on Git and haven't looked back.<\/p><p>I've used GUI tools for Git, such as Sourcetree and GitHub Desktop, but I prefer to use Git on the command line instead of a GUI or TUI.<\/p><p>As a Developer who uses a command-line-focused workflow and works mainly in a terminal, there is less context switching, but I want to focus on learning the tool itself rather than a wrapper around it.<\/p><p>Some GUIs add their own terminology or functionality, making it difficult for people to debug something on the command line if they experience an issue.<\/p><p>It's easier to solve problems if you understand the tool itself.<\/p><p>What if I had a favourite Git GUI that became no longer supported or maintained?<\/p><p>Would any time spent learning that GUI have been wasted?<\/p><p>This was also a reason why I switched to using Docker and Docker Compose instead of pre-built wrappers.<\/p><p>I want to better understand and be efficient with the underlying tool, not only someone else's implementation of it.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Write programs that do one thing and do it well",
"date": "1711152000",
"permalink": "/daily/2024/03/23/write-programs-that-do-one-thing-and-do-it-well",
"text": "<p>Over the last few days, I've written about watchers and running commands such as automated tests when files are changed.<\/p><p>Some tools have this built in, whilst others don't.<\/p><p>I've used different tools to do this and recently switched to <code>entr<\/code>.<\/p><p>The previous one wasn't showing me the output from running Drupal automated tests, which <code>entr<\/code> does.<\/p><p>I also like that it follows the UNIX philosophy of doing one thing well and working well with other programs.<\/p><p>For example, to run my automated tests when I change a file, I need to run <code>find web\/modules\/custom | entr .\/run test<\/code>.<\/p><p><code>entr<\/code> isn't concerned with how to find the list of files to watch - only what to do with them.<\/p><p>To get the list of files, I use the <code>find<\/code> command and provide the files to <code>entr<\/code>.<\/p><p>I also like to do this with my application code. I like to write small modules and libraries with clear boundaries and responsibilities, do their tasks well, and work well with other parts of the application.<\/p>",
"cta": "",
"tags": ["software-development","unix","linux"]
}, {
"title": "Watching all the things",
"date": "1711065600",
"permalink": "/daily/2024/03/22/watching-all-the-things",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/21\/git-hooks---yay-or-nay\">In yesterday's email<\/a>, I mentioned that I use watch commands such as <code>nodemon<\/code>, <code>watchexec<\/code> and <code>entr<\/code> whilst developing to run commands automatically when I change code.<\/p><p>For example, running <code>find web\/modules\/custom | entr .\/run test<\/code> will re-run my test suite when any custom module changes.<\/p><p>This works well for tests, but for other checks, such as static analysis with PHPStan or coding standards with PHPCS, I have integrations in Neovim, and I get real-time feedback as I code.<\/p><p>If a line fails static analysis or coding standards, a diagnostic message is shown so I can fix it immediately, and I don't need to use a watcher or wait for my CI pipeline to fail.<\/p>",
"cta": "",
"tags": ["software-development","php"]
}, {
"title": "Git hooks - yay or nay?",
"date": "1710979200",
"permalink": "/daily/2024/03/21/git-hooks---yay-or-nay",
"text": "<p>Many people are very for or against Git hooks - scripts that run automatically on events such as pre-commit and pre-push.<\/p><p>Commonly, they are used for running tasks such as altering a commit message or running before committing automated tests and static analysis before pushing a commit.<\/p><p>I'm on the fence.<\/p><p>I've used them and added support for them to Build Configs, but I don't feel strongly about them.<\/p><p>They are awkward to set up (you need to edit the configuration for them to work) and can be easily disabled or bypassed.<\/p><p>Some people think it's the Developer's responsibility to run the tasks before pushing changes or that they'll be run in a CI pipeline, so why would they need to be run locally?<\/p><p>As I write many small commits and push changes regularly, I can find hooks irritating and prefer to use watchers instead with tools like <code>watchexec<\/code> and <code>entr<\/code>.<\/p><p>There are also tools like Captain Hook that are built to manage Git hooks. Maybe, I should investigate it more.<\/p><p>What do you think? Are you yay or nay for Git hooks?<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "What is legacy code?",
"date": "1710892800",
"permalink": "/daily/2024/03/20/what-is-legacy-code",
"text": "<p>How do you define legacy code?<\/p><p>Is it code written by previous Developers who worked on the codebase?<\/p><p>Is it code you wrote last week or last month?<\/p><p>Is it code for features everyone no longer uses?<\/p><p>Is it the \"old\" part of the application that no one wants to work on?<\/p><p>It is any code that's not nice to work on or difficult to change?<\/p><p>Is it code written with different conventions to your current ones or in a different style?<\/p><p>Is it any code that doesn't have automated tests or wasn't written with test-driven development?<\/p><p>Is it code built with outdated tooling or frameworks (like CSS libraries) that were popular then but have since been replaced by something newer?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>These are just some of the potential definitions I can think of.<\/p><p>The term \"legacy code\" and others, such as \"technical debt\", often mean different things.<\/p><p>What's your definition? Reply and let me know.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Drupal Commerce: not just for selling t-shirts and hats",
"date": "1710806400",
"permalink": "/daily/2024/03/19/drupal-commerce-not-just-for-selling-t-shirts-and-hats",
"text": "<p>I recently had Ryan Szrama as a guest on the <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/13-ryan-szrama-centarro\">Beyond Blocks podcast<\/a>.<\/p><p>Ryan is the CEO of Centarro - the company behind Drupal Commerce, the eCommerce platform built on the Drupal CMS.<\/p><p>I've used Drupal Commerce for a number of projects since it was released in 2011, as well as Ubercart before that.<\/p><p>One of the major things I like about it is its flexibility.<\/p><p>The Commerce Kickstart distribution is a great way to create a demo Drupal Commerce project that shows a typical eCommerce store selling everything from books to hats, furniture and inflatable flamingos.<\/p><p>I've used Drupal Commerce for these typical scenarios but also for some non-typical ones.<\/p><p>I created a multi-site Drupal Commerce store for a gadget insurance company, dealing with many products and product variations. I built a custom Vue.js form that created an order with the required items before passing customers to a Drupal Commerce checkout flow.<\/p><p>I created a yearly photography competition website that photographers can enter by purchasing a product and uploading their photographs to the order. I built custom judging functionality, which allows jurors to score each entry and the site owner to see the totals and which submission won the competition.<\/p><p>I created an events management and booking website where each event was a product with different variations based on the different prices - early bird, regular and last minute. Each event had a maximum number of places and, potentially, a waitlist.<\/p><p>This website also included a loyalty scheme for event organisers and attendees, who received coupons after organising or attending a certain number of events.<\/p><p>Drupal Commerce can do a lot and isn't just selling t-shirts, hats, books or furniture.<\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","drupal-commerce","php"]
}, {
"title": "Automated Drupal 11 compatibility fixes",
"date": "1710720000",
"permalink": "/daily/2024/03/18/automated-drupal-11-compatibility-fixes",
"text": "<p>Yesterday, I received the first \"Automated Drupal 11 compatibility fixes\" email from the Rector-powered Project Update Bot.<\/p><p>It was for the <a href=\"https:\/\/www.drupal.org\/project\/feature_toggle_twig\">Feature Toggle Twig module<\/a> that adds a <code>featureIsEnabled()<\/code> function to Twig to check if a feature toggle is enabled.<\/p><p>For example:<\/p><pre><code class=\"language-twig\">{% if featureIsEnabled('foo') %} {# ... #}{% endif %}<\/code><\/pre><h2 id=\"what-changes-were-needed%3F\">What Changes Were Needed?<\/h2><p>The only change needed to make the module Drupal 11 compatible was updating the <code>core_version_requirement<\/code> to <code>^10 || ^11<\/code> - allowing the module to support Drupal 10 and 11 at the same time as it uses no deprecated code.<\/p><p>That's a great thing about modern Drupal compared to legacy versions - no major changes or rewrites to support a new major version!<\/p><h2 id=\"here%27s-the-thing\">Here's the Thing<\/h2><p>I thought this was a great initiative in previous versions and I'm glad to see it again for Drupal 11, and it's great that it's being done with time before the Drupal 11 release as it gives maintainers the time to update their projects so as many modules as possible will be Drupal 11-compatible when it's released.<\/p><p>I look forward to getting more of these emails for my <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/09\/override-node-options-40624-drupal-websites\">other contributed projects on Drupal.org<\/a>.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php"]
}, {
"title": "Patches vs Merge Requests",
"date": "1710633600",
"permalink": "/daily/2024/03/17/patches-vs-merge-requests",
"text": "<p>I'm aware of the ongoing changes to the issue queues on Drupal.org, I haven't contributed or committed as much recently, so I haven't had to use the new approaches, such as issue forks and GitLab merge requests.<\/p><p>Yesterday, though, I was able to do that whilst submitting <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/16\/adding-tests-to-the-content-access-by-path-module\">the tests I wrote to the Content Access by Path module<\/a>.<\/p><p>I've made many contributions to projects on Drupal.org, including Drupal core and Drupal.org itself, so I'm very familiar with how the issue queues and the patch workflow work.<\/p><p>When I first started contributing, we were using CVS, and before the \"Great Git Migration\".<\/p><p>I'm also familiar with the pull or merge request approach from working on open-source and team projects on GitHub, GitLab and Bitbucket.<\/p><p>I can see how a merge request-based workflow on Drupal.org will lower the barriers for new contributors, which seemed to be the case at DrupalCon Lille.<\/p><p>I look forward to adapting and using it more now that the patch workflow is deprecated and will soon no longer work as everything will switch to merge requests and leverage more of GitLab's features.<\/p><p>Another step forward for Drupal.org and the Drupal project.<\/p>",
"cta": "d7eol",
"tags": ["software-development","drupal","php","open-source"]
}, {
"title": "Adding tests to the Content Access by Path module",
"date": "1710547200",
"permalink": "/daily/2024/03/16/adding-tests-to-the-content-access-by-path-module",
"text": "<p>Last month, I released the <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/11-mark-conroy\">Beyond Blocks podcast episode<\/a> where I spoke with Mark Conroy.<\/p><p>We spoke about a number of things, including the 'Content Access by Path' Drupal module he wrote, and I promised I'd write some automated tests for it as there weren't any at the time.<\/p><p><a href=\"https:\/\/www.youtube.com\/live\/XTpliKd47Lg?si=o4-my-XHGvcM_mWS\">Yesterday on my Friday live stream<\/a>, I installed the module and learnt how it works whilst writing some automated tests.<\/p><p>As is common, the first test took a little while to do as I got the setup steps working and learned how the module worked. Once that was passing, adding the others was fairly straight forward.<\/p><p>After the stream, I <a href=\"https:\/\/www.drupal.org\/project\/content_access_by_path\/issues\/3428680\">created an issue<\/a> with a merge request to add the tests I wrote and enabling GitLab CI so they'll be automatically run for any other changes.<\/p><p>Hopefully, it'll be reviewed soon, but I've done what I promised, contributed to more open-source software, learned more about a new module and, hopefully, others will have learned things from the stream too.<\/p><p><a href=\"https:\/\/www.youtube.com\/@opdavies\">Subscribe to my YouTube channel<\/a> to be notified of future live streams!<\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","php","automated-testing"]
}, {
"title": "Everything is a trade-off",
"date": "1710460800",
"permalink": "/daily/2024/03/15/everything-is-a-trade-off",
"text": "<p>I recently added a custom <code>wrapper<\/code> class within a Tailwind CSS project.<\/p><p>It combined the <code>max-w-6xl<\/code>, <code>mx-auto<\/code> and <code>px-4<\/code> classes using <code>@apply<\/code>, which I rarely use.<\/p><p>I added it so we didn't have to add the same classes multiple times.<\/p><p>The advantage was it removed some duplication, but people needed to switch from the Twig template to the CSS file to remember what the <code>wrapper<\/code> class did.<\/p><p>This undoes some of the advantages of Tailwind CSS and utility classes - the ability to stay in one file without needing to context switching, and easily reading what classes are on an element and immediately knowing what styles are applied to it.<\/p><p>Everything is a trade-off.<\/p><p>You need to decide which option feels right for you.<\/p>",
"cta": "d7eol",
"tags": ["software-development"]
}, {
"title": "Just say Drupal",
"date": "1710374400",
"permalink": "/daily/2024/03/14/just-say-drupal",
"text": "<p>Today, I've been following a conversation on Twitter and reading a blog post about Drupal naming and removing the version number from promotional materials.<\/p><p>In the post, the author recommends stopping using the version number and \"just say Drupal\" and referring to Drupal 7 and older as \"Legacy Drupal\".<\/p><p>Here's a quote from the article that stood out to me:<\/p><blockquote> <p>This is no longer true! We have successfully eliminated the need for organizations to leave Drupal because \u201cit\u2019s cheaper to just rebuild it in Wordpress than upgrade from 8 to 9 or from 9 to 10.\u201d We\u2019ve made it easier for our clients to spend less on major upgrades, we should be proud!<\/p><\/blockquote><p>Another suggestion was to also use the term \"Modern Drupal\" for anything since Drupal 8.<\/p><p>I've been doing this or calling it \"Drupal 8+\" on streams and podcast episodes, but I like this approach and I'm going to standardise on this, help change the perception of Drupal and that large rebuilds are no longer needed to upgrade as they were between the older legacy versions.<\/p><p><a href=\"https:\/\/ten7.com\/blog\/post\/just-say-drupal\">Read the article<\/a> for more information about this.<\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","php"]
}, {
"title": "80% of PHP?",
"date": "1710288000",
"permalink": "/daily/2024/03/13/80--of-php",
"text": "<p>Something I see on many Developers' websites and CVs is percentages or levels of how well they know certain tools and frameworks.<\/p><p>Things like \"80% of PHP\" or \"Advanced in HTML and CSS\".<\/p><p>But how do you quantify that?<\/p><p>Do people alter their percentages accordingly if a new feature is added to a language or framework?<\/p><p>Or, instead of trying to show how much you understand, focus on what problems you can solve with those tools and how you can provide value to customers or employers instead of what tools you'd use to do it.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "You should know when to remove a feature flag",
"date": "1710201600",
"permalink": "/daily/2024/03/12/you-should-know-when-to-remove-a-feature-flag",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/03\/11\/feature-flags-should-be-short-lived\">In yesterday's email<\/a>, I mentioned my recent <a href=\"https:\/\/twitter.com\/opdavies\/status\/1767846980250714261\">\"minimum viable feature flag\" tweet<\/a> and that I think feature flags should be short-lived.<\/p><p>But how do you know when a feature flag should be removed?<\/p><p>My approach is to add a TODO comment above where I use a feature flag.<\/p><p>In that comment, I added why the feature flag was added and when it can be removed.<\/p><p>It can be something like \"Remove this when x is deployed\" and\/or a targeted date when I'd expect to be able to remove the flag.<\/p><p>Then, when reading through the code, anyone can see when it should be possible to remove each feature flag, and it's easy to find flags that can be removed by reviewing the TODO comments.<\/p>",
"cta": "subscription",
"tags": ["software-development","feature-flags"]
}, {
"title": "Feature flags should be short-lived",
"date": "1710115200",
"permalink": "/daily/2024/03/11/feature-flags-should-be-short-lived",
"text": "<p>Today, I <a href=\"https:\/\/twitter.com\/opdavies\/status\/1767846980250714261\">posted a tweet<\/a> with a screenshot of some code.<\/p><p>When previously working on the <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/19\/introducing-versa\">Versa CLI tool<\/a>, I had a TODO comment saying \"What if there are multiple languages?\".<\/p><p>Versa is a tool for standardising commands between different languages and frameworks, but some projects, like my personal website, use multiple languages.<\/p><p>The website is powered by Sculpin, a static site generator written in PHP (so there is a composer.json file) and node to compile the front-end assets (so there is also a package.json file).<\/p><h2 id=\"what-problem-am-i-trying-to-solve%3F\">What Problem Am I Trying to Solve?<\/h2><p>Depending on the language, commands like <code>versa install<\/code> will need to execute a different command - e.g., composer install<code>or<\/code>npm install` (or an equivalent node package manager).<\/p><p>I added PHP support first, so if a composer.json file is found, the PHP command is run as the default.<\/p><p>What I thought was for projects with multiple languages, to prompt the user to select the language when running the command if no explicit language is set.<\/p><p>This led me to do a spike of using Symfony Console's <code>choice<\/code> method to see what that would look like so I could add a screenshot to the GitHub issue.<\/p><p>Once I'd finished with the spike, rather than deleting the code, I wrapped it in an <code>if (false)<\/code> condition so it wouldn't be executed, but I could still re-enable it in the future.<\/p><p>The screenshot in the tweet showed this, along with the text \"Minimum viable feature flag.\"<\/p><p>This is only supposed to be there for a short time until I revisit the code and implement the feature I was spiking on.<\/p><p>If it would be a long time before I looked at it again, I'd take a different approach.<\/p><h2 id=\"here%27s-the-thing\">Here's the Thing<\/h2><p>One of the main rules of using feature flags is that they should be short-lived.<\/p><p>It's less than ideal to read through a codebase and see it scattered with feature flags that are no longer needed and were used to release a feature several months ago, but the flag hasn't been removed.<\/p><p>A feature flag is a temporary solution for separating the deployment of code from the release of a change.<\/p><p>Once it's been released, the flag should be removed.<\/p>",
"cta": "subscription",
"tags": ["software-development","feature-flags"]
}, {
"title": "Visual testing and Diffy with Yuri Gerasymov",
"date": "1710028800",
"permalink": "/daily/2024/03/10/visual-testing-and-diffy-with-yuri-gerasymov",
"text": "<p>This week on the Beyond Blocks podcast, I'm joined by Yuri Gerasymov to discuss Diffy visual regression testing.<\/p><h2 id=\"talking-points\">Talking Points<\/h2><ul><li>What is visual regression testing?<\/li><li>How do you deal with false positives?<\/li><li>Different use cases for visual regression testing.<\/li><li>Automatic updates.<\/li><li>Scheduling content.<\/li><li>Visual regression testing in CI.<\/li><li>Diffy in WordPress.<\/li><li>What's a baseline?<\/li><li>Initial setup and onboarding feedback.<\/li><li>Testing dark mode?<\/li><li>Component testing with Storybook and Fractal?<\/li><li>Testing local environments.<\/li><li>Testing as authenticated users.<\/li><li>The roadmap for Diffy.<\/li><\/ul><h2 id=\"quotable-quotes\">Quotable Quotes<\/h2><ul><li>We help development teams to have less visual bugs in their website. We take screenshots of the pages and compare them so you can see what changed and how. (YG)<\/li><li>We built tools for you to mock the content. You provide selectors for the elements with the content of the article and we'll replace it with lorem ipsum text so it will be exactly the same across multiple environments. (YG)<\/li><li>I can still write an assertion to check the text is on the page or not, but it won't confirm it's in the correct place. (OD)<\/li><li>Having a tool checking for changes on a regular basis instead of only after a deployment would be very useful. (OD)<\/li><li>So, you could have a tool like Violinst automatically creating pull requests and Diffy checking those PRs, so the two could work together? (OD)<\/li><li>With visual testing, it's very easy to get started. (YG)<\/li><li>Visual testing is great for showing your client your work. (YG)<\/li><\/ul><p>I learned a lot during this conversation and have added visual regression testing to my testing toolbox for working on projects.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/14-yuri-gerasymov-diffy\">Listen to the episode<\/a><\/p>",
"cta": "subscription",
"tags": ["software-development","drupal","podcast","automated-testing"]
}, {
"title": "Override Node Options is used on 40,624 Drupal websites",
"date": "1709942400",
"permalink": "/daily/2024/03/09/override-node-options-40624-drupal-websites",
"text": "<p>In my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">Test-Driven Drupal talk slides<\/a>, I show a screenshot of a tweet from February 2012 by Tim Millwood asking if anyone wanted to maintain the Override Node Options module.<\/p><p>I said yes and took over maintainership.<\/p><p>In April 2012, the module was installed on 9,212 Drupal websites - just over 7,000 Drupal 6 websites and just over 2,000 Drupal 7 websites.<\/p><p>Before DrupalCon Lille, the module was used on 38,096 websites and was 173rd in the most used modules.<\/p><p>As of the 3rd of March, the Override Node Options module is used on 40,624 Drupal websites and is up to the 169th most used module.<\/p><p>That's pretty cool!<\/p>",
"cta": "testing_course",
"tags": ["software-development","drupal","php"]
}, {
"title": "Conventions over readability?",
"date": "1709856000",
"permalink": "/daily/2024/03/08/conventions-over-readability",
"text": "<p>I previously wrote about why you shouldn't use variable names like <code>$x<\/code> and <code>$y<\/code> in your code and why you should use more descriptive names.<\/p><p>But what if there is an existing convention?<\/p><p>For example, I use Lua to configure Neovim and noticed that it's common to use shortened variable names, such as <code>buffer<\/code> instead of <code>buffer_number<\/code> or <code>bufferNumber<\/code>.<\/p><p>It's also common to use the variable <code>M<\/code> to declare a module. For example:<\/p><pre><code class=\"language-lua\">local M = {}M.find_files = function() \/\/ ...endreturn M<\/code><\/pre><p>Whilst <code>Module<\/code> would be a more descriptive name, would deviating from the convention be more confusing for anyone reading the code?<\/p><p>Do the benefits of following a convention outweigh the benefits of using more descriptive variable and function names?<\/p><p>Which would be easier for newcomers to your project or team to understand and allow them to be productive sooner?<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Why write software for this?",
"date": "1709769600",
"permalink": "/daily/2024/03/07/why-write-software-for-this",
"text": "<p>Recently, when speaking with prospective clients, instead of focusing on the features they want, I like to ask questions like:<\/p><p>What's wrong with what you have now?<\/p><p>Why not fix what you have instead of rebuilding?<\/p><p>What problem are you trying to solve?<\/p><p>Why write software for this at all?<\/p><p>Why not do it manually?<\/p><p>Why do you need to do this now?<\/p><p>What results would you expect to see after this project?<\/p><p>If they can answer these types of questions and explain the business outcomes they're looking to achieve and what value I can add, those are the projects I want to work on.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Types are optional",
"date": "1709683200",
"permalink": "/daily/2024/03/06/types-are-optional",
"text": "<p>The main programming languages I write are PHP and JavaScript.<\/p><p>Both offer types where, as well as declaring a parameter or property, you can define what type it is - whether it's a string, array, boolean, etc.<\/p><p>Adding types is optional.<\/p><p>You don't need to add types to your PHP code, and you can choose to write plain JavaScript instead of TypeScript.<\/p><p>Some people prefer simpler or cleaner code or less \"visual debt\".<\/p><p>I like the extra clarity that types add.<\/p><p>I like to be able to read some code and immediately know what types things should be.<\/p><p>I like the clearer errors and messages if a different type is given than was expected.<\/p><p>Tools like PHPStan know more about my code and give better recommendations than if I don't add types.<\/p><p>I like the better autocompletion I get when writing code that has types.<\/p><p>I like types, but I also like the flexibility of whether or not to add them and for Developers and development teams to make their own decisions based on their preferences.<\/p>",
"cta": "subscription",
"tags": ["software-development","php"]
}, {
"title": "Why write framework-agnostic code",
"date": "1709596800",
"permalink": "/daily/2024/03/05/why-write-framework-agnostic-code",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/\/archive\/2024\/03\/04\/why-you-need-layers-in-your-application-code\">Yesterday<\/a>, I wrote about writing layers in your application code and the benefits of loosely coupled code.<\/p><p>Something else you can do with this approach is to write framework-agnostic code.<\/p><p>By writing your business logic in code that isn't tied to a specific framework or CMS, with a small adapter layer, you can upgrade to a newer version of the framework, such as Drupal 7 to 10, or a different framework, keep most of the code the same and only update the parts that connect the business logic and the framework.<\/p><p>This is something that Commerce Guys (now Centarro) did when creating Drupal Commerce 2.0.<\/p><p>The logic around addressing, tax, etc., was released in separate PHP libraries, each with its own release cycle and reusable logic.<\/p><p>This meant the Drupal modules were much smaller, and other eCommerce systems and frameworks could use the agnostic libraries.<\/p><p>It's something to consider when writing your next Drupal module.<\/p><p>It's something <a href=\"https:\/\/github.com\/opdavies\/national-rail-enquiries-feed-parser\">I did recently<\/a> and have done on client projects previously, and it can be a good approach.<\/p>",
"cta": "testing_course",
"tags": ["software-development","php","clean-code"]
}, {
"title": "Why you need layers in your application code",
"date": "1709510400",
"permalink": "/daily/2024/03/04/why-you-need-layers-in-your-application-code",
"text": "<p>You need to add an integration with a new service or supplier to your application code.<\/p><p>You should avoid writing code that interacts directly with that service or supplier - a.k.a tightly-coupled code.<\/p><p>What if you change to a different service or supplier in the future?<\/p><p>What if they release a new version of their API that includes breaking changes?<\/p><p>If your code is tightly coupled to a single implementation, you'd need to rewrite the code, and there wouldn't be a way to easily switch from the old version to the new one.<\/p><p>By introducing an adapter layer, you make your code more loosely coupled.<\/p><p>You can have multiple implementations, with one for each different supplier, service, or version.<\/p><p>You can have a consistent interface and API for every implementation, making them hot-swappable and making it easy to switch between different implementations.<\/p><p>If you change supplier or they release a new version, you write a new implementation for it and switch when you're ready.<\/p><p>Also, as every implementation satisfies a common interface, it's easy to make a fake implementation that you can use for testing.<\/p>",
"cta": "",
"tags": ["software-development","software-architecture","clean-code"]
}, {
"title": "Centarro and Drupal Commerce with Ryan Szrama",
"date": "1709424000",
"permalink": "/archive/2024/03/03/centarro-and-drupal-commerce-with-ryan-szrama",
"text": "<p>This week on Beyond Blocks, I'mj oined by Ryan Szrama, CEO of Centarro, to discuss Drupal Commerce, Commerce Kickstart, Mario Kart and the dreaded <code>cache_form<\/code> table.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/13-ryan-szrama-centarro\">Listen to the episode now<\/a>.<\/p><h2 id=\"key-points\">Key points<\/h2><ul><li>eCommerce, Ubercart and Drupal Commerce.<\/li><li>How Commerce Guys started.<\/li><li>How Ryan started in the eCommerce space.<\/li><li>The origins of Drupal Commerce and Commerce Guys.<\/li><li>Commerce Kickstart.<\/li><\/ul><h2 id=\"quotes\">Quotes<\/h2><ul><li>The best code isn't the most novel or most compact, it's the most easily readable and easily extendable (RS).<\/li><li>My only resource for learning PHP was php.net (RS)<\/li><li>I'm a self-taught Developer or community-taught, I suppose (OD).<\/li><li>Porting osCommerce into Drupal, which became Ubercart (RS).<\/li><li>Do we do this in Ubercart and Drupal 6 that we know works, or this new thing that was Drupal Commerce in Drupal 7 (OD).<\/li><li>It was built in Ubercart and was in production until quite recently, considering we're in 2024 (OD).<\/li><li>Once you get thoroughly entrenched in a platform, the cost to re-platform outweighs the cost of maintaining it in-house (RS).<\/li><li>If there's 10,000 of anybody, they're going to want to pay for support (RS).<\/li><li>How do we convince them to invest in an upgrade that doesn't see them jettison Drupal entirely? (RS)<\/li><li>One thing I like about Drupal Commerce is its flexibility. (OD)<\/li><li>It doesn't need to be a t-shirt or book shop. You can do some outside the box things with it. (OD)<\/li><li>Being a native extension of Drupal has a lot more advantages and pros than cons. (RS)<\/li><li>Ubercart was more \"batteries included\" and \"this is what it does\", whereas Drupal Commerce is more flexible and although it requires a bit more setup to begin with, you can plug it together the way you want to. (OD)<\/li><li>Our vision was to go the next step of getting off the Drupal island. (RS)<\/li><li>The Commerce Addressing library is now over 17,000,000 downloads. (OD)<\/li><li>Composer allowed us to separate our projects and separate our concerns. (RS)<\/li><li>Do you know when you should not use Views and when you decouple that component and use JavaScript and the REST API? (RS)<\/li><li>If we can reduce the number of times introduce those kinds of problems, that's how I would certify somebody. (RS)<\/li><\/ul>",
"cta": "d7eol",
"tags": ["software-development","drupal","drupal-commerce","podcast"]
}, {
"title": "Are your tests good enough?",
"date": "1709337600",
"permalink": "/daily/2024/03/02/are-your-tests-good-enough",
"text": "<p>You've been asked to add a new feature to or refactor some existing code.<\/p><p>Assuming you have automated tests already (if not, why not?), before you change the code, you should ask whether they're good enough.<\/p><p>They need to be passing, but do you feel confident the existing functionality will still work after you make your changes?<\/p><p>Do you have all the existing use cases covered?<\/p><p>If so, carry on.<\/p><p>If not, spend some time improving your tests first to get that confidence before making any changes.<\/p>",
"cta": "testing_course",
"tags": ["software-development","automated-testing","test-driven-drupal"]
}, {
"title": "Back to live streaming",
"date": "1709251200",
"permalink": "/daily/2024/03/01/back-to-live-streaming",
"text": "<p>Today, after saying I wanted to get back into it, I did my first live coding stream in over two years.<\/p><p>I spent around an hour and a half working on <a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">Build Configs<\/a> - a Symfony command line application I wrote to generate build configuration files.<\/p><p>To learn more about it, I <a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-build-configs\">gave a meetup talk<\/a> about it recently.<\/p><p>On stream, I explained what Build Configs is, added a <code>--dry-run<\/code> option that prevents any files from being created and started to look again at Behat to see how I might use it to test the app's functionality.<\/p><p>I want to do at least one stream a week going forward. Most likely, it will be on Friday afternoons.You can <a href=\"https:\/\/www.youtube.com\/watch?v=Wlkcf1PLWN8\">watch the full stream<\/a> on YouTube now. I'll split it into sections this week and upload some lightly edited versions to the same channel.<\/p><p>I won't post a link to every video here, so please subscribe to my YouTube channel to be notified when I go live next.<\/p>",
"cta": "subscription",
"tags": ["software-development","live-streaming","symfony","php"]
}, {
"title": "Experimenting with web components",
"date": "1709164800",
"permalink": "/daily/2024/02/29/experimenting-with-web-components",
"text": "<p>After my Beyond Blocks episode with Mark Conroy, I've spent some time this week experimenting with web components.<\/p><p>The team and I are building a new design system in Fractal and, as Drupal is our main application, we're using Twig as our templating language within Fractal so the changes are easier to port between systems.<\/p><p>Web components are agnostic, so they work within different languages and frameworks.<\/p><p>We also use other technologies, such as Vue.js, and third-party suppliers, so having an agnostic web component would reduce the time and effort needed to implement the design system across different technologies and applications.<\/p><p>If we can make self-contained web components that include their own styling and behaviour, that also improves re-usability and reduces the maintenance overhead as there would be one canonical version for everyone to use - not just a reference implementation everyone would need to recreate.<\/p><p>After this spike, I'm intrigued to see how we could use web components and what potential issues we can solve with them whilst reducing our implementation and maintenance efforts.<\/p><p>Are you interested in web components, too? <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/11-mark-conroy\">Listen to the podcast episode with Mark Conroy<\/a>.<\/p>",
"cta": "subscription",
"tags": ["softare-development","web-components","front-end"]
}, {
"title": "Why I don&#039;t branch",
"date": "1709078400",
"permalink": "/daily/2024/02/28/why-i-dont-branch",
"text": "<p>A few days ago, I asked <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/25\/why-do-people-still-use-git-flow\">why people are still using Git Flow in 2024<\/a>.<\/p><p>I moved to trunk-based development two years ago and haven't looked back.<\/p><h2 id=\"why-did-i-do-that%3F\">Why did I do that?<\/h2><p>Only having a single branch instead of separate <code>main<\/code> and <code>develop<\/code> branches and branches for each feature and fix is much simpler.<\/p><p>I don't get merge conflicts when trying to merge branches together, as everything is on a single branch.<\/p><p>A couple of years ago, I was working on two features for a project. I was demoing them to a client and broke my local environment when switching branches from feature A to feature B.<\/p><p>It was embarrassing, and it took me time to resolve the issues before I could continue working.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Working mostly on a single branch avoids merge conflicts, saves time, and simplifies my workflow.<\/p><p>No more confusion, merge conflicts or broken demos.<\/p>",
"cta": "d7eol",
"tags": ["softare-development","git"]
}, {
"title": "Building a design system in a few hours with Symfony",
"date": "1708992000",
"permalink": "/daily/2024/02/27/building-a-design-system-in-a-few-hours-with-symfony",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/11-mark-conroy\">I recently spoke with Mark Conroy<\/a>, Director of Development at Annertech, on the Beyond Blocks podcast.We discussed building something useful in a day and building design systems with web components.<\/p><p>Inspired by that conversation, I spent this afternoon experimenting with web components and seeing how I could use them within a design system we're building, as I think they can solve a particular need we have.<\/p><p>Following that, I thought I'd see how I could build my own design system and decided to do it with Symfony and see what I could achieve within a few hours.<\/p><p>It was a great opportunity to take Symfony 7 for a spin and explore and test some things that <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/10-ryan-weaver-symfonycasts\">Ryan Weaver and I discussed in our episode<\/a>, such as Symfony UX and Twig components.<\/p><p>Each component is a Twig component with its own PHP class and Twig template, which is rendered when I visit its URL, and I can use the HTML-like <code>&lt;twig:Logo \/&gt;<\/code> syntax to include child components.<\/p><p>You can <a href=\"https:\/\/github.com\/opdavies\/symfony-design-system\">view the code on GitHub<\/a>, and it may be something I use and work on in the future.<\/p>",
"cta": "d7eol",
"tags": ["softare-development","symfony","php","podcast"]
}, {
"title": "Docker and content creation with Nick Janetakis",
"date": "1708905600",
"permalink": "/daily/2024/02/26/docker-and-content-creation-with-nick-janetakis",
"text": "<p>This week's guest on the Beyond Blocks podcast is Nick Janetakis - a Software Developer, Docker Captain and Teacher who focuses on building and deploying web apps.<\/p><p>I'm a long-time consumer of Nick's content via his blog, YouTube channel and courses, so it was great to discuss Docker, content creation and more with him.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/12-nick-janetakis-docker\">Listen to the episode<\/a><\/p>",
"cta": "",
"tags": ["software-development","docker","podcast"]
}, {
"title": "Why do people still use Git Flow?",
"date": "1708819200",
"permalink": "/daily/2024/02/25/why-do-people-still-use-git-flow",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/talks\/git-flow\">The first conference talk I gave<\/a> was at DrupalCamp London 2014.<\/p><p>The talk was about Git Flow - a popular branching scheme I was using to manage a project, where there are different branches for development and production versions of the software and separate branches for features, releases and hotfixes.<\/p><p>It's been a standard approach as I've worked on different projects and teams, usually with pull or merge requests and code reviews.<\/p><p>But why do people still use it?<\/p><p>I was conducting technical interviews recently and every candidate explained how they used Git Flow or something inspired by it, and GitHub and GitLab have their own simplified versions.<\/p><p>Vincent Driessen wrote the original Git Flow blog post in January 2010, though he updated it in March 2020 to add this note of reflection:<\/p><blockquote> <p>This model was conceived in 2010, now more than 10 years ago, and not very long after Git itself came into being. In those 10 years, git-flow (the branching model laid out in this article) has become hugely popular in many a software team to the point where people have started treating it like a standard of sorts \u2014 but unfortunately also as a dogma or panacea.<\/p> <p>During those 10 years, Git itself has taken the world by a storm, and the most popular type of software that is being developed with Git is shifting more towards web apps \u2014 at least in my filter bubble. Web apps are typically continuously delivered, not rolled back, and you don't have to support multiple versions of the software running in the wild.<\/p> <p>This is not the class of software that I had in mind when I wrote the blog post 10 years ago. If your team is doing continuous delivery of software, I would suggest to adopt a much simpler workflow (like GitHub flow) instead of trying to shoehorn git-flow into your team.<\/p> <p>If, however, you are building software that is explicitly versioned, or if you need to support multiple versions of your software in the wild, then git-flow may still be as good of a fit to your team as it has been to people in the last 10 years. In that case, please read on.<\/p> <p>To conclude, always remember that panaceas don't exist. Consider your own context. Don't be hating. Decide for yourself.<\/p><\/blockquote><p>Since adopting trunk-based development and continuous integration and delivery, I've worked faster and avoided merge conflicts, which wasn't the case before, even when I was the only one working on a codebase.<\/p><p>It's a simpler workflow.<\/p><p>I don't need to think about whether this branch is a feature or a hotfix, and I've rarely seen release and hotfix branches used as described in the original blog post.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Do what works best for you and your team, but don't adopt something because it's the \"standard\" approach.<\/p>",
"cta": "d7eol",
"tags": ["software-development","git"]
}, {
"title": "When should you start writing tests?",
"date": "1708732800",
"permalink": "/daily/2024/02/24/when-should-you-start-writing-tests",
"text": "<p>When you start a new project, when should you start writing tests and doing test-driven development?<\/p><p>Is it before you write any code, or is it something you can start later?<\/p><p>When starting <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/19\/introducing-versa\">versa<\/a>, I was only scaffolding the console commands and running some basic commands such as \"composer install\" and \"phpunit\".<\/p><p>At that point, there wasn't any business logic to test.<\/p><p>The first versions only supported PHP, so there was no complexity around which language the project used.<\/p><p>There was no logic to determine which language or package manager was used.<\/p><p>Now I've started to add this functionality - such as determining the project type from its composer.json or package.json file - there is logic to test, and I've started to write tests and do test-driven development.<\/p><p>At this phase, I can see the value, which I couldn't when setting up the application to begin with, and different have any logic worth testing.<\/p>",
"cta": "subscription",
"tags": ["software-development","php","automated-testing","test-driven-development"]
}, {
"title": "Slow down to go fast",
"date": "1708646400",
"permalink": "/daily/2024/02/23/slow-down-to-go-fast",
"text": "<p>I've recently been improving my typing.<\/p><p><img src=\"https:\/\/www.oliverdavies.uk\/assets\/images\/daily-emails\/typing.png\" alt=\"A screenshot of a typing test.\" \/><\/p><p>My speed is usually good, but my accuracy is not where I'd like it to be (it's usually around 95%, and I'd like it to be nearer 99%).<\/p><p>It may seem counterintuitive, but I need to slow down to get faster.<\/p><p>But not focusing on the speed and prioritising accuracy, I'll still get faster as I'm not mistyping as many keys.<\/p><p>It's the same when I run.<\/p><p>My first few kilometres are slower as I get into the run, find my pace, focus on breathing, etc.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>The same can also be said for automation and automated testing.<\/p><p>They require some time investment initially but will save time as a project evolves and becomes more complex.<\/p><p>You need to slow down initially to go faster later.<\/p>",
"cta": "subscription",
"tags": ["software-development","automated-testing"]
}, {
"title": "Diffy and visual regression testing",
"date": "1708560000",
"permalink": "/daily/2024/02/22/diffy-and-visual-regression-testing",
"text": "<p>I recently recorded an episode of <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">Beyond Blocks<\/a> with Yuri Gerasymov, who runs Diffy.<\/p><p>He and I discussed visual regression testing, why you'd use it, and some features Diffy offers.<\/p><p>I usually write a combination of browser, kernel and unit tests within an application framework like Drupal and Symfony or behavioural tests with Behat.<\/p><p>These validate that my logic works as expected and that functions return the correct results or pages return the correct response codes and content.<\/p><p>There are types of issues, though, such as breakages within the page layout or structure, which these tests won't discover but can be identified by visual regression tests that compare before and after screenshots.<\/p><p>I added to my website during the recording and can see what value it offers as an additional layer of testing on top of the tests I already write.<\/p>",
"cta": "subscription",
"tags": ["software-development","automated-testing"]
}, {
"title": "Coding defensively and considering the unhappy path",
"date": "1708473600",
"permalink": "/daily/2024/02/21/coding-defensively-and-considering-the-unhappy-path",
"text": "<p>Last week, whilst speaking about Sculpin at PHP South West, I showed an example from a client project I'd built with Sculpin.<\/p><p>The project was for a local gym and fitness centre, and I was demonstrating how I'd created the timetable page and kept the data separate from the HTML and Twig markup so the client could easily administer it (they edit the files on GitHub, which triggers a rebuild of the website).<\/p><p>Each class should have a name and start and end times and be on a specified day.<\/p><p>But what if the client didn't include a name or start or end time?<\/p><p>What if they put a number or boolean instead of a string?<\/p><p>What if there are no classes on a particular day?<\/p><p>You don't know how people will use your software, so it's best to be defensive - validate and verify things before rendering them and prevent the page or whole application from breaking if something isn't as you expected or assumed.<\/p><p>We also can't assume the \"happy path\" will always be correct.<\/p><p>What if there aren't any classes? Do we put an empty message on the timetable or not show that day?<\/p><h2 id=\"another-scenario\">Another scenario<\/h2><p>If you were retrieving or posting data to an API endpoint, would you assume it was successful or verify the response code is what you expected?<\/p><p>If you get the data, do you check if it's in the correct format and something you can use?<\/p><p>If not, do you verify other actions in your application haven't run and it's not in an invalid state?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>In PHP, a common approach is to use the <code>assert()<\/code> function, as we saw in <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/20\/which-level-is-right-for-you\">yesterday's email<\/a>.<\/p><p>Then, write automated tests that don't test just the happy path but also the unhappy paths.<\/p>",
"cta": "d7eol",
"tags": ["software-development","automated-testing","php"]
}, {
"title": "Which level is right for you?",
"date": "1708387200",
"permalink": "/daily/2024/02/20/which-level-is-right-for-you",
"text": "<p>Today, whilst working on <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/19\/introducing-versa\">Versa<\/a>, I was experimenting with different PHPStan levels.<\/p><p>Level 1 is the least strict level, and applies the fewest rules and returns the fewest results.<\/p><p>As you increase the level, the stricter PHPStan is.<\/p><h2 id=\"levelling-up-to-9\">Levelling up to 9<\/h2><p>Here is the code to get the values of the <code>--extra-args<\/code> and <code>--working-dir<\/code> options:<\/p><pre><code class=\"language-php\">$extraArgs = $input-&gt;getOption('extra-args');$workingDir = $input-&gt;getOption('working-dir');<\/code><\/pre><p>This passed PHPStan level 8, but these are the errors I get when running level 9:<\/p><pre><code class=\"language-plain\">------ ------------------------------------------------------------------------------------------------------- Line versa------ ------------------------------------------------------------------------------------------------------- 61 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 62 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given. 72 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 73 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given. 84 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 85 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given. 94 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 95 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given. 104 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 105 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given. 119 Parameter $extraArgs of static method App\\Process\\Process::create() expects string|null, mixed given. 120 Parameter $workingDir of static method App\\Process\\Process::create() expects string, mixed given.------ -------------------------------------------------------------------------------------------------------[ERROR] Found 12 errors<\/code><\/pre><p>The issue is that <code>$input-&gt;getOption()<\/code> from Symfony's <code>InputInterface<\/code> returns <code>mixed<\/code> - even though it always returns <code>null<\/code> or a string.<\/p><p>If I did <code>--working-dir 2<\/code>, it would return the string <code>\"2\"<\/code>.<\/p><p>An empty string throws an error, and an empty value (if there are no extra arguments) returns <code>null<\/code>.<\/p><p>So, I know <code>$workingDir<\/code> will always be a string and <code>$extraArgs<\/code> will either a string or <code>null<\/code>.<\/p><h2 id=\"passing-level-8\">Passing level 8<\/h2><p>To pass level 8, PHPStan needs to be sure the variables are what I think they are.<\/p><p>Here's the code I can use to get it to pass:<\/p><pre><code class=\"language-php\">$extraArgs = $input-&gt;getOption('extra-args');$workingDir = $input-&gt;getOption('working-dir');assert(is_string($extraArgs) || is_null($extraArgs));assert(is_string($workingDir));<\/code><\/pre><p>By using <code>assert()<\/code> and throwing an Exception if the condition fails, PHPStan is now happy with the code and my code passes level 9.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Although the extra code gets PHPStan to pass, it it worth it?<\/p><p>Is this extra code adding value? Does it make the code more readable or is it likely to prevent a bug?<\/p><p>In this case, I know the value will always be the type I expect.<\/p><p>I can work around this using a baseline or annotations for PHPStan to ignore these lines, <strong>or is level 8 good enough for this project<\/strong>?<\/p><p>Similar to 100% test coverage, is aiming for the highest PHPStan level an objective to be met, or is enough value being added added by the lower level?<\/p><p>Which level is right for you and this codebase?<\/p>",
"cta": "",
"tags": ["software-development","static-analysis","php","phpstan"]
}, {
"title": "Introducing Versa - the versatile CLI tool",
"date": "1708300800",
"permalink": "/daily/2024/02/19/introducing-versa",
"text": "<p>Today, I started to build a new open-source project - Versa, the versatile command-line tool that standardises common commands across projects.<\/p><p>After watching a Twitch streamer building something similar in Rust, I decided to build my take on it and add features I'd need, such as support for local vs Docker-based commands and to run different commands for different projects.<\/p><p>For example, <code>versa run<\/code> would need to run different commands for Drupal and Sculpin projects, <code>versa test<\/code> should support different test frameworks for the same language - e.g. PHPUnit, Pest and ParaTest for PHP - and the commands will need to be different in Docker Compose-based projects.<\/p><p>Currently, this logic is within my <a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">Build Configs<\/a> project but can be moved to Versa.<\/p><p>This reduces the complexity within that codebase and means I can open-source it as it's a separate project.<\/p><p>At the moment, I've added PHP as the only supported language but I will add JavaScript\/TypeScript support so it supports projects like Fractal.<\/p><p>It's still in the prototype phase and includes some initial commands, but the interesting parts will be making it clever.<\/p><p>Instead of running <code>versa run --type sculpin<\/code>, I'd like to just do <code>versa run<\/code> and have it determine the type of project automatically.<\/p><p><code>versa test<\/code> should be able to determine the testing framework automatically based on what's in the project's <code>composer.json<\/code> file instead of having to specify it.<\/p><p>Likewise, for JavaScript, <code>versa install<\/code> should be able to determine if <code>npm<\/code>, <code>yarn<\/code> or <code>pnpm<\/code> is used.<\/p><p>That'll be where the more complex code will be added and when I start doing test-driven development - maybe with Behat, which is also something I've been thinking about for Build Configs.<\/p><p>Interested? <a href=\"https:\/\/github.com\/opdavies\/versa\">Take a look at the code<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","php","symfony","open-source"]
}, {
"title": "Build something useful in one day with Mark Conroy",
"date": "1708214400",
"permalink": "/daily/2024/02/18/build-something-useful-in-one-day-with-mark-conroy",
"text": "<p>This week on the Beyond Blocks podcast, I'm joined by Mark Conroy - Director of Development at Annertech to discuss all things front-end development and building something useful in one day.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/11-mark-conroy\">Listen now<\/a><\/p><h2 id=\"talking-points\">Talking points<\/h2><ul><li>Building better websites faster, including Drupal distributions, such as LocalGov.<\/li><li>What Drupal gives you out of the box and using the right tool for the job.<\/li><li>Drupal migrations and migrating Drupal configuration from a spreadsheet.<\/li><li>Saving time and improving efficiency by standardising base builds with Docksal and Composer.<\/li><li>How to build projects, like the Running Plan Generator, in a day and training for 10Ks and marathons.<\/li><li>Prioritising tasks.<\/li><li>Annertech's development workflow and standardisation by developing on remote servers.<\/li><li>Why you may not need preprocessors and complicated front-end build tools, and reducing complexity using vanilla CSS, JavaScript and web components.<\/li><li>Lowering the barrier to entry to contribute to open-source projects.<\/li><li>Building a design system\/component library with web components.<\/li><li>The Content Access by Path module that was developed for Essex County Council.<\/li><\/ul>",
"cta": "d7eol",
"tags": ["podcast","drupal","front-end","software-development","css"]
}, {
"title": "Another way to create test module configuration",
"date": "1708128000",
"permalink": "/daily/2024/02/17/another-way-to-create-test-module-configuration",
"text": "<p>In one of the lessons in my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">free automated testing in Drupal email course<\/a>, I explain how I create configuration that I need within my tests, such as adding a custom field:<\/p><blockquote> <p>But how do you know what to name the configuration files and what content to put in them?<\/p> <p>Rather than trying to write them by hand, I create the configuration I need, such as fields, within a Drupal site and then export and edit the files I need.<\/p><\/blockquote><p>As well as creating the fields in the Drupal UI, I was also using it to export the configuration files I needed:<\/p><blockquote> <p>Once Drupal is installed and the configuration has been created, you can go to - \/admin\/config\/development\/configuration\/single\/export and select the configuration type and name.<\/p> <p>The filename is shown at the bottom of the page, and you can copy the content into files within your module.<\/p><\/blockquote><h2 id=\"there%27s-another-way\">There's another way<\/h2><p>After reading that lesson, somene replied and reminded me that there's a <code>--destination<\/code> option you can use with the <code>drush config:export<\/code> command.<\/p><p>Instead of exporting to the standard configuration directory, I can do it to a temporary directory:<\/p><pre><code class=\"language-shell\">run drush cex --destination \/app\/.ignored\/config<\/code><\/pre><p>Everyhing in a <code>.ignored<\/code> direcotry is automatically ignored by Git, and to get the files I need, I can use Linux's <code>find<\/code> command to find any files that contain the field name and copy them into my test module directory:<\/p><pre><code class=\"language-shell\">find .ignored\/config \\ -type f \\ -name \\*drupal_project\\* \\ -exec cp -r {} web\/modules\/custom\/foo\/modules\/foo_test\/config\/install \\;<\/code><\/pre><p>I still need to edit the files to remove the <code>uuid<\/code> and <code>_core<\/code> values, but this approach means less clicking in the Drupal UI which makes me more productive.<\/p><p>I used this approach when <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/16\/keep-logic-within-tests-for-as-long-as-you-can\">writing my SaaS code yesterday<\/a> and it worked well.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","drupal","php"]
}, {
"title": "Keep logic within tests for as long as you can",
"date": "1708041600",
"permalink": "/daily/2024/02/16/keep-logic-within-tests-for-as-long-as-you-can",
"text": "<p>Inspired by some recent podcast guests, I've started writing the first code for a Drupal-based SaaS product that I've been thinking of creating.<\/p><p>Here's an early iteration of the first test I wrote:<\/p><pre><code class=\"language-php\">public function test_it_creates_a_project_node_from_json(): void { self::assertNull(Node::load(id: 1)); $this-&gt;installEntitySchema(entity_type_id: 'node'); $this-&gt;installConfig(modules: self::$modules); $projectData = json_decode(json: self::$projectJson, associative: TRUE); self::assertNotNull($projectData); Node::create([ 'title' =&gt; $projectData['list'][0]['title'], 'type' =&gt; 'drupal_project', ])-&gt;save(); $node = Node::load(id: 1); self::assertNotNull($node); self::assertInstanceOf(actual: $node, expected: NodeInterface::class); self::assertSame(actual: $node-&gt;label(), expected: 'Override Node Options'); self::assertSame( actual: $node-&gt;get('field_drupalorg_node_id')-&gt;getString(), expected: strval(107871), );}<\/code><\/pre><p>It checks that, given some defined JSON data, it will create a node in my database.<\/p><p>It confirms no node ID exists when starting, runs some setup setups (this is a Kernel test), decodes the JSON, creates the node and asserts it contains the expected values.<\/p><p>There are two things that you may be wondering...<\/p><ul><li>Why do you have test setup code that you'll need within the test? Won't you need that for every test?<\/li><li>Why are you creating the node within the test and not somewhere else?<\/li><\/ul><p>The answer to both is that this is the first test, and I want to write <strong>as little code as possible for it to pass<\/strong>.<\/p><p>When I write the second test, I'll either need to duplicate the setup lines or extract them to a <code>setUp()<\/code> method.<\/p><p>I'll also need to refactor the code that creates the node.<\/p><p>Once I've written the second test, to get it to pass, I refactored to use Repository, Builder and Action classes.<\/p><p>If there's a regression, the test I had will fail, and I could revert to the passing version before reattempting the refactor.<\/p><p>With test-driven development, I want to work in small and simple steps and get to green by making the smallest and easiest possible change.<\/p><p>When I have a test that forces me to refactor and adopt a more complex approach, I'll do it.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","drupal","php","phpunit"]
}, {
"title": "gray or grey, and center or centre?",
"date": "1707955200",
"permalink": "/daily/2024/02/15/gray-or-grey--and-center-or-centre",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/blog\/renaming-gray-grey-tailwind-css\">I previously wrote<\/a> about how to change <code>gray<\/code> to <code>grey<\/code> in Tailwind CSS.<\/p><p>So, instead of writing <code>bg-gray-200<\/code>, I could write <code>bg-grey-200<\/code>.<\/p><p>This would be the correct spelling, as I live in the UK.<\/p><p>But I recently realised that I don't change <code>text-center<\/code> or <code>items-center<\/code> when 'centre' would also be the correct spelling.<\/p><p>So, what value is there to renaming <code>gray<\/code>?<\/p><p>It adds inconsistency as it mixes US and UK English in this project and inconsistencies between different projects.<\/p><p>It doesn't match the CSS colour name.<\/p><p>And, if I'm working with others on a project, they also need to be aware of this as it's different from the default configuration and could cause some confusion and affect productivity.<\/p><p>Keeping it the default value would make it easier to work on, collaborate on and maintain.<\/p><p>Maybe, I'll leave it as <code>gray<\/code> in the future.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "Major version updates are just removing deprecated code",
"date": "1707868800",
"permalink": "/daily/2024/02/14/major-version-updates-are-just-removing-deprecated-code",
"text": "<p>Today, I've been watching the new <a href=\"https:\/\/symfonycasts.com\/screencast\/symfony7-upgrade\">Upgrading &amp; What's in Symfony 7<\/a> video course on SymfonyCasts.<\/p><p>The first video - <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/10-ryan-weaver-symfonycasts\">recent podcast guest Ryan Weaver<\/a> - explains how Symfony's release cycle works.<\/p><p>New feature releases that contain new features are every six months.<\/p><p>Along with the x.4 release - such as Symfony 6,4 - there is also a new major release - in this case, Symfony 7.<\/p><p>They are essentially identical, except for code that was deprecated in Symfony 6, which has been removed.<\/p><p>So, updating from Symfony 6.4 to 7 means you just need to remove any deprecated code from your application and make it work in the Symfony 7 way.<\/p><p>This is also how Drupal releases new versions, too.<\/p><p>New releases, like Layout Builder, are added in minor versions like 8.1, and Drupal 9 is Drupal 8 without its deprecated code.<\/p><p>Because the code in major versions is so similar, <strong>contributed modules and themes can support multiple major versions at the same time<\/strong>.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>When upgrading projects from Drupal 8 to 9 and 9 to 10, the majority of the work can be done beforehand by keeping up to date with module releases and updating custom code to remove any deprecations.<\/p><p>This means the upgrade can be split over several weeks or months to reduce the risk.<\/p><p>Then, finally, you <em>just<\/em> update to the next major version.<\/p><p>All the hard work has already been done.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","symfony"]
}, {
"title": "It takes the drama out of open-source",
"date": "1707782400",
"permalink": "/daily/2024/02/13/it-takes-the-drama-out-of-open-source",
"text": "<p>As well as the code changes, such as adopting Symfony components and other third-party code, one of my favourite things about Drupal since D8 is the new release cycle.<\/p><p>Instead of \"It'll be ready when it's ready.\", since Drupal 8, Drupal releases new versions on fixed dates.<\/p><p>If a feature is ready by that date, it will be included.<\/p><p>If not, it will be included in a later\u00a0version.<\/p><p>As well as regular bug fixes and security updates, there is a new feature release every six months.<\/p><p>Drupal 8.1 included features like the Layout Builder, which wasn't included in 8.0.<\/p><p>In earlier Drupal versions, it would have been deferred to the next major version, making it longer before users get its benefits.<\/p><p>A fixed release schedule makes it easier for users and Developers to plan their updates and prepare to upgrade to the major version.<\/p><p>As Ryan said on a <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/10-ryan-weaver-symfonycasts\">recent episode of Beyond Blocks<\/a>, \"It takes the drama out of open-source\".<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "Symfony conventions making their way to Drupal",
"date": "1707696000",
"permalink": "/daily/2024/02/12/symfony-conventions-making-their-way-to-drupal",
"text": "<p>Drupal 8 was a major turning point for Drupal when it was released in 2015.<\/p><p>Moving from \"not invented here\" to \"proudly found elsewhere\" and \"getting off the island\", Drupal 8 introduced Composer to Drupal core and several of the Symfony PHP components.<\/p><p>Following Drupal 8's release, Drupal core started to follow semantic versioning and, six months later, released Drupal 8.1.0 with new features.<\/p><p>In comparison, Drupal 7, with non-semantic versioning, is now on version 7.99.<\/p><p>The approach to having fixed release dates instead of feature-based release dates is also used in Symfony, which makes it much easier to plan for.<\/p><p>The differences between major versions, such as Drupal 9 and 10, is the removal of deprecated code - making it much easier than ever before to upgrade to the new major version of Drupal core. Sometimes, you won't need to update any custom code - especially if it's been maintained and updated during the minor releases.<\/p><p>I've been pleased to see Symfony features such as autowiring and autoconfiguration start to be used within Drupal, as well as discussions around using PHP attributes to replace annotations and docblocks.<\/p><p>Most recently, when writing my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">automated testing email course<\/a>, I saw a number of aliases have been added to core's <code>core.services.yml<\/code> file, which means I can use the fully qualified class name as the service name without adding aliases to my own services files.<\/p><p>Drupal and Symfony are separate projects, and Drupal uses more than just Symfony components, but as someone who uses Drupal and Symfony, I'm happy to see them learning from and inspiring each other.<\/p><p>I'm looking forward to seeing the next thing - <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/10-ryan-weaver-symfonycasts\">Twig components<\/a>, maybe - in Drupal.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","symfony"]
}, {
"title": "Twig, Symfony and SymfonyCasts with Ryan Weaver",
"date": "1707609600",
"permalink": "/daily/2024/02/11/ryan-weaver",
"text": "<p>This week's guest on Beyond Blocks is <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/10-ryan-weaver-symfonycasts\">Ryan Weaver<\/a>.<\/p><p>Ryan is a Symfony Developer, Symfony core team member and writer for SymfonyCasts.<\/p><p>We discussed recent developments in Twig templates, SymfonyCasts, release cycles, and similarities between the Drupal and Symfony projects and communities.<\/p><p>I've been a long-time subscriber of SymfonyCasts and it was a big help when I was learning Drupal 8 for Twig and object-orientated PHP, so it was great to speak with Ryan.<\/p>",
"cta": "",
"tags": ["software-development","php","symfony","drupal","podcast","beyond-blocks"]
}, {
"title": "Do you really need it?",
"date": "1707523200",
"permalink": "/daily/2024/02/10/do-you-really-need-it",
"text": "<p>Before adding a new feature or change to a codebase, ask if it's really needed and consider its long-term implications.<\/p><p>Code is easy to write, but needs to be maintained as newer language or framework features are added or have breaking changes.<\/p><p>Something I've added recently to Build Configs was an option to use an <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/01\/27\/gitignore-inclusive-or-exclusive\">inclusive or exclusive .gitignore file<\/a>.<\/p><p>Whilst it's only adding an if condition based on a value, it adds a separate path in my code and both need to be maintained.<\/p><p>I've been thinking of adding <code>just<\/code> again to some projects instead of a <code>run<\/code> file, which would add separate files that need to be maintained and kept up-to-date with each other so both offer the same features.<\/p><p>Is this something I want to maintain going forward? Does it add enough value to justify its maintenance?<\/p><p>Different to a feature flag, which usually has a known lifespan, this could need be maintained for the whole lifespan of the application.<\/p><p>On a client project, this could be having two sets of buttons with rounded and square corners.<\/p><p>Do we need both?<\/p><p>It could be the positioning of a title in a header. Fewer options mean there is less code to write and maintain.<\/p><p>In a Drupal project, each choice could mean adding a different field, taxonomy term, or content or block type to achieve the desired result.<\/p><p>The more we can achieve with fewer options means the application will be easier to maintain and work on in the future.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Defining boundaries between custom Drupal modules",
"date": "1707436800",
"permalink": "/daily/2024/02/09/defining-boundaries-between-custom-drupal-modules",
"text": "<p>I recently made a change to a Drupal project with several custom modules.<\/p><p>As part of the change, there was a method that was no longer being used, so I went ahead and removed it.<\/p><p>There were no tests for this part of the codebase, and the existing tests were still passing.<\/p><p>My change was successfully finished and deployed, including removing the unused method.<\/p><p>A few days later, we noticed cron jobs were no longer running on the website.<\/p><p>The method I'd removed was attempting to be called from within a different module.<\/p><p>Because it no longer existed, it was causing an error and stopping the cron job from running successfully.<\/p><p>When I re-added the method, the cron jobs worked again.<\/p><p>There were no <code>dependencies<\/code> set in either module's .info.yml file, though that would only prevent you from uninstalling either module.<\/p><p>It wouldn't prevent me from deleting code used by another module.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>This is why I've been <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/08\/experimenting-with-architectural-testing\">experimenting with architectural testing<\/a>. To ensure that modules only use their own code and to start enforcing layers within each module.<\/p><p>Then, if I had the same situation again, I'd know straight away that there was an issue and not have to wait for the bug to be deployed to production.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","architectural-testing","php","drupal"]
}, {
"title": "Experimenting with Architectural Testing",
"date": "1707350400",
"permalink": "/daily/2024/02/08/experimenting-with-architectural-testing",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/02\/07\/running-tests-in-parallel-with-paratest\">In yesterday's email<\/a>, I mentioned parallel testing and speeding up your tests by running them in parallel.<\/p><p>Something else I've been experimenting with recently in architectural testing with PHPat.<\/p><p>For example, ensuring classes within a namespace are <code>final<\/code> or not, that Controller classes all extend <code>ControllerBase<\/code> and have the Controller suffix in their names.<\/p><p>Going forward, I'd like to ensure that each Drupal module only uses its own classes and is separated, as I recently had an issue where I deleted a class method in one module only to find it was used in a different module.<\/p><p>Here's what I have so far for my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">testing course codebase<\/a>:<\/p><pre><code class=\"language-php\">final class ArchitectureTest { public function test_classes_should_be_final(): Rule { return PHPat::rule() -&gt;classes(Selector::inNamespace('Drupal\\atdc')) -&gt;shouldBeFinal(); } public function test_controllers_should_extend_ControllerBase(): Rule { return PHPat::rule() -&gt;classes(Selector::inNamespace('Drupal\\atdc\\Controller')) -&gt;shouldExtend() -&gt;classes(Selector::classname(ControllerBase::class)); } public function test_controllers_should_have_the_Controller_suffix(): Rule { return PHPat::rule() -&gt;classes(Selector::inNamespace('Drupal\\atdc\\Controller')) -&gt;shouldBeNamed( classname: '\/Controller$\/', regex: TRUE, ); }}<\/code><\/pre><p>I plan to continue expanding this configuration as I become more familiar with PHPat, and because it's a PHPStan extension, it's already available to run within my projects locally and within the CI pipeline.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing","architectural-testing","php"]
}, {
"title": "Running tests in parallel with Paratest",
"date": "1707264000",
"permalink": "/daily/2024/02/07/running-tests-in-parallel-with-paratest",
"text": "<p>Something that I've recently added to my PHP projects is <a href=\"https:\/\/github.com\/paratestphp\/paratest\">Paratest<\/a>.<\/p><p>It adds parallel testing to PHPUnit, so your tests will be run in parallel instead of sequentially.<\/p><p>For the example module in my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">automated testing in Drupal email course<\/a>, using Paratest reduces the execution time from ~16 seconds to ~8 seconds.<\/p><p>In a client project with 136 tests, it reduces the time from four and a half minutes to less than two minutes.<\/p><p>This is a big improvement just from running a single Composer command to add Paratest.<\/p><p>There's also <a href=\"https:\/\/www.drupal.org\/project\/drupal\/issues\/2781123\">an open issue<\/a> for using it for Drupal core's tests, which is something I'll keep an eye on and will look to contribute to.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","phpunit"]
}, {
"title": "Tim Lehnen and the Drupal Association",
"date": "1707177600",
"permalink": "/daily/2024/02/06/tim-lehnen-and-the-drupal-association",
"text": "<p>Last week on the Beyond Blocks podcast, I spoke with Tim Lehnen - CTO and former colleague at the Drupal Association.<\/p><p>We discussed what the Drupal Association is and what it does, how companies and individuals can contribute and support the Association, some recent and upcoming improvements to Drupal.org, Drupal 7's end-of-life, and more.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/9-tim-lehnen\">Listen now<\/a><\/p><p>This Friday, I'm releasing an episode with Ryan Weaver from SymfonyCasts.<\/p>",
"cta": "",
"tags": ["drupal","drupal-association","podcast","php","phpc"]
}, {
"title": ".gitignore or .gitallow",
"date": "1707091200",
"permalink": "/daily/2024/02/05/gitignore-or-gitallow",
"text": "<p>Following last week's email on <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/01\/27\/gitignore-inclusive-or-exclusive\">different ways to write .gitignore files<\/a>, friend of the list, Daniel Harper, sent me this reply (shared with permission):<\/p><blockquote> <p>I had a debate once about this topic and we settled on ignore as the filename explicitly describes what it should be doing ie. It's not .gitallow \ud83d\ude06<\/p><\/blockquote><p>This is a good point.<\/p><p>What do people expect to see in a <code>.gitignore<\/code> file?<\/p><p>A list of directories and files to be ignored or allowed?<\/p><p>Based on the filename, it should be the former.<\/p><p>This would be clearer for people when they first open the file.<\/p><p>However, if you decide to use the allow approach instead, document it in an <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/23\/adrs-technical-design-documents\">ADR or design document<\/a> and why you decided to do it that way and provide context for people working on the codebase in the future.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Speaking about Sculpin at PHPSW",
"date": "1707004800",
"permalink": "/daily/2024/02/04/speaking-about-sculpin-at-phpsw",
"text": "<p>I'm happy to be speaking again at <a href=\"https:\/\/www.meetup.com\/php-sw\/events\/298880313\">PHP South West<\/a> next week for my 98th talk or workshop and eighth at PHPSW.<\/p><p>This talk will be on <a href=\"https:\/\/sculpin.io\">Sculpin<\/a> - a static site generator written in PHP.<\/p><p>I first presented a Sculpin talk at <a href=\"https:\/\/www.oliverdavies.uk\/talks\/test-drive-twig-with-sculpin\">DrupalCamp North in July 2015<\/a> while learning Twig before Drupal 8.<\/p><p>If you'd like a sneak peek of the demo site I'm building, <a href=\"https:\/\/github.com\/opdavies\/phpsw-sculpin-demo\">it's on GitHub<\/a>, and I posted a screenshot on <a href=\"https:\/\/twitter.com\/opdavies\/status\/1754629305575874738\">Twitter<\/a>.<\/p>",
"cta": "",
"tags": ["php","phpc","sculpin"]
}, {
"title": "Reducing complexity makes contribution easier",
"date": "1706918400",
"permalink": "/daily/2024/02/03/reducing-complexity-makes-contribution-easier",
"text": "<p>This week, I spoke with <a href=\"https:\/\/mark.ie\">Mark Conroy<\/a> for an upcoming episode of the <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">Beyond Blocks podcast<\/a>.<\/p><p>We discussed his approach to removing front-end build tools from projects, including the LocalGov Drupal base theme.<\/p><p>Doing this removes dependencies such as Sass and tools like Webpack but also makes it easier for others to contribute as there's less to learn.<\/p><p>The barrier to entry is lower.<\/p><p>This is a big advantage in the open-source space and for companies and project teams.<\/p><p>Having simpler code and fewer tools makes it easier for others to understand and work on your codebase, making them productive sooner.<\/p>",
"cta": "",
"tags": ["software-development","front-end","beyond-blocks","podcast","drupal","localgov-drupal"]
}, {
"title": "Automated tests prevent you from adding regressions",
"date": "1706832000",
"permalink": "/daily/2024/02/02/automated-tests-prevent-you-from-adding-regressions",
"text": "<p>Continuing from <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/01\/30\/tdd-doesnt-mean-you-know-everything-upfront\">my last few emails<\/a>, as well as adding the new use case more easily and quicker, having automated tests also saved me from adding a regression into the code I was changing.<\/p><p>I'd written a condition in the query to ensure only results that started with the search term.<\/p><p>Initially, I removed it, but then the tests failed.<\/p><p>This reminded me why I'd written the condition that way, and I was able to re-add my fix differently.<\/p><p>Without the tests, I'd likely have removed it and introduced a regression.<\/p><p>Whilst fixing a bug, I'd have introduced a different bug.<\/p><p>My tests saved me from doing that and I was able to rectify it quickly before pushing to CI or the staging environment.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Start with a failing test",
"date": "1706745600",
"permalink": "/daily/2024/02/01/start-with-a-failing-test",
"text": "<p>When fixing a bug or adding a new feature using test-driven development, it's important to see the test fail first.<\/p><p>You should write your test so it doesn't pass by default or accidentally.<\/p><p>When creating data, such as users or nodes within tests, do so in a way that will force the test to fail, such as explicitly setting the title or published date into a non-default order.<\/p><p>When fixing a bug, write a test that represents the expected outcome when the bug is fixed. This confirms the bug exists and can be replicated.<\/p><p>Then, once the tests pass, you know the feature or fix is working and that it's because of your changes and not for any other reason.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Automated tests mean you can make changes quicker",
"date": "1706659200",
"permalink": "/daily/2024/01/31/automated-tests-mean-you-can-make-changes-quicker",
"text": "<p>Before fixing <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/01\/30\/tdd-doesnt-mean-you-know-everything-upfront\">yesterday's bug<\/a>, because I'd written automated tests, I ran them to ensure they were all passing.<\/p><p>Then, I was able to focus solely on adding the new use case - starting with a failing test to replicate the issue and then getting it to pass.<\/p><p>Because it was already tested, I didn't need to worry about breaking any other functionality and introducing regressions.<\/p><p>When the new test was passing, I could run the whole test suite and ensure they still passed and things continued to work.<\/p><p>Without the tests, I'd either need to check everything else manually (which takes time) or worry that something could potentially be broken.<\/p><p>Having tests meant I could be confident that the new and existing functionality worked.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "TDD doesn&#039;t mean you know everything upfront",
"date": "1706572800",
"permalink": "/daily/2024/01/30/tdd-doesnt-mean-you-know-everything-upfront",
"text": "<p>I'm in the final phase of a Drupal development project for a customer.<\/p><p>It has some custom modules and code I wrote with automated tests and test-driven development.<\/p><p>Today, the client reported a bug.<\/p><p>But, instead of something working incorrectly, this was a use case I hadn't considered.<\/p><p>The tests were passing, but there wasn't one for this.<\/p><p>I wrote the code for the use cases I was aware of when I started, and now I'm aware of another, I can add a test for it and ensure it's tested and working.<\/p><p>To do test-driven development, you don't need to know all the use cases and functionality upfront.<\/p><p>Write for what you know at the time, then expand and iterate in the future.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Violinist and automation with Eirik Morland",
"date": "1706486400",
"permalink": "/daily/2024/01/29/violinist-and-automation-with-eirik-morland",
"text": "<p>In <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/8-eirik-morland-violinist\">today's episode of the Beyond Blocks podcast<\/a>, I'm joined by Eirik Morland - the Developer of <a href=\"https:\/\/violinist.io\">Violinist<\/a>.<\/p><p>We discuss why you'd want to use a tool like Violinist to manage your dependency updates, why you'd want to automate repetitive tasks and focus on providing value for clients and customers.<\/p><p>We also discuss running a SaaS business and why Drupal is a good choice for SaaS products - though this could be a full episode on its own.<\/p>",
"cta": "",
"tags": ["software-development","podcast","php","phpc","composer"]
}, {
"title": "Ignoring things globally",
"date": "1706400000",
"permalink": "/daily/2024/01/28/ignoring-things-globally",
"text": "<p>Yesterday's email was about repository-specific .gitignore files and different ways to write them.<\/p><p>But there's a setting that most people don't know about, where you can configure a global <code>.gitignore<\/code> file.<\/p><h2 id=\"what-i-use-it-for\">What I use it for<\/h2><p>Whilst it doesn't replace repository-specific files, it's good for operating system-specific files - such as <code>.DS_Store<\/code> files on macOS.<\/p><p>I have a convention where I have a <code>.ignored<\/code> directory in a project, and everything in it should be ignored by Git.<\/p><p>Instead of adding this to every <code>.gitignore<\/code> file, and because it's specific to me, it's a good choice for a global ignore file.<\/p><p>Anything that affects multiple users - such as ignoring <code>vendor<\/code> or <code>node_modules<\/code> should still be set in each repository.<\/p><h2 id=\"how-do-you-add-it%3F\">How do you add it?<\/h2><p>Add this to your <code>~\/.gitconfig<\/code> or <code>~\/.config\/git\/config<\/code> file to set the path for your global ignore file:<\/p><pre><code class=\"language-plain\">[core] excludesFile = \"~\/.config\/git\/ignore\"<\/code><\/pre><p>Then, create the file and add what you want to ignore everywhere.<\/p><p>Just remember this is specific to you, and if others have something you've ignored globally and they haven't, they could still add and commit it.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "gitignore - inclusive or exclusive?",
"date": "1706313600",
"permalink": "/daily/2024/01/27/gitignore-inclusive-or-exclusive",
"text": "<p>Add everything and ignore what you don't want, or ignore everything and explicitly add what you need.<\/p><p>There are two ways to structure a .gitignore file.<\/p><p>The default approach is that all files can be added, and you specify the files and directories you want to ignore.<\/p><p>For example, if my <code>.gitignore<\/code> file was this, these two directories would be ignored:<\/p><pre><code class=\"language-plain\">vendorweb<\/code><\/pre><p>The other approach is to ignore everything and unignore the things to add. For example:<\/p><pre><code class=\"language-plain\">*!build.yaml!Dockerfile!docker-compose.yaml!web\/*\/custom<\/code><\/pre><p>Both approaches work and are regularly used.<\/p><p>Which approach do you prefer and why?<\/p><p>Reply and let me know.<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Write once, manage forever",
"date": "1706227200",
"permalink": "/daily/2024/01/26/write-once-manage-forever",
"text": "<p>I built my <a href=\"https:\/\/www.oliverdavies.uk\/build-config\">Build Configs<\/a> tool because I only wanted to write a file once and re-use it instead of writing it over again or copying and pasting between projects.<\/p><p>Having standardised templates for different languages and project types, I can easily set up new projects and get them running in a few minutes.<\/p><p>If I need to add a feature or fix a bug, I can do it once in the Build Configs tool and easily regenerate the configuration files for all projects, and they'll all get the updated files.<\/p><p>There's no \"I need to copy this feature from project A or this bug fix from project B.\" when starting on project C.<\/p><p>As I only work on fixed-price engagements, it's in my interest to be able to create and maintain projects in a fast and efficient manner.<\/p><p>The Build Configs tool enables me to do that.<\/p>",
"cta": "",
"tags": ["software-development","automation"]
}, {
"title": "Speaking at PHP Oxford",
"date": "1706140800",
"permalink": "/daily/2024/01/25/speaking-at-php-oxford",
"text": "<p>I attended the relaunched PHP Oxford user group meetup this evening, organised by Humand Talent.<\/p><p>I gave the short version of my talk on the <a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">Build Configs<\/a> tool I've built and used to manage multiple projects' configuration files.<\/p><p>As it was a shorter talk, I didn't show the internals slides I did remotely for PHP Muninch on Tuesday evening.<\/p><p>However, if anyone wants to see the full slides that show some of the Build Configs code, <a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-build-configs\">they are online<\/a>.<\/p><p>As well as the Drupal, Fractal, Drupal Commerce Kickstart and Drupal LocalGov examples on GitHub, I created Symfony and Laravel examples that are still unreleased in private repositories. I plan on reviewing those, making them public soon and continuing to iterate on and improve the Build Configs tool itself - making it more valuable to me and my customers and clients.<\/p>",
"cta": "",
"tags": ["php","phpc","symfony"]
}, {
"title": "Defining Ubiquitous language",
"date": "1706054400",
"permalink": "/daily/2024/01/24/defining-ubiquitous-language",
"text": "<p>A key takeaway from Rob Allen's Domain-Driven Design talk was defining ubiquitous language and avoiding the phrase \"That's not what I meant\".<\/p><p>Even a simple table or glossary that lists business and domain-specific terms and their agreed meaning is very helpful to ensure everyone in the discussion is on the same page and means the same thing.<\/p><p>Rob's example was using the words \"policy\" and \"risk\" when dealing with insurance clients.<\/p><p>A common issue I've seen is where people are referred to as customers by the business and users within the software.<\/p><p>Ideally, these should be consistent, and the code should match the business terminology.<\/p><p>This can be complicated further by different areas of the business, such as a marketing team that may refer to people as subscribers.<\/p><p>Without the ubiquitous language being defined, the requirements are more likely to be misunderstood and the wrong solution delivered, resulting in \"that's not what I meant.\".<\/p><p>This then means the work needs to be re-done and delayed, which can be expensive and time-consuming.<\/p><p>Another approach is to work in small batches, which is something I've written about before, and getting feedback from customers as early and often as possible so, if there is a misunderstanding, the minimum amount of time has been spent before it's realised and rectified.<\/p><p>Rob, of course, covered a lot more about DDD in his talk, and I'm looking forward to re-watching it once the video from the meetup is released.<\/p>",
"cta": "",
"tags": ["software-development","php","domain-driven-design"]
}, {
"title": "Why use automation tools for dependency updates",
"date": "1705968000",
"permalink": "/daily/2024/01/23/why-use-automation-tools-for-dependency-updates",
"text": "<p>Last week, I recorded an episode of <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">Beyond Blocks<\/a> with Eirik Morland - the Developer of violinist.io, a tool for automating dependency updates in PHP projects.<\/p><p>Instead of a person manually running <code>composer update<\/code> in each project, tools like Violinist can do that for you and submit pull or merge requests to your project for you to review.<\/p><p>But why would you want this?<\/p><p>There are technical reasons, such as not having to rely on everyone having the same local environment and avoiding potential conflicts, and consistency by ensuring the same command is run every time.<\/p><p>But, the big advantage, in my opinion, is the time it saves and allows you to reuse.<\/p><p>Instead of manually updating each project's dependencies, I can focus on tasks that deliver value to my customers and clients and move us towards our objectives.<\/p><p>Dependency updates, such as a new version of Drupal core or a contrib module, don't contain any perceived value compared to other tasks, such as adding a new feature or fixing a bug.<\/p><p>They happen behind the scenes, often invisibly, without any visual changes to show an update has been done.<\/p><p>If they aren't done often, they will be riskier to deploy due to the larger changes, and the longer it takes, the greater the potential for insecure versions to be exploited - potentially affecting your reputation and your customer's and with any remedial work taking the focus from other tasks.<\/p><p>Having a service like Violinist performing the updates for you means they can be applied and deployed more regularly, reducing the risk and making it easier to stay up-to-date and run secure versions of your dependencies.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","composer"]
}, {
"title": "Tailwind CSS workshop recording",
"date": "1705881600",
"permalink": "/daily/2024/01/22/tailwind-css-workshop-recording",
"text": "<p>At Saturday's hackathon that I mentioned in yesterday's email, most of the squads decided to try Tailwind CSS in their applications.<\/p><p>I've been using Tailwind since it was released, and first gave <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">a Tailwind CSS talk<\/a> in January 2018.<\/p><p>It's one of my most popular talks and, during COVID lockdowns, I also gave a workshop\/webinar on Tailwind CSS for some online conferences.<\/p><p><a href=\"https:\/\/www.youtube.com\/watch?v=phFDKF-9j0Y\">Here's a recording<\/a> of the session I gave for DrupalCamp Florida, in which I cover some Tailwind CSS concepts and show how to install and customise Tailwind before rebuilding the Florida DrupalCamp website live.<\/p><p>If this helps anyone on their Tailwind CSS learning journey, please reply and let me know!<\/p>",
"cta": "",
"tags": []
}, {
"title": "Where is the value in your application?",
"date": "1705795200",
"permalink": "/daily/2024/01/21/where-is-the-value-in-your-application",
"text": "<p>Yesterday, I was in Birmingham for a hackathon event organised by the School of Code, who I've been a Bootcamp mentor for for the last few cohorts.<\/p><p>At the event, I was mentoring a team of three Bootcamp graduates to plan and build a Christmas-themed application.<\/p><p>We decided on a Christmas walking application where people can view upcoming walks, log in and book a place.<\/p><p>After designing some initial pages, such as the Home page with a login form, a registration form, a list of walks and a walk detail page, we started to code them.<\/p><p>Naturally, we started with the Home page, the login form and the login functionality.<\/p><p>But, is that the most valuable part of the application?<\/p><p>What differentiates it from other applications, such as the ones being built by other squads at the event?<\/p><p>In this case, it's the page showing the list of walks and, if you click one, the details about that walk.<\/p><p>The squad needed to give a presentation and demo of the application by the end of the day, so we needed to prioritise.<\/p><p>We refocused on the walk pages and built them before moving back to the other pages to complete the user journey so it could be shown.<\/p><p>Similarly, we didn't need a fully functional user login and registration system for the demo. We just needed to show the forms we'd built, demo the user journey and show how someone would find and register for an event.<\/p><p>When I'm building an application, I identify the most valuable part and focus on it rather than other unrelated functionality that could likely be done manually or another way until that functionality is available.<\/p><p>The beginning of the user journey isn't always the best first thing to start developing.<\/p><p>It was a great day, our squad won the prize for the event, and I look forward to attending more events and continuing to work with the School of Code.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "PHPUnit or Pest?",
"date": "1705708800",
"permalink": "/daily/2024/01/20/phpunit-or-pest",
"text": "<p>A recent discussion has started about which testing framework should be the default one used in Laravel.<\/p><p>PHPUnit or Pest.<\/p><p>I've used both, and I like both.<\/p><p>I'm more familiar with classes, object-orientated code and PHPUnit, but for people who are more familiar with JavaScript and the Jest testing framework, Pest may be the better option.<\/p><p>Its expectation API, where you can chain multiple assertions on the same expectation, is helpful, although I don't mind some repetition in PHPUnit tests.<\/p><p>Pest tests can become abstract, especially with some of their one-line example tests.<\/p><p>Whether you pick PHPUnit, Pest or another framework like Behat or Codeception, the main thing is you're taking the time to write automated tests for your code, which is valuable whichever testing tool you use.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","php"]
}, {
"title": "Tests can assert multiple things",
"date": "1705622400",
"permalink": "/daily/2024/01/19/tests-can-assert-multiple-things",
"text": "<p>Similar to \"a method should only have one return statement\", I've seen similar advice when working with tests: \"Tests should only have a single assertion\".<\/p><p>I don't think this is true, and in my experience, you need multiple assertions to have a thorough test.<\/p><p>And, whilst similar assertions add some duplication, they can make the intent clearer and give better error messages.<\/p><p>Instead, I focus on one test case per test.<\/p><p>If I'm testing the following:<\/p><ul><li>A blog page exists.<\/li><li>Only post nodes are visible.<\/li><li>Only published posts are visible,<\/li><li>Posts are returned in a specified order.<\/li><\/ul><p>These will be split into separate tests - making it easier to read and maintain the code and have faster execution times by running only the tests I want with the minimum amount of code in each - regardless of how many assertions are in each.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Is zero unlimited?",
"date": "1705536000",
"permalink": "/daily/2024/01/18/is-zero-unlimited",
"text": "<p>Something I've seen in code is the unclear use of zero when adding limits, such as loading items from a database.<\/p><p>In some instances, setting zero will return all items - essentially, an 'unlimited' value in disguise - rather than returning no results, which is what I'd expect.<\/p><p>I imagine the code looks something like this:<\/p><pre><code class=\"language-php\">if ($limit &gt; 0) { $query-&gt;range(0, $limit);}<\/code><\/pre><p>If <code>$limit<\/code> is greater than one, add it to the query.<\/p><p>For me, using <code>0<\/code> as the unlimited value doesn't seem like the best option.<\/p><p>I'd prefer to use a <code>null<\/code> value as the default and only add the limit if it's set - i.e. an integer or not null.<\/p><p>It means the value could be either an integer or null, but I think the intent of the code is more explicit.<\/p><p>This would make the code look like this:<\/p><pre><code class=\"language-php\">if (is_int($limit)) { $query-&gt;range(0, $limit);}<\/code><\/pre><p>Whilst this is clearer, it doesn't cover all use cases.<\/p><p>Presumably, the limit should only be a positive integer.<\/p><p>It wouldn't make sense to set a negative number as the limit or, as the unlimited value is <code>null<\/code>, setting it to zero.<\/p><p>This is the end code I'd likely write:<\/p><pre><code class=\"language-php\">if (is_int($limit)) { if ($limit &lt; 1) { throw new InvalidArgumentException('A limit must be a positive integer.'); } $query-&gt;range(0, $limit);}<\/code><\/pre><p>If the limit is not an integer, nothing happens.<\/p><p>It throws an Exception if the value is invalid - i.e. less than one.<\/p><p>The limit is applied if the limit is greater than or equal to one.<\/p><p>While it's more complex as there are more checks to perform and different types in use, I think this is clearer and easier for someone reading or implementing the code to understand what it does and use it correctly.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Please don&#039;t use short variable names",
"date": "1705449600",
"permalink": "/daily/2024/01/17/short-variable-names",
"text": "<p>When learning to code, one of the most confusing things was using short variable names in documentation and other people's code.<\/p><p>Things like <code>$k<\/code> and <code>$v<\/code> instead of <code>$key<\/code> and <code>$value<\/code> within loops, <code>$i<\/code> instead of <code>$index<\/code>, or <code>$e<\/code> when working with Exceptions.<\/p><p>I've also seen slightly better names, such as <code>$idx<\/code> for index or <code>$ctx<\/code> for context.<\/p><p>But what does this achieve?<\/p><p>Why not write the full variable name and clarify what it refers to?<\/p><p>It would be easier to read and understand for anyone reading the code, including Junior Developers and people new to your team or application.<\/p><p>There are no limitations - at least in the languages I use - to force this, such as a maximum number of characters in a file, so why not write the full variable name?<\/p><p>The only reason I can think of is to save time by pressing fewer keys, but code is read more than written, so it should be optimised for readability.<\/p><p>Your tests and CI pipeline don't have a preference.<\/p><p>The people reading the code will.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Daily or quarterly?",
"date": "1705363200",
"permalink": "/daily/2024/01/16/daily-or-quarterly",
"text": "<p>Imagine this scenario.<\/p><p>You have two options on how frequently you can deploy code changes to your application.<\/p><p>Option 1: Every day.<\/p><p>Option 2: Once a quarter.<\/p><p>No more, no less.<\/p><p>I'd choose daily.<\/p><p>I much prefer to deploy changes as often as possible rather than waiting.<\/p><p>I'm much more confident when releasing small changes - even if it's a small refactor, such as changing a variable name or extracting a small helper method.<\/p><p>It might even seem too small to release.<\/p><p>But the smaller the release is, the easier it is to find and fix any issues, and knowing that the next release would only be the following day makes it easier to fix forward instead of rolling back a large release with months of changes.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Whilst it may seem counterintuitive initially, it's much less risky to release small changes often compared to large changes infrequently.<\/p><p>Which option would you choose?<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Don&#039;t be perfect, be useful",
"date": "1705276800",
"permalink": "/daily/2024/01/15/don-t-be-perfect--be-useful",
"text": "<p>In a recent private coaching session with <a href=\"https:\/\/jonathanstark.com\">Jonathan Stark<\/a>, he said, \"Don't be perfect, be useful\".<\/p><p>He meant it relating to giving a presentation, like a talk or workshop, but I thought about how the same quote applies to some of the software development topics I cover in these emails.<\/p><p>You don't need a perfect test suite with 100% coverage. One test is better than no tests, and some tests are better than one.<\/p><p>You don't need to run static analysis on all your code at the highest level. If you run it on some of your code, maybe the newer code or the most crucial parts of your application, that's better than not running it at all, and it will catch many issues even at the lower levels.<\/p><p>You don't need to know and implement all the design patterns within your code. The objective is to deliver working software for your customers and clients. Do this first and refactor later when needed.<\/p><p>You don't need always to be pair or mob programming. Do it when it works for the people and situation.<\/p><p>These tools and techniques are useful.<\/p><p>They don't need to be perfect.<\/p>",
"cta": "",
"tags": ["software-development","design-patterns","automated-testing","test-driven-development","static-analysis","pair-programming","mob-programming"]
}, {
"title": "Code is a liability, not an asset",
"date": "1705190400",
"permalink": "/daily/2024/01/14/code-is-a-liability-not-an-asset",
"text": "<p>Something I mentioned during my <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/7-mike-karthauser-testing-legacy\">podcast episode with Mike Karthauser<\/a> is a quote I saw recently:<\/p><blockquote> <p>Code is a liability, not an asset.<\/p><\/blockquote><p>The more code you write, the more you have to maintain.<\/p><p>The more complex the code is, the harder it is to maintain.<\/p><p>For example, when adding a new page to a Drupal application, should you write a custom route, a Controller, and a Repository and write accompanying tests, or should you use the Views module?<\/p><p>Both can give the same result.<\/p><p>One involves writing and maintaining custom code; the other uses a no-code approach available in Drupal, which creates the page and output based on your selections.<\/p><p>There isn't a correct answer.<\/p><p>The option you choose will depend on what problem you're solving, what deadlines you're working to, and any precedents set within the project.<\/p><p>It also depends on whether you want to maintain the code you write over time, fix any bugs, refactor it, and upgrade it as part of major Drupal version upgrades.<\/p><p>Like a house, car or pet, any code you write will need ongoing care and maintenance in the future - not just now.<\/p>",
"cta": "",
"tags": ["software-development","drupal"]
}, {
"title": "Testing Legacy with Mike Karthauser",
"date": "1705104000",
"permalink": "/daily/2024/01/13/testing-legacy-with-mike-karthauser",
"text": "<p>Last week, Mike Karthauser - Senior Software Developer at Huboo - <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/7-mike-karthauser-testing-legacy\">joined me on the Beyond Blocks podcast<\/a>.<\/p><p>Mike also gave a talk recently at the PHP South West meetup on \"Testing Legacy\" which explained how he works with and tests legacy applications.<\/p><p>In the episode, we discuss e-commerce, legacy code, technical debt, automated testing, test-driven development, refactoring, code vs. no-code solutions.<\/p>",
"cta": "",
"tags": ["software-development","podcast","beyond-blocks","automated-testing","refactoring"]
}, {
"title": "Utility classes make global scope local",
"date": "1705017600",
"permalink": "/daily/2024/01/12/utility-classes-make-global-scope-local",
"text": "<p>In my <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2024\/01\/09\/using-tailwind-css-is-a-great-way-to-learn-css\">recent pair programming session<\/a>, building components with Tailwind CSS, we experienced another benefit of styling with utility classes.<\/p><p>CSS usually has a global scope, but utility classes change it to a local scope.<\/p><p>For example, having a card component with a <code>card<\/code> class on it, any changes to the styles will affect all instances of any card component that uses the <code>card<\/code> class.<\/p><p>How do you know you haven't broken something in a different component without re-checking every component manually?<\/p><p>How do you easily modify or extend it as requirements change or add more card types?<\/p><p>If you need to make a change in the future, you're likely to add more styles and modifiers and add to the CSS, causing it to grow rather than change the existing styles - in fear of breaking something else.<\/p><p>With utility classes, such as the ones generated by Tailwind CSS, you can see and understand what styles are applied to the HTML.<\/p><p>This also makes it easier to change, and because the classes and styles are added directly to that element, you don't need to worry about breakages elsewhere.<\/p><p>If you need to add a new class to that card type, you can do so knowing that it won't affect all card styles globally in your application - just the one you're working on.<\/p><p>This means you can change things more easily in the future but also work quicker now as you don't need to worry about all that additional context.<\/p><p>You can focus on what you're working on right now.<\/p>",
"cta": "",
"tags": ["software-development","css","tailwind-css"]
}, {
"title": "My Drupal testing email course is live",
"date": "1704931200",
"permalink": "/daily/2024/01/11/my-drupal-testing-email-course-is-live",
"text": "<p>Do you want to learn automated testing in Drupal?<\/p><p>My free email course is live!<\/p><p>Learn how to write tests in Drupal from a DrupalCon speaker, workshop trainer, and module maintainer (me!).<\/p><p>Register for the course and get a lesson each day where you build a module from scratch with automated tests and test-driven development based on my previous talks and workshops.<\/p><p>All emails are sent from my personal email address, so if you have questions or issues, you can press reply and let me know. I'll be happy to help!<\/p><p>Happy testing!<\/p>",
"cta": "",
"tags": ["softare-development","drupal","php","phpc","automated-testing","test-driven-development"]
}, {
"title": "Don&#039;t put business logic in templates",
"date": "1704844800",
"permalink": "/daily/2024/01/10/dont-put-business-logic-in-templates",
"text": "<p>Here is some code from my website:<\/p><p><img src=\"https:\/\/www.oliverdavies.uk\/assets\/images\/talk-count-code.png\" alt=\"A screenshot of the code that calculates the number of talks I've given.\" \/><\/p><p>If you want, you can also <a href=\"https:\/\/raw.githubusercontent.com\/opdavies\/oliverdavies.uk\/main\/source\/_pages\/talks.md\">view it on GitHub<\/a>.<\/p><p>It is business logic responsible for counting the number of talks I've given at different events so I can display it on my Talks page.<\/p><p>It starts at zero, loops over each talk, and increments the talk count if the event is the current day or a past date.<\/p><p>It's only used in a single place, so the same logic isn't duplicated elsewhere.<\/p><p>But it's in the page's Twig template.<\/p><p>It has no test coverage.<\/p><p>If I need to change or refactor it, I'd need to test it again manually.<\/p><p>Don't do this.<\/p><h2 id=\"so%2C-what-should-i-do%3F\">So, what should I do?<\/h2><p>It's OK to put simple presentational logic, such as looping over a list or whether to show or hide a value within a template, but not complex business logic.<\/p><p>Business logic should be separated and executed elsewhere. The values should be passed to the template to be rendered.<\/p><p>This makes the business logic easier to test as you can test the logic itself and determine the value passed to the template is correct without being concerned about the templating engine.<\/p><p>In an application, you may need to output a value to a template and a terminal. You'd have one source of truth, such as a Service, Action or Command class that calculates the value before passing it to the appropriate output.<\/p><p>Once the logic is separated, you only need to test it once.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>In a previous version of my website, I did this by creating a custom Twig function.<\/p><p>It was as simple as adding <code><\/code> to the template.<\/p><p>All the logic was moved from the template to my custom extension.<\/p><p>The logic was separated.<\/p><p>It had tests.<\/p><p>This is the approach I'd take to achieve the same result for a client application.<\/p><p>For a client, I want to run a test suite and be confident my logic works as expected - now and in the future.<\/p><p>For myself, and for calculating something simple, this is fine.<\/p>",
"cta": "",
"tags": ["software-development","clean-code","twig","automated-testing"]
}, {
"title": "Using Tailwind CSS is a great way to learn CSS",
"date": "1704758400",
"permalink": "/daily/2024/01/09/using-tailwind-css-is-a-great-way-to-learn-css",
"text": "<p>I was in a pair programming session today, working on some Twig components with Tailwind CSS.<\/p><p>We knew what we needed to implement and did so based on an example from a Tailwind component library and some additional styles.<\/p><p>After implementing the feature, we could review the classes we added and review what each did.<\/p><p>We could easily move or remove a class and see what effect it had.<\/p><p>Something nice is that the Tailwind classes usually relate to what CSS they're applying, such as <code>block<\/code> and <code>flex<\/code> for <code>display<\/code> and <code>relative<\/code> and <code>absolute<\/code> for positioning.<\/p><p>This makes Tailwind a great way to learn CSS compared to other frameworks that give you prebuilt HTML and expect you to add a generic class like <code>card<\/code>.<\/p><p>In that case, the knowledge is hidden within a stylesheet the Developer doesn't see, which makes it harder to read and learn from.<\/p><p>Other utility-class frameworks have shorter class names that are less readable.<\/p><p>Tailwind strikes the perfect balance, in my opinion.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Try it and see",
"date": "1704672000",
"permalink": "/daily/2024/01/08/try-it-and-see",
"text": "<p>I recently saw a post with a screenshot of some code they'd written using Tailwind CSS.<\/p><p>Reading the comments, it had the usual \"re-inventing the wheel\" and \"just use inline styles\" comments, which, to me, didn't seem very helpful and not the point of the post.<\/p><p>When I've given a <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">talk on Tailwind CSS<\/a>, I've acknowledged that people have common initial reactions and suggested people try it for a week or so and see how it works for them before making up their minds.<\/p><p>Someone did after a conference and posted this on Twitter:<\/p><blockquote> <p>I saw a talk on tailwind at a conference. Spent 15 minutes afterwards \"discussing\" with the presenter how it was horrible and against the neat way of CSS and so on. But promised to try it just once as he said it feels better than it looks.<\/p> <p>He was right. It's so freeing.<\/p><\/blockquote><p>The same approach applies to many other things, such as pair programming, automated testing, test-driven development, static analysis, Scrum, Linux and Vim - to name a few.<\/p><p>If you use it and don't like it, don't continue and return to what you did before.<\/p><p>Whether you keep it or not, you better understand what you're evaluating and not dismiss it out of hand.<\/p>",
"cta": "",
"tags": ["tailwind-css","automated-testing","test-driven-development"]
}, {
"title": "Things take as long as they take",
"date": "1704585600",
"permalink": "/daily/2024/01/07/things-take-as-long-as-they-take",
"text": "<p>Today, I saw a post that asked the question:<\/p><blockquote> <p>Have you ever spent three days on an issue that should have taken 2 hours?<\/p><\/blockquote><p>My thought was, \"Who said it should have taken two hours?\".<\/p><p>In my experience, tasks take as long as they take.<\/p><p>Even something that seems simple can end up being something complex.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Sculpin - the PHP static site generator",
"date": "1704499200",
"permalink": "/daily/2024/01/06/sculpin-the-php-static-site-generator",
"text": "<p>If you use PHP and need to make a static website, <a href=\"https:\/\/sculpin.io\">Sculpin<\/a> is a great choice!<\/p><h2 id=\"what-is-it%3F\">What is it?<\/h2><p>Built with PHP and using Symfony components, it converts Markdown files and Twig templates into static HTML that can be easily deployed and hosted.<\/p><p>Once generated, you can upload the files to a web host of your choice as the generated files are simple HTML, such as an S3 bucket with static hosting or GitHub Pages.<\/p><h2 id=\"why-do-i-use-it%3F\">Why do I use it?<\/h2><p>As a PHP Developer, it's already familiar and I can immediately start instead of learning a new language or templating engine, which I'd need to do if I were to use a static site generator written in Ruby, JavaScript or Go.<\/p><p>If I need to extend it, I already can.<\/p><p>I already know how to write custom Twig extensions, for example, so I can do it in Sculpin in the same way. (<a href=\"https:\/\/github.com\/opdavies\/sculpin-twig-markdown-bundle\">I made one<\/a> and open-sourced it)<\/p><p>I already know how to use PHPUnit to write tests.<\/p><h2 id=\"what-do-i-use-it-for%3F\">What do I use it for?<\/h2><p>I use Sculpin for <a href=\"https:\/\/github.com\/opdavies\/oliverdavies.uk\">this website<\/a> and client projects that don't need the features of a CMS or framework with the ability to have reusable components and functionality provided by Twig (this works great with Tailwind CSS, too).<\/p><p>I used it to <a href=\"https:\/\/www.oliverdavies.uk\/test-drive-twig-with-sculpin\">learn Twig before Drupal 8 was released<\/a>, back in 2015.<\/p><p>I've also given a talk on <a href=\"https:\/\/www.oliverdavies.uk\/building-static-websites-sculpin\">building websites with Sculpin<\/a> which I may submit to some upcoming conferences.<\/p>",
"cta": "",
"tags": []
}, {
"title": "PHP in Neovim",
"date": "1704412800",
"permalink": "/daily/2024/01/05/php-in-neovim",
"text": "<p>Yesterday, I posted a screenshot from my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">automated testing in Drupal email course<\/a> on Twitter as a sneak peek of what's included.<\/p><p>Here it is again:<\/p><p><img src=\"https:\/\/www.oliverdavies.uk\/assets\/images\/php-neovim-1.png\" alt=\"Screenshot of a lesson from my automated testing email course\" \/><\/p><p>I also posted a screenshot of the accompanying code in my text editor, Neovim, which had a few likes.<\/p><p><img src=\"https:\/\/www.oliverdavies.uk\/assets\/images\/php-neovim-2.png\" alt=\"Screenshot of Drupal code in Neovim\" \/><\/p><p>Since July 2021, I've used Neovim as my daily driver for writing all my code, which I spoke about during my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/working-without-workspace\">Working without Workspace talk<\/a>.<\/p><p>You can also see my NixOS-based <a href=\"https:\/\/github.com\/opdavies\/dotfiles\">dotfiles on GitHub<\/a> which contains my Neovim configuration.<\/p><p>Register now to find out when the email course is live, or <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/25\/zero-to-test\">read the first lesson<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","php","vim","neovim"]
}, {
"title": "Reuse what you can.",
"date": "1704326400",
"permalink": "/daily/2024/01/04/reuse-what-you-can",
"text": "<p>A lot is different between Drupal 7 and 10, with the introduction of Composer, object-orientated code, Symfony components and other third-party libraries, to name a few things.<\/p><p>But, when upgrading a project, the business logic may not need to change.<\/p><p>How it integrates with the new version of Drupal may change - it may use a different module, such as Paragraphs instead of Field Collection, or be within a Controller or Service class instead of a Drupal \"hook\", but if the majority of the logic can remain the same, it might as well be reused instead of written from scratch.<\/p><p>Presumably, it works as it does in Drupal 7, which may not be the case after it's been rewritten, as bugs and issues may have been introduced.<\/p><p>This is the approach I took when migrating the Override Node Options module to Drupal 8. I picked a test, migrated it from SimpleTest (Drupal 7) to PHPUnit (Drupal 8), ported enough code to make it pass, and moved to the next test.<\/p><p>Most custom applications, though, tend to be rewritten and the old business logic discarded.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>If it works, why rewrite it?<\/p><p>Migrate what you can and only rewrite what you need.<\/p><p>As someone who works on fixed-price projects and includes a bug-free guarantee, it's in my interests to deliver working and stable software as soon as possible, which is also in my client's interests as they get their new software sooner and not from a drawn-out process where everything is re-done from scratch.<\/p>",
"cta": "",
"tags": ["drupal","drupal7","drupal10","drupal-upgrade"]
}, {
"title": "Why you need to start upgrading from Drupal 7 now",
"date": "1704240000",
"permalink": "/daily/2024/01/03/why-you-need-to-start-upgrading-from-drupal-7-now",
"text": "<p>There's only one year before support for Drupal 7 support ends, but there are still more than 337,000 Drupal 7 websites, according to <a href=\"https:\/\/www.drupal.org\/project\/usage\/drupal\">https:\/\/www.drupal.org\/project\/usage\/drupal<\/a>.<\/p><p>Even though there's a year left, if you've got a Drupal 7 website, you need to start upgrading now!<\/p><p>Unlike upgrading from Drupal 8 to 9 or 9 to 10, upgrading from Drupal 7 requires major changes to your code for it to be compatible. This will take time to do and test.<\/p><p>Most websites have some or many custom modules and at least one custom theme that must be upgraded.<\/p><p>Most use a large number of community-contributed modules.<\/p><p>Many of these are abandoned or minimally maintained as their maintainers have focused on newer Drupal versions or a module has been marked as unsupported in favour of another.<\/p><p>If they do have supported versions, it is likely that they haven't had a release for some time. If that's the case, they're essentially unsupported.<\/p><p>Because of this, there may not be the same modules available with the same functionality for Drupal 10.<\/p><p>Depending on the available modules, your functionality may need to change, or the old functionality will need to be written within a new custom module.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Depending on the complexity, it will take a number of months to complete an upgrade.<\/p><p>Rather than wait until 2025, you want to do the work now whilst Drupal 7 is still supported rather than waiting and being vulnerable to security exploits if running an outdated and unsupported version.<\/p>",
"cta": "",
"tags": ["drupal","drupal-upgrade","drupal7","php","phpc"]
}, {
"title": "Flexible Mob and Pair Programming",
"date": "1704153600",
"permalink": "/daily/2024/01/02/flexible-pair-programming",
"text": "<p>Doing pair or programming doesn't mean you need to be working in groups continuously.<\/p><p>If you've asked a colleague to review the code you're writing or help you fix a bug, that's pair programming.<\/p><p>You don't always need a driver and navigator, a set rotation time or dedicated allocated daily pair programming time.<\/p><p>While that works for some teams, and on some occasions, you can do what's needed or feels right at the time to complete the task at hand.<\/p><p>If you need a short pair programming session to fix a bug or finish a feature, to review some code before you merge it or submit it for code review, or want to pair ad-hoc or for one afternoon a week, that works, too.<\/p><p>There isn't one way to do pair or mob programming.<\/p><p>Do what works for you.<\/p>",
"cta": "",
"tags": ["software-development","pair-programming"]
}, {
"title": "Continuous improvement",
"date": "1704067200",
"permalink": "/daily/2024/01/01/continuous-improvement",
"text": "<p>I've written emails before about continuous delivery and continuous deployment, but there's another \"continuous\" I like to follow.<\/p><p>Continuous <strong>improvement<\/strong>.<\/p><p>Always focusing on improving, whether learning new things or getting better with things I already know.<\/p><p>If you haven't written automated tests or done test-driven development before, try it.<\/p><p>Try using static analysis tools if you haven't before.<\/p><p>If your tools or approaches are outdated, try something more modern.<\/p><p>Can you reduce the time your CI pipeline takes to run, or write better documentation?<\/p><p>You may not like everything you try, but what works will pay dividends over time.<\/p>",
"cta": "",
"tags": ["software-development","agile","continuous-improvement"]
}, {
"title": "Just...",
"date": "1703980800",
"permalink": "/archive/2023/12/31/just",
"text": "<p>If you have a request that starts with \"Just\", it's likely a red flag!<\/p><p>Why is it being made?<\/p><p>What problem is it going to solve?<\/p><p>Whose problem does it solve?<\/p><p>Is the problem time-sensitive?<\/p><p>What value does it add?<\/p><p>Is it the best solution to fix the problem?<\/p><p>Is it the best solution to fix the problem right now?<\/p><p>To know this, we need to know why it's needed and it \"just\" needs doing.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "We&#039;ve always done it this way",
"date": "1703894400",
"permalink": "/archive/2023/12/30/weve-always-done-it-this-way",
"text": "<p>Two of the worst phrases I've heard when working with new development teams is \"We've always done it this way\" or \"We've never needed to do this before\".<\/p><p>Whether it's writing automated tests, using static analysis, having a CI pipeline or using a specific framework or tool, this mindset prevents experimentation, growth and improvement.<\/p><p>Instead, try to think about what benefits alternative approaches could offer and how they could improve any situations you're currently experiencing.<\/p><p>You don't need to do it forever. Decide on something you want to try on a trial basis and set an end date.<\/p><p>Then, when the trial is finished, you can decide if it achieved what you wanted, and if you want to continue with it.<\/p><p>Even if you don't continue with it, you still learned something by trying.<\/p>",
"cta": "",
"tags": ["software-development","agile","continuous-improvement"]
}, {
"title": "Decide, automate, document",
"date": "1703808000",
"permalink": "/archive/2023/12/29/decide-automate-document",
"text": "<p>Decide, automate, document<\/p><p>Here are three steps to making decisions, such as introducing new tools and processes:<\/p><p>Decide.<\/p><p>Automate.<\/p><p>Document.<\/p><p>First of all, a decision needs to be made about what you will introduce.<\/p><p>It could be whether to write automated tests, use static analysis, choose which coding standard to use, or make architecture decisions about how you want to build your application.<\/p><p>Once you've decided and added the tool or process, automate it if you can.<\/p><p>A CI pipeline or Git Hooks can run tests and checks automatically to know if the code complies with what was agreed upon rather than relying on this being done manually.<\/p><p>Finally, document it so that it's available for others to read and reference, including new team members.<\/p><p>Ensure to document why this was added, what problem it solves, any alternatives that were considered and any side effects or consequences. Technical design documents and ADRs (architectural decision records) are great for this!<\/p><p>In the future, you may want to revisit the decision and decide if it's still correct, and you'll appreciate having the information documented.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Don&#039;t let pride get in the way of productivity",
"date": "1703721600",
"permalink": "/archive/2023/12/28/pride-and-productivity",
"text": "<p>Today, I was reading a support request on a public forum.<\/p><p>The poster asked a question about a technical issue and explained the problem they were experiencing. I was experiencing the same thing, which is how I found it.<\/p><p>A community member responded and suggested a solution.<\/p><p>To this, the original poster responded:<\/p><blockquote> <p>Not too proud to ask where I [make the change].<\/p><\/blockquote><p>The response to this was what caught my attention:<\/p><blockquote> <p>No problem. Don't let pride get in the way of productivity.<\/p><\/blockquote><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Don't be afraid to ask questions or say you don't know or understand something.<\/p><p>No one knows everything, and there's no such thing as a stupid question.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Writing new code is quick, to begin with",
"date": "1703635200",
"permalink": "/archive/2023/12/27/writing-new-code-is-quick-to-begin-with",
"text": "<p>When you first start a new application, adding new features is quick and easy.<\/p><p>There's no existing code, and everything is written from scratch.<\/p><p>As the project progresses, you need to account for and, in some cases, work around the existing code - ensuring the existing functionality continues to work.<\/p><p>Even if a sole Developer is working on the project, inconsistencies start to be introduced.<\/p><p>One feature was implemented in one way and the next in a different way.<\/p><p>One follows a particular design pattern, and the other does not.<\/p><p>There is code within the application that isn't used and is no longer needed but hasn't been removed - creating confusion and uncertainty.<\/p><p>It can't be removed, just in case it does something and removing it breaks something elsewhere.<\/p><p>A task that would have taken hours to complete when the application started now takes days, weeks or longer.<\/p><p>Having automated tests, using tools like static analysis, and minimising technical debt helps to minimise this, as does having written technical design documents, ADRs or flow charts to ensure consistency and to document the \"why\" for future Developers.<\/p><p>P.S. Is your New Year's resolution to deliver better software faster? <a href=\"https:\/\/www.oliverdavies.uk\/team-coaching\">I have availability for team coaching<\/a> starting in January 2024 and can help you avoid issues like this in your applications.<\/p>",
"cta": "",
"tags": ["software-development","technical-debt","clean-code"]
}, {
"title": "Good code is not about being easy to write",
"date": "1703548800",
"permalink": "/archive/2023/12/26/good-code-is-not-about-being-easy-to-write",
"text": "<p>Good code is not about being easy to write. It's about how easy it is to change.<\/p><p>Once you've written some code, how easily and confidently could you change it in the future, either adding new features or fixing a bug?<\/p><p>How easily could you refactor the code or remove it altogether if it's no longer needed?<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "A sneak peek of my Drupal automated testing course",
"date": "1703462400",
"permalink": "/archive/2023/12/25/zero-to-test",
"text": "<p>Happy Christmas!<\/p><p>Here's my present - a sneak peek at the first lesson in my free upcoming Automated Testing for Drupal email course.<\/p><p>In this lesson, we start from scratch and end with a working test suite.<\/p><p>If you like it, <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">register for free and get the full course<\/a> when it launches.<\/p><h2 id=\"creating-a-drupal-project\">Creating a Drupal project<\/h2><p>If you don't have one, you'll need to create a new Drupal project. I'd suggest using Drupal 10.2 and the instructions at <a href=\"https:\/\/www.drupal.org\/download\">https:\/\/www.drupal.org\/download<\/a>.<\/p><p>You'll need <a href=\"https:\/\/www.php.net\/manual\/en\/install.php\">PHP<\/a> and <a href=\"https:\/\/getcomposer.org\/doc\/00-intro.md\">Composer<\/a>.<\/p><p>First, run <code>composer create-project drupal\/recommended-project drupal<\/code> followed by <code>cd drupal &amp;&amp; composer require --dev drupal\/core-dev<\/code> to add the development dependencies, including PHPUnit.<\/p><p>At this point, you should have a <code>web<\/code> directory and a <code>phpunit<\/code> file within <code>vendor\/bin<\/code>.<\/p><p>Finally, run <code>php -S 0.0.0.0:8000 -t web<\/code> to start a local web server.<\/p><p>You don't need to install Drupal - as long as you see the installation page, that's fine.<\/p><h2 id=\"creating-a-custom-module\">Creating a custom module<\/h2><p>Before adding tests, you must create a module to place them in.<\/p><p>Run <code>mkdir -p web\/modules\/custom\/atdc<\/code> to create an empty module directory, and create an <code>atdc.info.yml<\/code> file within it with this content:<\/p><pre><code class=\"language-yaml\">name: Exampletype: modulecore_version_requirement: ^10package: Custom<\/code><\/pre><p>This is the minimum content needed for a module to be installable.<\/p><h3 id=\"writing-your-first-test-class\">Writing your first test class<\/h3><p>Test classes are placed within each module's <code>tests\/src<\/code> directory.<\/p><p>Run <code>mkdir -p web\/modules\/custom\/atdc\/tests\/src\/Functional &amp;&amp; touch web\/modules\/custom\/atdc\/tests\/src\/Functional\/ExampleTest.php<\/code> to create the directory structure and a blank test class.<\/p><p>Then, add this content.<\/p><pre><code class=\"language-php\">&lt;?phpnamespace Drupal\\Tests\\atdc\\Functional;use Drupal\\Tests\\BrowserTestBase;use Symfony\\Component\\HttpFoundation\\Response;class ExampleTest extends BrowserTestBase {\u00a0 public $defaultTheme = 'stark';}<\/code><\/pre><p>Note: within a test class, the namespace is <code>Drupal\\Tests\\{module_name}<\/code> instead of <code>Drupal\\{module_name}<\/code>.<\/p><p>With the boilerplate class added, create a test method within it:<\/p><pre><code class=\"language-php\">public function testBasic(): void {\u00a0 self::assertTrue(FALSE);}<\/code><\/pre><p>Note: the class name must be suffixed with <code>Test<\/code>, and the test method must be prefixed with <code>test<\/code> for them to be run.<\/p><p>Now we have a test with an assertion, we need to run it and see if it passes.<\/p><h2 id=\"running-the-test\">Running the test<\/h2><p>On the command line, run <code>vendor\/bin\/phpunit web\/modules\/custom<\/code>, and you'll get an error like:<\/p><blockquote> <p>PHPUnit\\TextUI\\RuntimeException: Class \"Drupal\\Tests\\BrowserTestBase\" not found.<\/p><\/blockquote><p>This isn't an assertion failure, but that PHPUnit can't find the files it needs to run.<\/p><p>To fix this, let's configure PHPUnit.<\/p><h2 id=\"configuring-phpunit\">Configuring PHPUnit<\/h2><p>Create a new <code>phpunit.xml.dist<\/code> file at the root of your project, with this content:<\/p><pre><code class=\"xml\">&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;&lt;phpunit bootstrap=\"web\/core\/tests\/bootstrap.php\" colors=\"true\"&gt; &lt;php&gt; &lt;env name=\"SIMPLETEST_BASE_URL\" value=\"http:\/\/localhost:8000\"\/&gt; &lt;env name=\"SIMPLETEST_DB\" value=\"sqlite:\/\/localhost\/\/dev\/shm\/test.sqlite\"\/&gt; &lt;ini name=\"error_reporting\" value=\"32767\"\/&gt; &lt;ini name=\"memory_limit\" value=\"-1\"\/&gt; &lt;\/php&gt; &lt;testsuites&gt; &lt;testsuite name=\"Example tests\"&gt; &lt;directory suffix=\"Test.php\"&gt;.\/web\/modules\/**&lt;\/directory&gt; &lt;\/testsuite&gt; &lt;\/testsuites&gt;&lt;\/phpunit&gt;<\/code><\/pre><p>This is based on <code>web\/core\/phpunit.xml.dist<\/code> with some project-specific changes.<\/p><p>Namely, setting the <code>bootstrap<\/code> value to include the <code>web\/core<\/code> path and fix the error, and populating the <code>SIMPLETEST_BASE_URL<\/code> and <code>SIMPLETEST_DB<\/code> environment variables.<\/p><p>PHPUnit now knows where the files are, to connect to Drupal at <a href=\"http:\/\/localhost:8000\">http:\/\/localhost:8000<\/a> (matching the PHP web server address) and an SQLite database.<\/p><p>I've also added a <code>testsuite<\/code> that declares where any test classes will be located so the path doesn't need to be specified on the command line.<\/p><h2 id=\"re-running-the-tests\">Re-running the tests<\/h2><p>Running the tests again will give the expected error about a failing assertion:<\/p><blockquote> <p>Failed asserting that false is true.<\/p><\/blockquote><p>Fix the assertion in the test by changing <code>FALSE<\/code> to <code>TRUE<\/code>, run <code>vendor\/bin\/phpunit<\/code> again, and you should see a passing test.<\/p><blockquote> <p>OK (1 test, 2 assertions)<\/p><\/blockquote><h2 id=\"improving-the-tests\">Improving the tests<\/h2><p>Now you have as passing test and know PHPUnit is working, let's improve it.<\/p><p>Instead of the basic check, let's check whether certain pages exist and are accessible.<\/p><p>To keep things simple and focused on writing and running tests, let's use some standard Drupal pages - the front and administration pages instead of writing your own.<\/p><p>As you're writing functional tests by extending <code>BrowserTestBase<\/code>, you can make HTTP requests to the web server, and make assertions on the responses.<\/p><p>Replace the <code>testBasic<\/code> test method with the following:<\/p><pre><code class=\"language-php\">public function testFrontPage(): void { $this-&gt;drupalGet('\/'); $assert = $this-&gt;assertSession(); $assert-&gt;statusCodeEquals(Response::HTTP_FORBIDDEN);}public function testAdminPage(): void { $this-&gt;drupalGet('\/admin'); $assert = $this-&gt;assertSession(); $assert-&gt;statusCodeEquals(Response::HTTP_OK);}<\/code><\/pre><p>These tests will make HTTP requests to the specified paths and assert the status code on the response matches the expected values.<\/p><p>I'm using the constants on the <code>Response<\/code> class, but you can also use the status code numbers - e.g. <code>200<\/code> and <code>403<\/code>.<\/p><h2 id=\"running-the-updated-tests\">Running the updated tests<\/h2><p>Running <code>vendor\/bin\/phpunit<\/code>, you'll get two errors:<\/p><blockquote> <p>1) Drupal\\Tests\\atdc\\Functional\\ExampleTest::testFrontPage Behat\\Mink\\Exception\\ExpectationException: Current response status code is 200, but 403 expected.<\/p> <p>2) Drupal\\Tests\\atdc\\Functional\\ExampleTest::testAdminPage Behat\\Mink\\Exception\\ExpectationException: Current response status code is 403, but 200 expected.<\/p> <p>ERRORS!<br \/> Tests: 2, Assertions: 4, Errors: 2.<\/p><\/blockquote><p>The responses are not returning the expected status codes, so the tests are failing.<\/p><p>Reviewing them, the front page should return a 200 response code (<code>HTTP_OK<\/code>) as it's accessible to all users, including anonymous users.<\/p><p>As we're logged out, the administration page should return a 403 (<code>HTTP_FORBIDDEN<\/code>).<\/p><p>Swapping the assertions should get the tests to pass.<\/p><p>Now, running <code>vendor\/bin\/phpunit<\/code> returns no errors or failures.<\/p><blockquote> <p>OK (2 tests, 4 assertions)<\/p><\/blockquote><p>Congratulations!<\/p><h2 id=\"conclusion\">Conclusion<\/h2><p>In this lesson, you've created a new Drupal 10 project, configured PHPUnit and created a custom module with your first passing browser tests.<\/p><p>From this, you can hopefully see that automated testing doesn't need to be difficult, and the configuration you've done here will work for the upcoming lessons, where you'll expand on what you've done and explore more that Drupal and PHPUnit have to offer.<\/p><p>I hope you enjoyed this sneak peek, and if you'd like to receive the course once it's complete, <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">register here for free<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","phpunit","automated-testing","test-driven-development"]
}, {
"title": "This should never happen",
"date": "1703376000",
"permalink": "/archive/2023/12/24/this-should-never-happen",
"text": "<p>How often do you see comments like \"This should never happen\" in a software codebase?<\/p><p>If that's true, why is it there?<\/p><p>If it truly should never happen, the additional code only adds more noise and distracts from the code that is run.<\/p><p>You can add a test that checks a method isn't called, but what value does this offer?<\/p><p>If it doesn't happen or some code isn't run, remove it and keep it as simple, clean and easy to understand as possible.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Using a whole framework or part of it",
"date": "1703289600",
"permalink": "/archive/2023/12/23/using-a-whole-framework-or-part-of-it",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/22\/best-language-cms-or-framework\">In yesterday's email<\/a>, I mentioned using several programming languages and frameworks.<\/p><p>Drupal is my main specialism and the one I have the most experience and knowledge of, but you don't need to use only Drupal code.<\/p><p>Using Composer, you can add parts of other frameworks to other projects.<\/p><p>I don't use Laravel often as a full-stack framework, but I use the Collections library, and recently the Pipelines library, in almost every project - whether it's Drupal or Symfony, it can be added to any PHP project.<\/p><p>Start small, keep things simple, and add what you need.<\/p><p>You don't need to go all in on one option, you can pick the pieces you like and that work for you.<\/p>",
"cta": "",
"tags": ["software-development","php","composer","drupal","symfony","laravel"]
}, {
"title": "Which is the best programming language, CMS or framework?",
"date": "1703203200",
"permalink": "/archive/2023/12/22/best-language-cms-or-framework",
"text": "<p>I started developing websites in HTML and CSS in 2007 before adopting PHP and Drupal in 2008.<\/p><p>Since then, I've used Drupal 6, 7, 8, 9 and 10 to deliver applications for clients, agencies and in-house teams.<\/p><p>I also use Symfony and Laravel, as well as JavaScript, TypeScript and Vue.js.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>There isn't one outright \"best\" programming language, CMS or framework.<\/p><p>It depends on the project and its requirements as well as the knowledge and experience of the team working on it.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal"]
}, {
"title": "New year coaching",
"date": "1703116800",
"permalink": "/archive/2023/12/21/new-year-coaching",
"text": "<p>I have availability to work with a small number of software development teams in the new year and help them ship better software, faster, using tools and techniques like automated testing, test-driven development and static analysis.<\/p><p>Would you like to work with me?<\/p>",
"cta": "",
"tags": ["software-development","coaching"]
}, {
"title": "hover + focus = hocus",
"date": "1703030400",
"permalink": "/archive/2023/12/20/hover-focus-hocus",
"text": "<p>When creating accessible websites, as well as hover states for focusable elements, such as buttons, you also need to add focus styles that apply when users navigate the page using a keyboard and focusing on an element.<\/p><p>With Tailwind, that can mean a lot of duplication if your hover and focus states are similar or the same, as the same classes need to be added with both the <code>:hover<\/code> and <code>:focus<\/code> variants.<\/p><p>One of Tailwind's best features is its extensibility, which means I can create a new interaction state - <code>:hocus<\/code> - that works for both.<\/p><p>It's very easy to do by adding this code to your <code>tailwind.config.js<\/code> or <code>tailwind.config.ts<\/code> file:<\/p><pre><code class=\"javascript\">const plugin = require(\"tailwindcss\/plugin\");module.exports = plugin(({ addVariant }) =&gt; {\u00a0 addVariant(\"hocus\", [\"&amp;:hover\", \"&amp;:focus\"]);});<\/code><\/pre><p>Or, use <a href=\"https:\/\/www.npmjs.com\/package\/tailwindcss-plugin-hocus-state\">the Tailwind CSS plugin I wrote<\/a>.<\/p><p>Get more accessible websites and less duplication today!<\/p>",
"cta": "",
"tags": ["software-development","accessibility","css","tailwind-css"]
}, {
"title": "PHP TUIs, CLIs and open-source with Dan Leech",
"date": "1702944000",
"permalink": "/archive/2023/12/19/php-tui-dan-leech",
"text": "<p>This week on the <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">Beyond Blocks podcast<\/a>, I'm joined by Dan Leech - a PHP Developer and open-source project creator.<\/p><p>He and I recently gave talks at the PHP South West meetup, where Dan introduced a new project - PHP-TUI - for building terminal user interfaces (TUIs) with PHP.<\/p><p>I use one of Dan's other open-source projects - Phpactor - within Neovim, and he also presented at PHP South Wales about PHPBench, so it was great to discuss and learn more about these in this episode.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/6-dan-leech-php-tui\">Listen to the episode now<\/a>, and I'll be back with more in the New Year.<\/p>",
"cta": "",
"tags": ["php","phpc","open-source","neovim"]
}, {
"title": "Should you run static analysis on your tests?",
"date": "1702857600",
"permalink": "/archive/2023/12/18/static-analysis-on-tests",
"text": "<p>I'm an advocate of both automated testing and static analysis but have mostly kept the two separate.<\/p><p>I've typically not run PHPStan on my automated test files - ignoring them in my PHPStan configuration.<\/p><p>As tests aren't production\/implementation code, what's the benefit of analysing them?<\/p><p>Recently, though, I've challenged this and, on some projects, started to run PHPStan on my test classes.<\/p><p>Depending on what level PHPStan is running, the more changes you're likely to have to make to get your test classes to pass the static analysis, and whilst it results in more verbose and explicit code, I prefer that and being able to easily understand what it does rather than implicit.<\/p><p>If you have a bug in your test, static analysis will potentially find that, too, making your test suite more robust.<\/p><p>Looking at some large open-source PHP projects, they run static analysis on their test code.<\/p><p>Presumably, they're benefiting from it, so I'll try it and see if I get the same.<\/p>",
"cta": "",
"tags": ["software-development","php","phpstan","static-analysis","automated-testing"]
}, {
"title": "Fail fast, fix fast",
"date": "1702771200",
"permalink": "/archive/2023/12/17/fail-fast-fix-fast",
"text": "<p>I recently listened to a podcast that discussed Elon Musk and quoted something like, \"If 20% of attempts aren't failing, you aren't taking enough risk\".<\/p><p>In a software context, I'm not advocating that one in five production releases should fail, but I like trying new ideas and approaches.<\/p><p>If you're releasing small changes regularly or practising continuous deployment, changes are easy to revert if there's a problem or the smaller the deployment and the more recently the code was written, then it should be easier to resolve the issue and \"fix forward\" instead of rolling back.<\/p><p>Using feature flags lets you quickly turn off a feature flag while investigating and resolving the issue without needing another deployment.<\/p><p>If you have an appropriate plan to follow in the case of an issue, that mitigates the risk and minimises the impact of a potential issue - making it quicker to resolve and restore the service.<\/p><p>Two of the DORA metrics refer to failure rate and restoration time:<\/p><ul><li>Deployment frequency<\/li><li>Lead time for changes<\/li><li>Change failure rate<\/li><li>Time to restore service<\/li><\/ul><p>Then, it depends on your organisation's tolerance for risk and what's acceptable.<\/p><p>But, the more frequent the releases, the lower the failure rate and the quicker it will be to restore the service if there is an issue.<\/p>",
"cta": "",
"tags": ["software-development","continuous-delivery","continuous-deployment","deployments","feature-flags"]
}, {
"title": "Adding snapshot tests to Build Configs",
"date": "1702684800",
"permalink": "/archive/2023/12/16/adding-snapshot-tests-to-build-configs",
"text": "<p>This week, I've started to add snapshot tests to the <a href=\"https:\/\/www.oliverdavies.dev\/build-configs\">Build Configs project<\/a>.<\/p><p>I had unit tests for the DTO validation to ensure the configuration was correct, but the main thing I wanted to test was I could run it for a given configuration file and get the expected files and contents to be generated.<\/p><p>With snapshot tests, I generate the files for each configuration and compare them to a set that I know to be correct.<\/p><p>If the files match, the tests pass, but, if they don't - such as a bug in the code, the tests will fail.<\/p><p>This is the level that I want to be testing this project and that provides the most value.<\/p><p>If a snapshot test fails, I can try to replicate the underlying issue in a unit test whilst also fixing the snapshot test.<\/p>",
"cta": "",
"tags": ["software-development","php","symfony","build-configs","automated-testing","test-driven-development"]
}, {
"title": "Building your own in-house Drupal distribution",
"date": "1702598400",
"permalink": "/archive/2023/12/15/building-your-own-in-house-drupal-distribution",
"text": "<p>On several occasions, I've seen companies who build a lot of Drupal projects creating their own in-house [Drupal distribution] for new projects.<\/p><p>Whilst this seems like a good idea, the ones I've seen are either not well maintained due to limited time between projects, or they're bloated with features and trying to include too much out of the box.<\/p><p>If you maintain an in-house distribution, or are thinking of creating one, my advice is to ensure it's maintained by allocating enough time for this, and to keep it lean and only include the minimum amount of required functionality.<\/p><p>Alternatively, maybe keep a template composer.json file to base new projects on instead of a full distribution.<\/p><p>That could declare the modules and themes you want to include, without the additional overhead.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/14\/save-time-and-effort-with-drupal-distributions\">drupal distribution<\/a><\/p>",
"cta": "",
"tags": ["software-development","php","drupal"]
}, {
"title": "Save time and effort with Drupal distributions",
"date": "1702512000",
"permalink": "/archive/2023/12/14/save-time-and-effort-with-drupal-distributions",
"text": "<p>Drupal distributions are pre-built versions of Drupal for specific use cases.<\/p><p>Need an eCommerce store? Use Commerce Kickstart.<\/p><p>Are you a local council looking for a new website? Look at LocalGov Drupal.<\/p><p>Contenta CMS is an API-first Drupal distribution for headless and decoupled content.<\/p><p>There are numerous others - each containing a list of pre-installed and configured modules to give you more functionality out of the box.<\/p><p>If you're starting a new project, try starting with an appropriate distribution instead of starting from scratch with a standard installation of Drupal core and save yourself time and effort.<\/p><p>Don't know if using a distribution could help for you? <a href=\"https:\/\/www.oliverdavies.uk\/call\">Book a 1-on-1 consulting call<\/a>, and I'll help you out.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","phpc"]
}, {
"title": "Reviving an old PHP project",
"date": "1702425600",
"permalink": "/archive/2023/12/13/reviving-an-old-php-project",
"text": "<p>I use Gmail\/Google Apps for my email address, and I used to use a LOT of filters.<\/p><p>Inspired by a Ruby gem, I created a PHP library that allows me to declare my filters in PHP and create them in XML.<\/p><p>I could import the generated XML into Gmail to create the filters.<\/p><h2 id=\"gmail-filter-buider\">Gmail Filter Buider<\/h2><p>The project is <a href=\"https:\/\/github.com\/opdavies\/gmail-filter-builder\/tree\/3.x\">Gmail Filter Builder<\/a>, and the last commit was in July 2020.<\/p><p>It was based on PHP 7 (unsupported since November 2022) and uses five Symfony components and several other packages.<\/p><p>Today, as I looked at my current Gmail filters, I decided to revisit and update Gmail Filter Builder.<\/p><h2 id=\"updating-the-project\">Updating the project<\/h2><p>I set PHP 8.1 as the minimum required version and used a Nix Flake to ensure this was available.<\/p><p>I updated the Symfony components from the 3.x versions to 6.x, the latest versions compatible with PHP 8.1. I also updated the other PHP packages to their compatible versions.<\/p><p>After some small changes to the application's code, it worked with PHP 8.1 and generated filters.<\/p><p>Once it worked, I updated <a href=\"https:\/\/github.com\/opdavies\/gmail-filter-builder\/tree\/3.x\/examples\">the examples<\/a>.<\/p><p>Whilst it wasn't a difficult process in this instance, having a test suite I could rely on helped me to know it worked as expected during the upgrade.<\/p><p>I don't know if I'll continue to use or maintain Gmail Filter Builder again, but it was an interesting exercise to do this morning.<\/p>",
"cta": "",
"tags": ["php","phpc","open-source"]
}, {
"title": "DrupalCon session survey results",
"date": "1702339200",
"permalink": "/archive/2023/12/12/drupalcon-session-survey-results",
"text": "<p>The survey results from my automated testing and test-driven development session at DrupalCon Lille are in, and here they are:<\/p><h2 id=\"how-would-you-rate-the-speakers%27s-mastery-of-this-topic%3F\">How would you rate the speaker(s)'s mastery of this topic?<\/h2><p>24 responses.<\/p><ul><li>Excellent - 33.3%<\/li><li>Very good - 50%<\/li><li>Good - 16.7%<\/li><li>Fair - 0%<\/li><li>Poor - 0%<\/li><\/ul><h2 id=\"how-would-you-rate-the-speakers%27s-presentation-skills%3F\">How would you rate the speaker(s)'s presentation skills?<\/h2><p>24 responses.<\/p><ul><li>Excellent - 20.8%<\/li><li>Very good - 37.5%<\/li><li>Good - 33.3%<\/li><li>Fair - 8.3%<\/li><li>Poor - 0%<\/li><\/ul><h2 id=\"how-would-you-rate-the-speakers%E2%80%99s-slides-and-other-session-materials%3F\">How would you rate the speaker(s)\u2019s slides and other session materials?<\/h2><p>25 responses.<\/p><ul><li>Excellent - 24%<\/li><li>Very good - 32%<\/li><li>Good - 36%<\/li><li>Fair - 8%<\/li><li>Poor - 0%<\/li><\/ul><h2 id=\"overall%2C-how-would-you-rate-this-session%3F\">Overall, how would you rate this session?<\/h2><p>25 responses.<\/p><ul><li>Excellent - 36%<\/li><li>Very good - 28%<\/li><li>Good - 36%<\/li><li>Fair - 0%<\/li><li>Poor - 0%<\/li><\/ul><p>Thanks to everyone who completed the survey for their feedback.<\/p><p>P.S. If you'd like your own software development training or coaching, including automated testing and test-driven development, I currently have availability for <a href=\"https:\/\/www.oliverdavies.uk\/team-coaching\">team coaching<\/a> and <a href=\"https:\/\/www.oliverdavies.uk\/pricing\">private talks and workshops<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing","php","phpc","drupal","drupalcon"]
}, {
"title": "Custom coding standards and conventions",
"date": "1702252800",
"permalink": "/archive/2023/12/11/custom-coding-standards-and-conventions",
"text": "<p>Open-source projects like Drupal and Symfony have their own published coding standards and conventions.<\/p><p>For example, from <a href=\"https:\/\/symfony.com\/doc\/current\/contributing\/code\/standards.html\">Symfony's coding standards<\/a>:<\/p><ul><li>Prefix all abstract classes with <code>Abstract<\/code> except PHPUnit <code>*TestCase<\/code>.<\/li><li>Suffix interfaces with <code>Interface<\/code>;<\/li><li>Suffix traits with <code>Trait<\/code>;<\/li><\/ul><p>And from <a href=\"https:\/\/www.drupal.org\/docs\/develop\/standards\/php\/php-coding-standards\">Drupal's<\/a>:<\/p><ul><li>Use an indent of 2 spaces, with no tabs.<\/li><li>Lines should have no trailing whitespace at the end.<\/li><li>Variables should be named using lowercase, and words should be separated either with uppercase characters (example: <code>$lowerCamelCase<\/code>) or with an underscore (example: <code>$snake_case<\/code>). Be consistent; do not mix camelCase and snake_case variable naming inside a file.<\/li><\/ul><p>But what about within custom applications?<\/p><p>Do you have your own agreed coding standards and conventions to keep the code consistent?<\/p><p>Do you explicitly follow the published coding standards, customise them, or follow something else?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Do you know where to put new custom modules, how to name them and what conventions to follow when writing code?<\/p><p>Do you know where to add a new stylesheet to your theme?<\/p><p>If not, or it's implied, it's worth writing it down and being explicit - either within your project's or company's documentation or publicly.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","symfony","clean-code"]
}, {
"title": "Suffixing names",
"date": "1702166400",
"permalink": "/archive/2023/12/10/suffixing-names",
"text": "<p>When writing code, it's common to suffix the class name with the type of class it is.<\/p><p>I do this often for most types of classes, such as Controllers, EventListeners, Factories, Repositories and Builders.<\/p><p>However, I don't always for value objects and data transfer objects (DTOs).<\/p><p>Also, I don't always suffix interfaces with <code>Interface<\/code>.<\/p><p>I've been re-reading the documentation for the Symfony Serializer component, which references both <code>NameConverterInterface<\/code> and <code>MyDto::class<\/code>.<\/p><p>Whilst it does make the names more verbose, it does clarify what the class is used for.<\/p><p>Symfony's coding standards and Drupal's PHP coding standards have conventions for this, but what do you think?<\/p><p>Do you add suffixes to your class or interface names, or do you prefer the simplified versions?<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","symfony","clean-code"]
}, {
"title": "Rebuild or iterate",
"date": "1702080000",
"permalink": "/archive/2023/12/09/rebuild-or-iterate",
"text": "<p>As I said in <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/08\/dont-just-rewrite\">yesterday's email<\/a>, I'm discussing with a team how to implement their new website design.<\/p><p>Their website has been live for a couple of years, and now they want to refresh its look and feel.<\/p><p>The current theme includes a lot of technical debt and legacy code, such as using an older CSS framework and build tools that need unsupported versions of packages to compile it and generate the scripts and stylesheets.<\/p><p>There are two ways they could approach this:<\/p><p>They could continue to iterate on the current theme, making and releasing small changes to move forward in small steps and slowly repaying the technical debt.<\/p><p>Alternatively, they could create a new theme from scratch.<\/p><p>This would allow them to start with new build tools, a modern CSS framework and small and simple stylesheets.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>There are advantages and disadvantages to both approaches.<\/p><p>Iterating on the original theme allows for continuous improvement, but it would take longer to remove the old frameworks and build tools - if that would be possible at all.<\/p><p>Rebuilding and re-inventing would mean immediately avoiding the technical debt and legacy tools, but it comes with its own risks, and you'd need to wait until the whole theme was completed before it could be launched.<\/p><p>There isn't a right and wrong answer, and it will depend on the thoughts and objectives of the team and business.<\/p>",
"cta": "",
"tags": ["software-development","drupal"]
}, {
"title": "Don&#039;t just rewrite. Re-invent.",
"date": "1701993600",
"permalink": "/archive/2023/12/08/dont-just-rewrite",
"text": "<p>A quote that stuck out to me from today's Neovimconf conference was this by Bj\u00f6rn Linse (aka bfredl):<\/p><blockquote> <p>Don't just rewrite. Re-invent.<\/p> <p>If you're going to start over from scratch, reconsider everything.<\/p><\/blockquote><p>This was in the context of what would be added to the core editor, what would be delegated to plugins, etc, but this also applies to other things.<\/p><p>I'm discussing with someone whether to build a new Drupal theme or keep iterating on the existing one.<\/p><p>If they start from scratch, they can re-invent and re-consider everything and decide which parts of the existing theme to reuse and which to leave and re-create.<\/p>",
"cta": "",
"tags": ["software-development","neovimconf"]
}, {
"title": "A Drupal case study from Oxfam",
"date": "1701907200",
"permalink": "/archive/2023/12/07/a-drupal-case-study-from-oxfam",
"text": "<p>In the latest episode of the Beyond Blocks podcast, Ed Crompton and I discuss his case study of upgrading 15 websites for Oxfam on how to build and test a multilingual, multisite Drupal migration.<\/p><p>We discussed focussing on delivering value, prioritising based on usefulness to users and stakeholders, Agile vs agile, and how they pivoted from a \"big bang\" approach to delivering rapid increments in smaller batches.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/4-ed-crompton-oxfam-case-study\">Listen to the episode now<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","agile"]
}, {
"title": "Open-source first doesn&#039;t mean you need to cover every use case",
"date": "1701820800",
"permalink": "/archive/2023/12/06/open-source-first-doesnt-mean-you-need-to-cover-every-use-case",
"text": "<p>An argument against the <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/01\/the-contribution-first-workflow\">contribution-first and open-source-first approach<\/a> is that it takes longer than writing custom code.<\/p><p>I think that this is due to thinking that you need to cover all use cases within the code if it's open-sourced, whereas, in custom code, you only write the code you need.<\/p><p>My approach is to write the same code, whether it's private and custom or open-sourced.<\/p><p>The code is based on the same set of requirements, and the only code that should be written should be enough to satisfy those requirements.<\/p><p>It doesn't get written if something isn't part of that objective.<\/p><p>It could be added to a public roadmap for the future if it doesn't need to be part of the initial minimal version.<\/p><p>If someone creates an issue to request new functionality or submits a pull request to contribute potential changes, you decide whether to accept or reject it or even add them as a maintainer to manage their own contributions as well as administrative tasks like managing the issue queues.<\/p><p>If you accept their code, you get the benefit of it (though you also need to maintain and own it) or, if you reject it, you can continue focusing on your minimum-viable version for its initial project.<\/p>",
"cta": "",
"tags": ["software-development","open-source","contribution"]
}, {
"title": "Open-source encourages more open-source",
"date": "1701734400",
"permalink": "/archive/2023/12/05/open-source-encourages-open-source",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/12\/04\/writing-contrib-modules-as-glue-between-your-custom-code\">In yesterday's email<\/a>, I mentioned the Private Message Queue module - a contributed Drupal module we wrote for a project as part of a contribution-first workflow.<\/p><p>In our experience, doing that and releasing Private Message Queue as its own open-source project encouraged more open-source contributions.<\/p><p>We started to ask questions like, \"Which user should the messages be sent from?\".<\/p><h2 id=\"system-users\">System Users<\/h2><p>This led us to create the <a href=\"https:\/\/www.drupal.org\/project\/system_user\">System User module<\/a>.<\/p><p>Inspired by system users in Linux, it provides a way to identify and retrieve system users that aren't tied to individuals' accounts and without relying on \"magic\" user IDs.<\/p><p>But what if a website doesn't have a system user?<\/p><h2 id=\"null-users\">Null Users<\/h2><p>This led to the <a href=\"https:\/\/www.drupal.org\/project\/null_user\">Null User module<\/a>.<\/p><p>Following the Null object pattern, if there isn't a system user, instead of returning <code>NULL<\/code> or <code>FALSE<\/code>, you return a null user that you use in the same way, though they'll have default empty values and won't perform any actions.<\/p><p>This pattern simplifies your code as you don't need to check for <code>NULL<\/code> or <code>FALSE<\/code> values.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>If I remember correctly, as part of the project, we created and released around ten new contributed modules to Drupal.org.<\/p><p>We were able to move straight onto the next phase of the project.<\/p><p>We didn't need to clean them up or refactor them beforehand. We didn't need to dedicate any additional time as they were already released.<\/p>",
"cta": "",
"tags": ["software-development","contribution","open-source","drupal","php"]
}, {
"title": "Writing contrib modules as glue between your custom code",
"date": "1701648000",
"permalink": "/archive/2023/12/04/writing-contrib-modules-as-glue-between-your-custom-code",
"text": "<p>A few years ago, I worked on an event booking and management website for a charity in the UK.<\/p><p>One required piece of functionality was to allow event organisers to send a private message to all attendees of an event.<\/p><p>We decided to use the <a href=\"https:\/\/www.drupal.org\/project\/private_message\">Private Message module<\/a> but were concerned about hitting memory limits or timeouts, as some events had several hundred attendees.<\/p><p>We decided that we needed to use a queue and have it process and send the messages.<\/p><p>This split the feature into three parts:<\/p><ul><li>The UI for event organisers to enter and send their messages.<\/li><li>The queue that stores and processes pending messages in the background.<\/li><li>The Private Message module that would create and send each message, provide an inbox for each user, and provide notifications.<\/li><\/ul><p>The UI for event organisers was specific to the project and had to be custom code and not open-sourced.<\/p><p>The Private Message module is already a contributed module, but what about the queue part?<\/p><p>This is why the <a href=\"https:\/\/www.drupal.org\/project\/private_message_queue\">Private Message Queue module<\/a> was created.<\/p><p>Instead of keeping it within the project's custom code, we created it as an open-source module on Drupal.org.<\/p><p>It contains no customer or project-specific information and only adds generic functionality - it creates a queue to hold private messages to be processed in the background.<\/p><p>It provides the glue between our custom UI and the Private Message module.<\/p><p>As there was no reason why we needed to keep it private, we made it public and developed it as its own project from the beginning instead of planning and hoping to do so later.<\/p>",
"cta": "",
"tags": ["software-development","contribution","open-source","drupal","php"]
}, {
"title": "The contribution-first workflow",
"date": "1701388800",
"permalink": "/archive/2023/12/01/the-contribution-first-workflow",
"text": "<p>I've worked on many software projects with a lot of custom code.<\/p><p>Not all the code is specific to that client or project, and often, code is identified as it can be extracted from the project and open-sourced as a Drupal module, PHP or JavaScript library, or Tailwind CSS plugin.<\/p><p>Usually, the code is written as custom code initially, with the best intentions to revisit it once the project is complete and open-source it.<\/p><p>But this rarely happens, as there's always the next sprint or project waiting.<\/p><p>It takes too long to extract the code as it usually needs to be tidied or refactored beforehand.<\/p><p>It may have been written with the client or project name within the code, which needs changing.<\/p><p>My suggestion is to avoid this step.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Instead of writing it as custom code and hopefully extracting it later, start it as a separate module, library or plugin, and use Composer or npm to add it to your project as another dependency.<\/p><p>Whilst it's a slightly smaller overhead, it's better and less risky than rewriting or refactoring code later and it's already open-sourced.<\/p><p>Plus, you may get some issues, testing and improvements from others along the way.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "Are bugs good for users?",
"date": "1701302400",
"permalink": "/archive/2023/11/30/are-bugs-good-for-users",
"text": "<p>I recently listened to a podcast episode that was discussing if bugs are good for users.<\/p><p>It suggested that bugs allowed for engagement between you and the user.<\/p><p>If someone reports a bug, you can tell them when you've fixed it. This encourages communication, and the customer will feel more connected to the product.<\/p><p>While this may be true, I think that users would prefer applications that just work.<\/p><p>If your application has major bugs, they may just go elsewhere. Maybe they won't even report the issue to you.<\/p><p>Major bugs can damage your reputation with your users and potential customers, as well as affect potential sales.<\/p><p>If you can avoid them to begin with, that's what I'd suggest. That's what tools and processes such as automated testing, test-driven development and static analysis are for.<\/p><p>When a user reports it (if they do at all), it could be too late.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","static-analysis"]
}, {
"title": "The lowest level is better than no level",
"date": "1701216000",
"permalink": "/archive/2023/11/29/the-lowest-level-is-better-than-no-level",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/11\/28\/which-phpstan-level-should-you-use\">Yesterday's email<\/a> introduced the different levels that PHPStan offers and which you may want to use on your codebase.<\/p><p>In the same way as having a single test is better than none, even if you run PHPStan at the lowest level, it's better than not running it at all.<\/p><p>Level 0 includes:<\/p><blockquote> <p>Basic checks, unknown classes, unknown functions, unknown methods called on $this, wrong number of arguments passed to those methods and functions, always undefined variables<\/p><\/blockquote><p>P.S. If you want to utilise PHPStan and static analysis on your development team and get fewer bugs, I have <a href=\"https:\/\/www.oliverdavies.uk\/team-coaching\">availability for team coaching<\/a>. I'll show you how!<\/p>",
"cta": "",
"tags": ["software-development","clean-code","static-analysis","php","phpstan"]
}, {
"title": "Which PHPStan level should you use?",
"date": "1701129600",
"permalink": "/archive/2023/11/28/which-phpstan-level-should-you-use",
"text": "<p>Which PHPStan level should you use?<\/p><p>PHPStan has different levels.<\/p><p>When you run it on your code, the errors you see will depend on what level you set.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/11\/27\/finding-the-best-test-base\">In yesterday's email<\/a>, the first example code block didn't generate an error until level 5 was used.<\/p><p>So, how do you know which level to use?<\/p><h2 id=\"for-greenfield-projects\">For greenfield projects<\/h2><p>For new (greenfield) code, install and configure PHPStan before you write any code and have and have it run automatically as part of a CI pipeline.<\/p><p>If you work on a team, speak with the other members and decide how strict you want PHPStan to be.<\/p><p>Read the rule levels and decide which are the most valuable for your team.<\/p><p>If you haven't used PHPStan or static analysis before, maybe start with a lower level.<\/p><p>For me, typehints and return type checking are a must, though I like to use as high a level as possible.<\/p><p>The more information you can provide to PHPStan, the more it will understand your code, give better results and be more likely to find potential bugs or issues.<\/p><h2 id=\"for-brownfield-projects\">For brownfield projects<\/h2><p>For existing (brownfield) code, start at the lowest level, which will give you the least number of errors.<\/p><p>Fix any errors, exclude any rules you want to ignore or generate a baseline containing any existing errors.<\/p><p>If you like, increase the level and repeat the process.<\/p><p>Keep increasing the level as long as you feel comfortable, and PHPStan gives you meaningful results.<\/p><p>Again, if you haven't used PHPStan or static analysis before, maybe stick with a lower level.<\/p><p>If you start with a lower level, you can increase it later.<\/p>",
"cta": "",
"tags": ["software-development","clean-code","static-analysis","phpstan"]
}, {
"title": "Finding the best test base",
"date": "1701043200",
"permalink": "/archive/2023/11/27/finding-the-best-test-base",
"text": "<p>As well as different base classes for types of tests - i.e. functional, kernel and unit - there are other test base classes within those that can be used to simplify things.<\/p><p>For example, if we have this test:<\/p><pre><code class=\"language-php\">&lt;?phpnamespace Drupal\\Tests\\example\\Kernel;use Drupal\\KernelTests\\KernelTestBase;use Drupal\\Tests\\node\\Traits\\NodeCreationTrait;use Drupal\\Tests\\user\\Traits\\UserCreationTrait;class ExampleTest extends KernelTestBase { use NodeCreationTrait; use UserCreationTrait; protected static $modules = [ 'node', 'user', ]; public function setUp(): void { parent::setUp(); $this-&gt;installEntitySchema(entity_type_id: 'node'); $this-&gt;installEntitySchema(entity_type_id: 'user'); } public function testExample(): void { $user = $this-&gt;createUser(); $article = $this-&gt;createNode([ 'title' =&gt; 'Test article', 'uid' =&gt; $user, ]); self::assertSame('1', $article-&gt;getOwnerId()); }}<\/code><\/pre><p>Both creation traits must be imported, the <code>node<\/code> and <code>user<\/code> modules must be enabled, and the entity tables must be installed.<\/p><p>When writing a lot of tests, this can result in duplication and more complex tests that take longer to write.<\/p><p>This can be simplified using <code>EntityKernelTestBase<\/code> instead of <code>KernelTestBase<\/code>:<\/p><pre><code class=\"language-php\">&lt;?phpuse Drupal\\KernelTests\\Core\\Entity\\EntityKernelTestBase;use Drupal\\Tests\\node\\Traits\\NodeCreationTrait;class ExampleTest extends EntityKernelTestBase { use NodeCreationTrait; protected static $modules = [ 'node', ]; public function testExample(): void { $user = $this-&gt;createUser(); $article = $this-&gt;createNode([ 'title' =&gt; 'Test article', 'uid' =&gt; $user, ]); self::assertSame('1', $article-&gt;getOwnerId()); }}<\/code><\/pre><p>The class is simpler, fewer modules must be specified, and the entity schemas are automatically installed.<\/p><p>As well as the core modules, some contrib modules also provide their own base test cases.<\/p><p>If you're using the Webform module, you may want to use <code>WebformAccessTestBase<\/code> instead of the standard <code>UnitTestCase<\/code>.<\/p><p>It's definitely worth spending some time looking at what base test cases are available and which are the best ones to use for your own tests.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","php","drupal"]
}, {
"title": "To docblock or not to docblock",
"date": "1700956800",
"permalink": "/archive/2023/11/26/to-docblock-or-not-to-docblock",
"text": "<h2 id=\"what-are-docblocks%3F\">What are docblocks?<\/h2><p>Docblocks are comment blocks that describe a class or method and document its parameters and return types.<\/p><p>Unfortunately, they're often overused and are outdated compared to the code they're describing, or repeat the same information again.<\/p><p>For example, here's some PHP code:<\/p><pre><code class=\"language-php\">function sayHello(string $name, array $options = ['shout' =&gt; false]): void {\u00a0\u00a0\u00a0\u00a0 echo 'Hello, ' . $name;}sayHello('');sayHello('Oliver', ['shout2' =&gt; true]);sayHello('Oliver', ['shout' =&gt; 'banana']);<\/code><\/pre><p>It's readable and understandable.<\/p><p>It has types.<\/p><p>We know that the name needs to be a string and that an array of options can be passed.<\/p><p>This is how I like to write my code. In a clear and readable way with minimal comments.<\/p><p>This code works, but there are issues with it.<\/p><p>Do we want the name to potentially be an empty string?<\/p><p>What if different options are passed in?<\/p><h2 id=\"step-1\">Step 1<\/h2><p>If you use PHPStan (a PHP static analysis tool), you won't get any errors until you test against level 6.<\/p><p>Then you'll get this error:<\/p><blockquote> <p>Function sayHello() has parameter $options with no value type specified in iterable type array.<\/p><\/blockquote><p>Now, we can use a docblock to provide more information to PHPStan to describe the structure of the <code>$options<\/code> array and that it has strings for keys and boolean values.<\/p><pre><code class=\"language-php\">\/**\u00a0* @param array&lt;string, bool&gt; $options\u00a0*\/<\/code><\/pre><p>Although it's not erroring, we can add the <code>$name<\/code> parameter and declare it as a <code>string<\/code>.<\/p><pre><code class=\"language-php\">\/**\u00a0* @param string $name\u00a0* @param array&lt;string, bool&gt; $options\u00a0*\/<\/code><\/pre><p>Now, the docblock adds some context and value but essentially repeats the defined types.<\/p><h2 id=\"step-2\">Step 2<\/h2><p>We can do more with the docblock and tell PHPStan more about what we want the values to be.<\/p><p>We don't want an empty string for a name and want the correct options and values.<\/p><p>Let's change the docblock to this:<\/p><pre><code class=\"language-php\">\/**\u00a0* @param non-empty-string $name\u00a0* @param array{shout: bool} $options\u00a0*\/<\/code><\/pre><p>This specified the name cannot be an empty string and the shape of the options array.<\/p><p>With this, we get these errors that weren't included before:<\/p><ul><li>Parameter #1 $name of function sayHello expects non-empty-string, '' given.<\/li><li>Parameter #2 $options of function sayHello expects array{shout: bool}, array{shout2: true} given.<\/li><li>Parameter #2 $options of function sayHello expects array{shout: bool}, array{shout: 'banana'} given.<\/li><\/ul><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>While I like to write minimal, readable and \"self-documenting\" code and not overuse docblocks by adding them everywhere, I only add them and comments where needed and provide value, either to someone reading the code in the future or to tools like PHPStan that help me make the code better.<\/p>",
"cta": "",
"tags": ["php","phpstan","static-analysis","clean-code"]
}, {
"title": "Community engagement for non-technical Drupal enthusiasts",
"date": "1700870400",
"permalink": "/archive/2023/11/25/community-engagement-for-non-technical-drupal-enthusiasts",
"text": "<p>This week's guest on the Beyond Blocks podcast is\u00a0Niklas Franke - Digital Marketing Manager at Factorial.<\/p><p>Niklas was a fellow speaker at the recent DrupalCon conference in Lille - presenting multiple sessions, whilst Factorial were sponsors of the event.<\/p><p>In this episode, Niklas and I discussed his first experience of DrupalCon, presenting a session on contribution for non-technical Drupalers, the German Drupal community, what the Splash Awards are and how to organise your own event.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/3-non-technical-contribution\">Listen to the episode now<\/a>.<\/p>",
"cta": "",
"tags": ["drupal","drupalcon","open-source","contribution","podcast"]
}, {
"title": "Are conventional commits worth it?",
"date": "1700784000",
"permalink": "/archive/2023/11/24/are-conventional-commits-worth-it",
"text": "<p>For some time, I've written commit messages following the Conventional Commits specification, where you start the subject with the type of commit - such as <code>feat<\/code>, <code>fix<\/code>, <code>chore<\/code>, <code>docs<\/code>, etc - and provide an optional scope before completing the subject line (the first line in the message).<\/p><p>Then, it is encouraged to add a longer body to the message and provide any links and task IDs that the change relates to.<\/p><p>Now I've been using it for a while, I'm deciding whether it adds value for me and whether it's worth me using it.<\/p><p>I don't create automatic CHANGELOG files from the commit types.<\/p><p>The scopes are usually arbitrary, it's unclear which scope (or scopes) should be added, or it repeats the module name I'm working on (which I could see from the Git diff).<\/p><p>While I see value in writing descriptive commit messages, I'm unsure if I do to format the subject line in this way.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>I like to use an iterative approach to my workflow. I like to try things and see if they work for me. If not, I can stop or continue iterating.<\/p><p>If working with others, should you focus on writing commits that categorise commit messages within their subject or writing descriptive commit messages that capture why the change is needed?<\/p><p>Which provides the most value when looking back at the Git log in the future?<\/p>",
"cta": "",
"tags": ["software-development","git"]
}, {
"title": "Partial mocking",
"date": "1700697600",
"permalink": "/archive/2023/11/23/partial-mocking",
"text": "<p>Today, I wrote a test whilst fixing a bug in some legacy custom Drupal code.<\/p><p>The code is for a custom block, which can be configured using user-defined settings - including a link URL.<\/p><p>In this case, if the link was null (one hadn't been provided), the link was generated to the home page instead of the desired destination.<\/p><h2 id=\"my-first-attempt\">My first attempt<\/h2><p>There was a combination of settings needed to replicate the bug, such as the current site language, the node type the block was placed on and, of course, an empty link URL.<\/p><p>Because the block uses the current route to get the current node, my first attempt to test this was to use a browser\/functional test.<\/p><p>That failed quickly after having to enable various other custom modules due to dependencies and to add and configure unrelated configuration settings.<\/p><h2 id=\"my-second-attempt\">My second attempt<\/h2><p>My second attempt used kernel\/integration tests, but as there's no <code>setParameter()<\/code> method on the route matcher I could use in the test, I'd need to rely on mocking.<\/p><p>In a unit test, everything needs to be mocked, but a kernel test allows me to be more selective, only mock what I need, and use the real services for everything else - a.k.a. partial mocking.<\/p><h2 id=\"the-result\">The result<\/h2><p>I replicated the bug by setting the default and current languages, creating a mock language manager, creating a node of the required type and returning it from a mocked route match.<\/p><p>Everything else remained the same.<\/p><p>Then, I fixed the bug and used a data provider to provide different variables into the test so each use case was covered.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>The whole test file is 129 lines and would have been much more if I'd had to replicate all the configuration in a functional test or mock everything in a unit test.<\/p><p>An integration test with partial mocking was ideal in this case, as it gave me the most flexibility to test what I needed whilst keeping the code simple.<\/p><p>Whilst I'm aware of over-using mocks, this was an ideal situation to use them.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development","drupal","php","phpunit","phpc"]
}, {
"title": "Frequency reduces difficulty",
"date": "1700611200",
"permalink": "/archive/2023/11/22/frequency-reduces-difficulty",
"text": "<p>\"Frequency reduces difficulty\" is a phrase I heard on a podcast today, though I have heard it before.<\/p><p>It's a better way of saying, \"If it hurts, do it more often\".<\/p><p>If software deployments and releases are large, risky, and contain bugs, break them into smaller, less-risky deployments and release them more often.<\/p><p>If you get a lot of merge conflicts in Git, merge your code more frequently. Make your topic branches as short-lived as possible, or try trunk-based development and avoid topic branches by default.<\/p><p>If writing tests is difficult and takes time, persevere. It will get easier the more you do it, and you'll save time in the future by releasing fewer bugs and being able to refactor safely.<\/p>",
"cta": "",
"tags": ["software-development","agile","continuous-delivery","git","trunk-based-development"]
}, {
"title": "Why I built &quot;Build Configs&quot;",
"date": "1700524800",
"permalink": "/archive/2023/11/21/why-i-built-build-configs",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">Build Configs<\/a> is a tool I wrote and recently <a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-build-configs\">gave a lightning talk about<\/a> at the PHP South West meetup in Bristol, UK.<\/p><p>It's a command-line tool that creates customised per-project configuration files from a set of reusable templates.<\/p><p>It's a Symfony project using components such as Console, Validator, and Twig for templating.<\/p><p>But why did I build it?<\/p><h2 id=\"what-was-i-doing-before%3F\">What was I doing before?<\/h2><p>When starting a new project, I'd copy configuration files from an existing project and alter them as needed.<\/p><p>If a project uses a <code>docroot<\/code> directory instead of <code>web<\/code>, a different version of PHP, or Caddy instead of Nginx, I'd need to change the files manually for the new project, add any required features, or fix any bugs.<\/p><h2 id=\"what-was-the-issue-with-this%3F\">What was the issue with this?<\/h2><p>It took time to set up new projects, and there would be drift between them.<\/p><p>I may have added a feature to one project, but it wouldn't exist in the one I was working on.<\/p><p>If I needed to move a feature from one project to another, I needed to do it manually.<\/p><h2 id=\"how-does-build-configs-solve-the-issue%3F\">How does Build Configs solve the issue?<\/h2><p>Now, I have a canonical set of template files.<\/p><p>Instead of making ad-hoc changes to each project, I can add new features and fix bugs in the templates, and re-generate the configuration files for each project.<\/p><p>I don't need to worry about drift between projects because they're all in sync and generated automatically.<\/p><p>It's quicker to create and onboard projects using existing configurations instead of copying files and making manual changes.<\/p><p>If you want to see an example, <a href=\"https:\/\/www.youtube.com\/watch?v=LkhsdmxReUc\">watch this video<\/a> where I set up a new Drupal 10 project from nothing to running website in less than a minute.<\/p>",
"cta": "",
"tags": ["docker","docker-compose","php","phpc","drupal","symfony"]
}, {
"title": "What&#039;ll be in Drupal 11?",
"date": "1700438400",
"permalink": "/archive/2023/11/20/whatll-be-in-drupal-11",
"text": "<p>Drupal 9 is end-of-life and no longer supported.<\/p><p>Drupal 10 is the current stable version, and the development branch for Drupal 11 has just been started.<\/p><p>But what will be in Drupal 11?<\/p><p>Well, we don't know yet.<\/p><p>Drupal's release schedule is based on fixed dates and not on features.<\/p><p>Whatever is ready on the release date will be included. If something isn't ready, it'll be in a future version.<\/p><p>If something is ready sooner, it'll be in a minor 10 version, such as Drupal 10.2 or 10.3. We've seen it recently with various UI improvements in 10.1 - with more in 10.2.<\/p><p>We saw new features, such as Layout Builder, added to Drupal core within the Drupal 8 lifecycle, and there's still time to add more to Drupal 10.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>But, like Drupal 9 and 10, Drupal 11 won't mean a major rewrite to your code.<\/p><p>Drupal 11 is based on Drupal 10, so the modules and themes you use will be able to work with both, allowing you to upgrade incrementally.<\/p><p>While there isn't a definitive list of new features or changes for Drupal 11, based on things I saw and learned about at DrupalCon, I'm excited to see what makes it.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "Why I&#039;ve standardised on &#039;run&#039; scripts",
"date": "1700352000",
"permalink": "/archive/2023/11/19/why-ive-standardised-on-run-scripts",
"text": "<p>In some of my first emails to this list, I wrote about <code>just<\/code> and <code>run<\/code> files.<\/p><p>Both allow you to write project-specific aliases and commands. For example, instead of running <code>docker compose exec php phpunit<\/code>, you run <code>just test<\/code> or <code>run test<\/code>.<\/p><p>While <code>just<\/code> uses a simple Makefile-like syntax, it requires its own program, so it needs to be installed.<\/p><p>While I have it installed locally, I've had instances where CI pipelines have failed because they can't download and install <code>just<\/code> and not because of an error in my code.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>A <code>run<\/code> script is a file of Bash functions.<\/p><p>Because it's written in Bash, it runs anywhere without installing additional dependencies.<\/p><p>If a CI pipeline fails, which is less often, it's due to a failure within my code and not because of a download error.<\/p>",
"cta": "",
"tags": ["software-development","continuous-integration"]
}, {
"title": "Writing good test names",
"date": "1700265600",
"permalink": "/archive/2023/11/18/writing-good-test-names",
"text": "<p>In PHPUnit, there are different ways to write test methods.<\/p><p>The standard way is to use camel-case method names with a <code>test<\/code> prefix, for example:<\/p><pre><code class=\"language-php\">public function testTheProjectNameShouldBeAString(): void{ \/\/ ...}<\/code><\/pre><p>Another popular way, particularly in some frameworks, is to use snake-case method names:<\/p><pre><code class=\"language-php\">\/** @test *\/public function the_project_name_should_be_a_string(): void{ \/\/ ...}<\/code><\/pre><p>This may be more readable but only works if the <code>@test<\/code> annotation is present.<\/p><p>What if you need to add another annotation, such as <code>@dataProvider<\/code> to the test? Do you do multi-line docblocks everywhere, or mix and match single and multiple line docblocks depending on the test?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>My preference switches between both ways of writing test methods.<\/p><p>But, whichever way I write it, I write descriptive method names that explain what the test does - even if it means having a long method name.<\/p><p>I avoid short and generic names like <code>testUpdate()<\/code>.<\/p><p>People should be able to read the test name and understand what it does and what it's testing.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing","php","phpunit"]
}, {
"title": "Drupal&#039;s Alternate Realities",
"date": "1700179200",
"permalink": "/archive/2023/11/17/drupal-s-alternate-realities",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/podcast\/2-alternate-realities\">This week's episode<\/a> of the Beyond Blocks podcast is live, where I speak with Panagiotis Moutsopoulos (vensires on Drupal.org) - Drupal Backend Developer at E-Sepia.<\/p><p>We discuss his first time DrupalCon and, more specifically, his session \"Drupal's Alternate Realities\" - a \"Birds of a Feather\" (BoF) session presenting some history, but mainly the different ways to tackle a problem in Drupal using different methodologies.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc","beyond-blocks","podcast"]
}, {
"title": "Avoiding over-mocking",
"date": "1700092800",
"permalink": "/archive/2023/11/16/avoiding-over-mocking",
"text": "<p>In unit tests, and sometimes in kernel tests, you need to mock the dependencies you aren't testing, but you can over-mock and only be testing the mocks and not the code you want to test.<\/p><p>Here's an example (thanks, ChatGPT, for the code).<\/p><h2 id=\"the-class-to-be-tested-myclass.php\">The Class to be tested (MyClass.php)<\/h2><pre><code class=\"language-php\">&lt;?phpclass MyClass { public function __construct( private DependencyInterface $dependency ) { } public function doSomething() { $result = $this-&gt;dependency-&gt;performAction(); return \"Result: \" . $result; }}<\/code><\/pre><h2 id=\"dependency-interface-dependencyinterface.php\">Dependency Interface (DependencyInterface.php)<\/h2><pre><code class=\"language-php\">&lt;?phpinterface DependencyInterface { public function performAction();}<\/code><\/pre><h2 id=\"a-test-class-that-ends-up-testing-mocks-myclasstest.php\">A test class that ends up testing mocks (MyClassTest.php)<\/h2><pre><code class=\"language-php\">&lt;?phpuse PHPUnit\\Framework\\TestCase;class MyClassTest extends TestCase { public function testDoSomething() { \/\/ Creating a mock of the DependencyInterface. $dependencyMock = $this-&gt;createMock(DependencyInterface::class); \/\/ Setting up the mock to return a specific value. $dependencyMock-&gt;expects($this-&gt;once()) -&gt;method('performAction') -&gt;willReturn('Mocked result'); \/\/ Creating an instance of MyClass with the mock. $myClass = new MyClass($dependencyMock); \/\/ Calling the method to be tested. $result = $myClass-&gt;doSomething(); \/\/ Asserting that the result matches the expected value. $this-&gt;assertEquals('Result: Mocked result', $result); }}<\/code><\/pre><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>In this example, the test creates a mock for the <code>DependencyInterface<\/code> and sets up an expectation that the performAction method will be called once, returning a specific value.<\/p><p>The test then calls the <code>doSomething<\/code> method on <code>MyClass<\/code> and asserts that the result is as expected.<\/p><p>The issue with this test is that it's not testing the actual behaviour of <code>MyClass<\/code>.<\/p><p>It's only testing that the mock is configured correctly.<\/p><p>If the real implementation of <code>MyClass<\/code> has a bug, this test won't catch it.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Don&#039;t pre-optimise and over-customise",
"date": "1700006400",
"permalink": "/archive/2023/11/15/dont-pre-optimise-and-over-customise",
"text": "<p>I've been re-watching a livestream series from a few years ago, showing a SaaS product being built.<\/p><p>The series was created from two full-day live streams to create a minimum viable product (MVP) version of the application.<\/p><p>Several times, things like this were said:<\/p><ul><li>This will eventually need to be customisable.<\/li><li>When we have multiple users, but now we only have one.<\/li><li>Let's hard-code this for now and refactor it later.<\/li><li>This isn't pixel-perfect, but let's move on.<\/li><\/ul><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>As they focused on creating an MVP version, they added these things to a to-do list or wrote comments in the code to revisit it later rather than slowing down the initial development and pre-optimising the code for use cases that didn't exist yet.<\/p><p>If there's only one user, there's no need to write code to handle multiple users.<\/p><p>Later, once the application is launched, that feature can be added.<\/p><p>And, because they were writing automated tests, they'd be able to refactor and extend the code and not worry about breaking it as the tests would confirm that the functionality still worked.<\/p>",
"cta": "",
"tags": ["software-development","clean-code","automated-testing","test-driven-development"]
}, {
"title": "Why I prefer integration tests to unit tests",
"date": "1699920000",
"permalink": "/archive/2023/11/14/why-i-prefer-integration-tests-to-unit-tests",
"text": "<p>With unit tests, you need to mock <strong>everything<\/strong>.<\/p><p>If what you're testing has a dependency, you need to create and use a mock version.<\/p><p>If the mock has its own dependencies, you need to mock those, too.<\/p><p>I've written unit tests with mocks and accidentally only tested the mocks instead of the functionality I intended.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>With integration tests, you can use and test the real dependencies.<\/p><p>Whilst they may be slightly slower to run, I prefer the simpler setup, less need for mocks, and knowing the real services work - not just the mocked versions.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","mocking"]
}, {
"title": "PHPUnit does more than unit testing",
"date": "1699833600",
"permalink": "/archive/2023/11/13/phpunit-does-more-than-unit-testing",
"text": "<p>As the name suggests, <a href=\"http:\/\/phpunit.de\">PHPUnit<\/a> is a unit testing framework for PHP.<\/p><p>It's the defacto PHP testing framework used by the major PHP projects, such as Drupal, Symfony, Laravel.<\/p><p>But unit testing isn't all that PHPUnit can do.<\/p><p>These frameworks extend PHPUnit to give it more functionality.<\/p><p>Drupal allows you to run functional\/browser tests to make requests to pages, check the response codes and content, as well as integration\/kernel tests to test real services instead of relying on mocking within unit tests.<\/p><p>Symfony does the same with its web and kernel test cases.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>If you use a framework and want to more than unit testing, intsead of including another testing framework, try using some of the PHPUnit extensions that are provided by the framework.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","software-development","test-driven-development","phpunit","php","drupal","symfony"]
}, {
"title": "Drupal gives you so much out-of-the-box",
"date": "1699747200",
"permalink": "/archive/2023/11/12/drupal-gives-you-so-much-out-of-the-box",
"text": "<p>When you download and install Drupal, you get so much functionality available out-of-the-box.<\/p><p>For example:<\/p><ul><li>Content creation and editing capabilities with a flexible content type<\/li><li>A taxonomy system for categorising content.<\/li><li>Tools for managing editorial workflows.<\/li><li>User registration and authentication.<\/li><li>A role-based permission system.<\/li><li>Support for creating multilingual websites with translation tools.<\/li><li>Caching mechanisms to optimise performance.<\/li><li>Scalability features for handling high-traffic websites.<\/li><li>Built-in search functionality.<\/li><li>Robust security features, including input validation and output filtering.<\/li><li>RESTful web services for building web applications and mobile apps.<\/li><li>A flexible page and layout builder.<\/li><\/ul><p>There are over 50,000 contributed modules on Drupal.org that you can download to add functionality like eCommerce, analytics, social media integrations, quizzes, webforms and surveys.<\/p><p>You can add specific functionality by writing your own modules, and customise a project by creating a theme.<\/p><p>It's a great choice for a new web project.<\/p>",
"cta": "",
"tags": ["software-development","drupal"]
}, {
"title": "Work in small batches",
"date": "1699660800",
"permalink": "/archive/2023/11/11/work-in-small-batches",
"text": "<p>Software should be designed, written, and deployed in small batches.<\/p><p>This is the first line from a blog post by Eric Ries and is something that gets discussed with a guest in an upcoming episode of the Beyond Blocks podcast.<\/p><p>In the post, Eric continues by saying, \"Of all of the insights I've contributed to the companies I've worked at over the years, the one I am most proud of is the importance of working in small batches\".<\/p><p>Small batches mean faster feedback, more localised problems as there are fewer changes, and reduced risk and overhead.<\/p><p>If you work in small batches and make smaller changes, merge them regularly into the mainline branch (ideally, at least once a day), and often deploy changes to production, the releases will be quicker and less stressful, and clients and customers will be happy as their changes will be available sooner.<\/p><p>I've worked this way, and with long-lived feature branches and large, infrequent deployments, I prefer to work in small batches and deploy often.<\/p><p>The full blog post is found at <a href=\"http:\/\/www.startuplessonslearned.com\/2009\/02\/work-in-small-batches.html\">http:\/\/www.startuplessonslearned.com\/2009\/02\/work-in-small-batches.html<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","git","continuous-integration","continuous-delivery","continuous-deployment","trunk-based-development"]
}, {
"title": "Retrofit with Matt Glaman",
"date": "1699574400",
"permalink": "/archive/2023/11/10/retrofit-with-matt-glaman",
"text": "<p>Today, I released <a href=\"https:\/\/www.oliverdavies.uk\/podcast\/1-retrofit\">the first episode of the \"Beyond Blocks\" podcast<\/a>.<\/p><p>I spoke with Matt Glaman - Principal Software Engineer at Acquia and author of Retrofit.<\/p><p>Retrofit makes it easier to upgrade from Drupal 7 by adding compatibility layers to run your legacy code within Drupal 10 - giving you more time to port it to the modern approaches and standards.<\/p><p>I've been aware of Matt and his work for some time, including his work on Drupal Commerce, so it was great to speak with him and for him to be the first guest on the podcast.<\/p><p>Future episodes will be <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">published online<\/a> weekly, so feel free to subscribe and let me know if you have feedback, suggestions for future guests and topics, or want to be a guest.<\/p>",
"cta": "",
"tags": ["drupal","php","drupal-upgrades","podcast","beyond-blocks"]
}, {
"title": "README-driven development",
"date": "1699488000",
"permalink": "/archive/2023/11/09/readme-driven-development",
"text": "<p>As well as test-driven development (TDD), I also like README-driven development - a.k.a. documentation-driven development.<\/p><p>In short, you write the documentation first, followed by the code.<\/p><p>Like writing tests in TDD, it allows you to think about how your code will work, what functions and methods it will contain, how they'll interact together and how you expect people to use your code.<\/p><p>This can also contain flowcharts, diagrams, example code snippets and anything else that would be useful.<\/p><p>If you like, you could have a colleague review it in a pull\/merge request before progressing.<\/p><p>Once the README file is written and you're happy with its contents, you can start coding.<\/p><p>Also, documentation is commonly missed or skipped in projects, so moving it forward in the development process ensures it will be done and, as it's being written nearer to the writing of the code, it's more likely to be correct instead of writing it all once the code has been written.<\/p>",
"cta": "",
"tags": ["software-development","documentation"]
}, {
"title": "&quot;Building Build Configs&quot; at PHP South West",
"date": "1699401600",
"permalink": "/archive/2023/11/08/building-build-configs",
"text": "<p>This evening, I'm presenting a lightning talk at the PHP South West meetup in Bristol.<\/p><p>The talk is 'Building \"Build Configs\"' - a Symfony command-line tool I wrote (based on TheAltF4Stream's Rust version with the same name) that generates project-specific build configuration files.<\/p><p>Since creating it, I've used it for personal projects, projects for clients, and example projects on GitHub - such as <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal\">my Docker Example Drupal project<\/a>.<\/p><p>Having a set of standardised and configurable templates makes it much easier and quicker to start a new project, which I did when creating a <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal-commerce-kickstart\">Drupal Commerce Kickstart example<\/a> at DrupalCon.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/talks\/building-build-configs\">The slides are already online<\/a> and I've created <a href=\"https:\/\/www.oliverdavies.uk\/build-configs\">an example video<\/a> where I go from nothing to a ready-to-work-on Drupal website in less than a minute!<\/p><p>If you have any questions, hit reply and let me know!<\/p>",
"cta": "",
"tags": ["software-development","php","public-speaking"]
}, {
"title": "It depends",
"date": "1699315200",
"permalink": "/archive/2023/11/07/it-depends",
"text": "<p>Usually, in software development, there isn't always a definitive black-and-white answer to a question or situation.<\/p><p>Most of the time, the answer is \"it depends\".<\/p><p>How you approach a problem depends on context.<\/p><p>How long do you have?<\/p><p>Are you working on the final version or a prototype or minimum-viable product?<\/p><p>Should you use a contributed module or write one yourself?<\/p><p>What if an existing module hasn't been updated for some time or doesn't have tests or other quality checks included?<\/p><p>Do you write custom CSS or use a framework like Tailwind CSS or Bootstrap?<\/p><p>Should this project be written in this framework or CMS, or would a different one be better suited?<\/p><h2 id=\"here%27s-the-thing...\">Here's the thing...<\/h2><p>There are usually multiple approaches to achieve the same result.<\/p><p>Decisions will depend on a combination of various factors. In a different situation, the answer could be different.<\/p><p>This doesn't make any solution outright wrong.<\/p><p>It was right given the situation.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "The first Beyond Blocks podcast episode is recorded",
"date": "1699228800",
"permalink": "/archive/2023/11/06/the-first-beyond-blocks-podcast-episode-is-recorded",
"text": "<p>For my first time in the podcast host chair, I interviewed Matt Glaman - Principal Software Engineer at Acquia.<\/p><p>I initially knew Matt from his work on Drupal Commerce, but I wanted to learn about his new project, Retrofit - a tool to make it easier to upgrade from Drupal 7 (which will be end of life in January 2025) to Drupal 10.<\/p><p>We also talked briefly about PHPStan Drupal and drupal-check, which are some of Matt's other projects and contributions to the Drupal community.<\/p><p>Thank you, Matt, for being the first guest on the Beyond Blocks podcast.<\/p><p>I have other guests booked for this week, so the episode with Matt will be <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">published soon<\/a>.<\/p>",
"cta": "",
"tags": ["software-development","podcast","drupal","php"]
}, {
"title": "I&#039;m starting a podcast",
"date": "1699142400",
"permalink": "/archive/2023/11/05/i-m-starting-a-podcast",
"text": "<p>This week, I'm starting my own podcast - <a href=\"https:\/\/www.oliverdavies.uk\/podcast\">Beyond Blocks<\/a>.<\/p><p>I'll be interviewing different people in every week, focussing on Drupal and related software development topics.<\/p><p>I have the first guests lined up, including some speakers from last month's DrupalCon Europe conference, where we can discuss their topics in more detail.<\/p><p>If you'd like to be a guest, <a href=\"https:\/\/forms.gle\/wdVqmEyQSWUx8cnm8\">get in touch<\/a> and let me know what you'd like to discuss.<\/p>",
"cta": "",
"tags": ["software-development","podcast"]
}, {
"title": "Why you should contribute to open-source software",
"date": "1699056000",
"permalink": "/archive/2023/11/04/why-you-should-contribute-to-open-source-software",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/11\/03\/why-your-company-should-contribute-to-open-source-software\">Yesterday's email<\/a> explained why your company should contribute to open-source software, but why should you contribute as an individual?<\/p><p>Most of the same reasons apply, such as gaining experience and improved knowledge from contributing.<\/p><p>As an individual, you can build your own reputation and personal brand.<\/p><p>You'll get exposure from contributions and involvement with initiatives, such as the Drupal admin UI improvements and other core initiatives, which look great on your CV and LinkedIn profile.<\/p><p>This could lead to better career opportunities and potential projects.<\/p><p>I've had paid development work directly from my open-source code contributions, as well as public speaking and event organising, so I can vouch for this.<\/p><p>Like companies, if you make money from open-source software - either a salary or from paid projects or courses - it's in your interest to contribute so the software you use is maintained and improved so it's the best it can be.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "Why your company should contribute to open-source software",
"date": "1698969600",
"permalink": "/archive/2023/11/03/why-your-company-should-contribute-to-open-source-software",
"text": "<p>I've always thought companies should contribute to open-source software.<\/p><p>Whether it's financial or contributing time, if companies use free, open-source software (and especially if they're directly making money from it).<\/p><p>Contributing to the software you use will improve the software, whether adding new features, fixing a bug, or contributing translations.<\/p><p>Having contributors to the software is a great way to differentiate your company from the competition, and the knowledge gained from contributing will result in better code for your projects.<\/p><p>If you organise or sponsor events such as conferences and meetups, you also get exposure from the event and help support the event and community.<\/p><h2 id=\"here%27s-the-thing...\">Here's the thing...<\/h2><p>I've recently pledged to donate a percentage of income from Drupal-related services to the Drupal Association and would like to see others do the same if they can.<\/p><p>I also sponsor several individuals and organisations on GitHub who build software and create content I use so I get better tools and knowledge for myself and my projects.<\/p><p>If your company can contribute to open-source, I'd encourage them to do so and help support open-source software projects and communities.<\/p>",
"cta": "",
"tags": ["software-development","open-source"]
}, {
"title": "Is code coverage an objective or guideline?",
"date": "1698883200",
"permalink": "/archive/2023/11/02/is-code-coverage-an-objective-or-guideline",
"text": "<p>Many development teams and projects use code coverage - e.g. how many lines of code are covered by automated tests - as an objective, and saying it must be 100% or another percentage.<\/p><p>But is this an effective metric?<\/p><p>In the same way as deleting failing tests to fix a pipeline, a code coverage amount can be faked.<\/p><p>With this in mind, what if, instead of setting an objective such as 100% code coverage, you used it as a guideline?<\/p><p>If you're working on a legacy project, what if you set a minimum code coverage amount as a guideline to ensure any new code has tests by not dropping under that level?<\/p><p>Would that be better than saying every line of code needs to be covered?<\/p><p>Code coverage is something I'm thinking of using more, so I want to know what you think.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Drupal 9 is now end of life",
"date": "1698796800",
"permalink": "/archive/2023/11/01/drupal-9-is-now-end-of-life",
"text": "<p>As of today, Drupal 9 is end-of-life and no longer supported.<\/p><h2 id=\"why%3F\">Why?<\/h2><p>Drupal 9 relies on several other software projects, including Symfony, CKEditor, and Twig.<\/p><p>With Symfony 4's end of life, CKEditor 4's end of life, and Twig 2's end of life all coming up soon, Drupal 9 went end of life on November 1st, 2023.<\/p><h2 id=\"what-do-i-do-next%3F\">What do I do next?<\/h2><p>There will be no further releases of Drupal 9 so you need to upgrade.<\/p><p>If you're stuck on Drupal 9, 8, or 7, get unstuck with a <a href=\"https:\/\/www.oliverdavies.uk\/drupal-upgrade\">Drupal upgrade roadmap<\/a> and get directions how to upgrade to Drupal 10.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "One official Drupal development environment?",
"date": "1698710400",
"permalink": "/archive/2023/10/31/one-official-drupal-development-environment",
"text": "<p>Yesterday, I read <a href=\"https:\/\/kevinquillen.com\/ddev-being-considered-official-drupal-development-environment\">a post by Kevin Quillen<\/a> titled 'DDEV being considered as the \"official\" Drupal development environment'.<\/p><p>I've been a DDEV user, and I've also used most, if not all, of the other popular Drupal development environments.<\/p><p>These days, I use <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/21\/2022-08-21\">my own Docker Compose-based setup<\/a>, but I feel having an official development environment would be an excellent move for the Drupal community and project - and for new Drupal users, evaluators and contributors in particular.<\/p><p>Anything that lowers the barrier to using or contributing to Drupal is a good thing and allows for more focused documentation and a simpler onboarding experience, similar to what other projects have - such as Laravel with Homestead, Valet and now, Sail.<\/p><h2 id=\"collaboration-is-key\">Collaboration is key<\/h2><p>Instead of multiple similar projects creating the same features and fixing the same issues, there could be an opportunity to collaborate or even combine projects and resources in the future.<\/p><h2 id=\"but-what-about-existing-teams-and-projects%3F\">But what about existing teams and projects?<\/h2><p>If your company or team already uses another option, you can continue to use it.<\/p><p>If you have an existing solution, I don't think it will be removed or abandoned in the near future.<\/p><p>But, for new Drupal users and teams, one official development environment would be a big plus.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Is Drupal a CMS or a framework?",
"date": "1698624000",
"permalink": "/archive/2023/10/30/is-drupal-a-cms-or-a-framework",
"text": "<p>Drupal is typically called a CMS (content management system) - somewhere you add and edit the content for your website.<\/p><p>However, unlike some other CMSes, unless a Drupal website uses only the default page and article content type, no Drupal websites are the same. Each will have its specific content model with different content types and fields.<\/p><p>Instead of being a content management system, Drupal can be described as a content management framework (CMF) - a framework for building a content management system specific to each application.<\/p><p>But as well as a content management framework, Drupal could also be considered an application framework like Symfony or Laravel.<\/p><p>As well as building the content model, you can extend Drupal's functionality with custom modules and add custom themes to make it visually different.<\/p><p>But, there's a lot of functionality in Drupal core itself - such as user accounts, authentication, a query builder (Views), JSON:API endpoints, and a visual page editor (Layout Builder) - to name a few things!<\/p><p>Drupal offers much more than just managing content.<\/p>",
"cta": "",
"tags": ["php","phpc","drupal"]
}, {
"title": "I can drive my car blindfolded, but is it a good idea?",
"date": "1698537600",
"permalink": "/archive/2023/10/29/i-can-drive-my-car-blindfolded-but-is-it-a-good-idea",
"text": "<p>After sending <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/10\/28\/can-you-move-faster-without-tests\">yesterday's email<\/a>, Dave Hall replied <a href=\"https:\/\/www.linkedin.com\/feed\/update\/urn:li:activity:7124401304315027456\">with a LinkedIn comment<\/a> I liked and wanted to share (done with permission):<\/p><blockquote> <p>In theory I can drive my car on the motorway, blind folded while not wearing a seat belt. It sounds really exciting and loads of fun. When something goes wrong it gets really messy.<\/p> <p>I tend to think of skipping automated tests in the same way.<\/p><\/blockquote><p>Just because you can do something, it doesn't mean you should.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Can you move faster without tests?",
"date": "1698451200",
"permalink": "/archive/2023/10/28/can-you-move-faster-without-tests",
"text": "<p>If you don't write automated tests or do test-driven development, you might move quickly to begin with - writing code and doing small amounts of manual testing.<\/p><p>But, once you start changing the code to add new features or fix bugs, things will begin to slow down.<\/p><p>You'll have more to test and need to ensure you don't break the existing functionality as well as your new code works.<\/p><p>Whilst it may be faster initially, skipping tests will cause problems later.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Work with me and support the Drupal Association",
"date": "1698364800",
"permalink": "/archive/2023/10/27/work-with-me-and-support-the-drupal-association",
"text": "<p>I used to work for the <a href=\"https:\/\/www.drupal.org\/association\">Drupal Association<\/a> - the non-profit organisation that supports the Drupal project, organises DrupalCon, and maintains Drupal.org.<\/p><p>I improved Drupal.org, fixed Drupal 8 release blockers, improved user profiles, helped make the Drupal.org theme responsive, and assisted with new websites like Drupal Events and Jobs.<\/p><p>At DrupalCon, one of the keynote speakers said, \"The Drupal Association is a small but mighty team\".<\/p><p>On the <a href=\"https:\/\/www.drupal.org\/association\/staff\">Association staff page<\/a>, there are 15 staff members listed, including only five people in the Engineering team.<\/p><p>I've been in the Drupal community for a long time and worked for various companies that make money from Drupal - a free and open-source project.<\/p><p>However, it's \"free as in puppies\". You can have the puppy for free, but it costs time and money to look after it.<\/p><p>There are programs like the Supporting Partners program which provide funding to the DA, but, at least when I worked there, a large amount of income was from event revenue from DrupalCon.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>As someone who works mainly on Drupal consulting and development projects, I'm pledging to commit a fixed percentage from my Drupal-related services and products to the Drupal Association, including my new <a href=\"https:\/\/www.oliverdavies.uk\/team-coaching\">team coaching<\/a> service.<\/p><p>If the Association or Drupal weren't there, I wouldn't be able to provide those products and services, so it's in my interest to support the Drupal project and the Drupal Association. Maybe others will do the same.<\/p><p><strong>Work with me and support the Drupal Association.<\/strong><\/p>",
"cta": "",
"tags": ["drupal","open-source","php","phpc"]
}, {
"title": "Is decoupled Drupal still a thing?",
"date": "1698278400",
"permalink": "/archive/2023/10/26/is-decoupled-drupal-still-a-thing",
"text": "<p>A few years ago, decoupled or headless Drupal - where Drupal is used as an API with a separate front-end - was very popular with some large Drupal agencies and clients using it.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/talks\/decoupling-drupal-vuejs\">I gave a conference talk<\/a> about how to use Drupal as a backend application for a Vue.js frontend.<\/p><p>Recently, though, I haven't heard much about it.<\/p><p>Some previous advocates have moved back to the more traditional approach.<\/p><p>Interestingly, though, I did hear quite a bit about it at DrupalCon and about Drupal and Next.js in particular.<\/p><p>I want to try using Drupal with Astro in the future and see what the landscape is like now.<\/p><h2 id=\"what-about-you%3F\">What about you?<\/h2><p>Do you use Drupal in a decoupled or headless way? If so, what do you use for the frontend?<\/p><p>If not, or if you've moved back to a more traditional approach, why?<\/p><p>Reply and let me know.<\/p>",
"cta": "",
"tags": ["software-development","drupal","decoupled-drupal","vuejs"]
}, {
"title": "Automated tests prevent regressions when upgrading",
"date": "1698192000",
"permalink": "/archive/2023/10/25/automated-tests-prevent-regressions-when-upgrading",
"text": "<p>With Drupal 9 almost being end-of-life and unsupported, I've recently been doing a lot of Drupal 9 to 10 upgrade work.<\/p><p>As it's a major version update, there are breaking changes that mean you may need to change your code.<\/p><p>Here's an example of an error caused by a breaking change:<\/p><blockquote> <p>Drupal\\Core\\Entity\\Query\\QueryException: Entity queries must explicitly set whether the query should be access checked or not. See Drupal\\Core\\Entity\\Query\\QueryInterface::accessCheck().<\/p><\/blockquote><p>To fix this, you need to call the <code>accessCheck()<\/code> method before executing a query and specify whether it should be checked.<\/p><p>But how do you know if it should be checked?<\/p><p>If you have automated tests that pass beforehand and still pass afterwards, you picked the correct option.<\/p><p>If the test passes before and fails afterwards, you found the bug and can fix it immediately to ensure the functionality works as before.<\/p>",
"cta": "",
"tags": ["software-development","php","drupal","automated-testing","test-driven-development"]
}, {
"title": "How to test code you didn&#039;t write",
"date": "1698105600",
"permalink": "/archive/2023/10/24/how-to-test-code-you-didnt-write",
"text": "<p>I was also asked at DrupalCon how you write tests for code you didn't write and how you cover all of the use cases and scenarios.<\/p><p>This is tricky. If you didn't write the code, how can you know all the scenarios you need to test?<\/p><p>Presumably, there is some documentation, Jira tickets, user stories or acceptance criteria from when the code was written that will help you with this.<\/p><p>Decide the most critical functionality to be tested and focus on that, as that will provide the most value.<\/p><p>I'd start with functional tests and test for high-level outcomes, such as whether a page loads, returns the correct status code, and contains the expected text.<\/p><p>Then, iteratively add more tests for other scenarios. Once you have the first one written, this should be easier as you already have the setup steps, such as which modules must be enabled and what configuration needs to be installed.<\/p><p><strong>One test is better than none.<\/strong><\/p><p>If you need to add any new features or fixes, ensure they have their own tests to keep a consistent level of coverage.<\/p><p>Even with a simple module, you're unlikely to be able to identify all of the scenarios, write all the tests in one go, and have everything covered.<\/p><p>Start with the most important test first and continue to add more iteratively.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "When should you run your tests?",
"date": "1698019200",
"permalink": "/archive/2023/10/23/when-should-run-your-tests",
"text": "<p>After my talk at DrupalCon, I was asked when you should run your tests.<\/p><p>Of course, if you're doing test-driven development, you have to run the tests as you work on them and have the red, green, refactor cycle as you work on the feature or bug fix.<\/p><p>If you're not doing TDD, I'd recommend running the whole test suite before you push your code to know it works before a peer review or to an environment for quality assurance or user-acceptance testing.<\/p><h2 id=\"what-about-ci-pipelines%3F\">What about CI pipelines?<\/h2><p>As well as running tests manually, I'd add them to a CI pipeline, such as GitHub Actions, GitLab CI or Bitbucket Pipelines.<\/p><p>There, tasks can be run automatically each time a commit is pushed, so you don't need to rely on them being run manually.<\/p><p>If you're doing trunk-based development, you want the CI pipeline to run on every push to prevent regressions and ensure the tests continue to pass.<\/p><p>If you're working with feature branches and doing code review, run the tests as part of the merge or pull request so you know everything works as expected before the code is reviewed.<\/p><p>This answers the main \"Does it work?\" question, and allows the reviewer to focus on reviewing the code and suggesting improvements.<\/p><p>If the CI pipeline in the merge or pull request fails, it needs to be fixed before submitting it for review as there's no need to review the code before it changes to fix the pipeline.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Off to DrupalCon",
"date": "1697328000",
"permalink": "/archive/2023/10/15/off-to-drupalcon",
"text": "<p>This week, I'll be in Lille, France for DrupalCon Europe, where I'm presenting a session on automated testing and test-driven development in Drupal.<\/p><p>I'll be taking a short break from these emails to enjoy the conference, focus on my talk, and finish my <a href=\"https:\/\/www.oliverdavies.uk\/atdc\">free email course on automated testing in Drupal<\/a>.<\/p>",
"cta": "",
"tags": ["drupal","drupalcon"]
}, {
"title": "Do you need to write tests for small or short-lived projects?",
"date": "1697241600",
"permalink": "/archive/2023/10/14/do-you-need-to-write-tests-for-small-or-short-lived-projects",
"text": "<p>When does it make sense not to write automated tests?<\/p><p>Tests prevent regressions in codebases that are changed and updated over time.<\/p><p>So, if you're working on a short-term project, such as a marketing campaign website that will only be live for a few months, you won't get as much benefit from having tests, especially if you may not even change it once it's live.<\/p><p>Likewise, tests are useful for projects on which you want to avoid downtime and outages, especially if you sell products via your website or it contains important information. For other websites, such as personal blogs, that are less critical, testing may be less beneficial.<\/p><p>Also, one of Drupal's key benefits is that you can build websites within the Drupal UI, without needing to write custom code.<\/p><p>If you're going down this route, there is no custom code to test and a separate tool that checks URLs exist and returns the correct response code would be a better fit.<\/p><p>If you then need to add any custom code and functionality, you may want to add tests.<\/p><p>Whilst there are some situations where not writing tests is reasonable, there are more reasons and situations when you should, compared to not.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Writing tests is an investment",
"date": "1697155200",
"permalink": "/archive/2023/10/13/writing-tests-is-an-investment",
"text": "<p>It can take time to write automated tests and do test-driven development, but it is an investment in a project's future stability.<\/p><p>Spending time to write tests upfront will save time as the project progresses, make the code easier to change, and result in better software, fewer bugs, and quicker changes.<\/p><p>Even though it takes time, it's time well spent.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Business logic in template files?",
"date": "1697068800",
"permalink": "/archive/2023/10/12/business-logic-in-template-files",
"text": "<p>I've often heard and advocated for not \"putting logic\" in template files and having a separation of concerns.<\/p><p>The templates should be as simple to read and change as possible, and any complicated logic should be moved elsewhere.<\/p><p>There can be presentational logic - such as a simple if condition to determine if a value should be shown or looping over a list of items, but business logic should be within custom code - ideally within Service, Action or Command classes - and injected into the templates.<\/p><p>As well as making the templates simpler and cleaner, this logic can be tested separately with automated tests to ensure it works as expected. If the logic is within a template, this can be done for some things using Functional tests, such as whether some text appears on a page, but testing whether it appears in a certain order, for example, is much harder. This is best done within kernel or unit tests.<\/p><p>As well as being more testable, extracting the logic from a template makes it more reusable. You can use a service from multiple places within your website without duplicating it, making your website code smaller and easier to maintain.<\/p>",
"cta": "",
"tags": ["software-development","drupal","twig","automated-testing"]
}, {
"title": "Do you need that module?",
"date": "1696982400",
"permalink": "/archive/2023/10/11/do-you-need-that-module",
"text": "<p>Drupal includes a lot of default functionality and additional core modules you can enable to extend it.<\/p><p>There are also over 50,000 community-contributed modules you can download and add.<\/p><p>But is it worth adding every module?<\/p><p>If you're browsing the list of modules on Drupal.org and find one of interest, is the functionality it adds more valuable than the cost of maintaining it?<\/p><p>Each module increases the number of updates you'll need to do to maintain the website.<\/p><p>What if it becomes unmaintained in the future and prevents you from updating your website to the next version of Drupal or has a security issue and introduces a vulnerability?<\/p><p>Some modules will be crucial to your website, others you can do without if you prefer a smaller maintenance overhead.<\/p>",
"cta": "",
"tags": ["software-development","drupal","php"]
}, {
"title": "Why use Composer to manage Drupal dependencies?",
"date": "1696896000",
"permalink": "/archive/2023/10/10/why-use-composer-to-manage-drupal-dependencies",
"text": "<p>One of the initial negatives when Drupal 8 launched was introducing Composer, PHP's dependency manager, and how it could affect non-technical users.<\/p><p>When I started doing Drupal, I downloaded the .tar.gz or .zip file of Drupal, extracted it, and placed it within my project.<\/p><p>I did the same for any additional modules I needed.<\/p><p>To update them, I needed to delete my files and repeat the process of downloading and replacing them.<\/p><h2 id=\"drush\">Drush<\/h2><p>Then, instead of doing it manually, I used Drush, the \"Drupal shell\", to download the files. This saved some time, but it still has down-sides.<\/p><p>What if you needed to install a module like Pathauto, which has dependencies you also need to download and install?<\/p><p>With Drush or downloading the files manually, you'd need to download the dependencies separately.<\/p><h2 id=\"composer\">Composer<\/h2><p>Composer is a dependency manager, which means it can handle these dependencies for us.<\/p><p>It looks at each project's <code>composer.json<\/code> file to find its dependencies and downloads them.<\/p><p>For example, to install Pathauto, you run <code>composer require drupal\/pathauto<\/code>.<\/p><p>Within its output, you'll see this:<\/p><pre><code class=\"language-plain\">Package operations: 3 installs, 0 updates, 0 removals - Downloading drupal\/token (1.12.0) - Downloading drupal\/ctools (4.0.4) - Downloading drupal\/pathauto (1.12.0)<\/code><\/pre><p>As well as Pathauto, it's downloading its dependencies - ctools and pathauto.<\/p><p>Instead of downloading three modules, we can do it with one command.<\/p><p>In fact, we don't need to know what its dependencies are - Composer will do that.<\/p><p>Also, updating the modules is just another simple command - <code>composer update<\/code>.<\/p><p>While it may be intimidating to non-technical users, learning a few simple commands makes installing and updating modules much easier!<\/p>",
"cta": "",
"tags": ["software-development","drupal","php","phpc","composer"]
}, {
"title": "Spotting new things in Drupal 10.1",
"date": "1696809600",
"permalink": "/archive/2023/10/09/spotting-new-things-in-drupal-10-1",
"text": "<p>I've recently updated my <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal\">Drupal Docker example project<\/a> to Drupal 10.1.5 and have been spotting new things.<\/p><p>From British English as my default option during installation, UX improvements to the admin pages, and developer settings such as Twig caching being configurable in the admin UI.<\/p><p>Something I've loved since Drupal 8 is the constant new features and iterative improvements being added to Drupal core.<\/p><p>I'm looking forward to finding more of these as I keep upgrading my Docker example project as well as others.<\/p>",
"cta": "",
"tags": ["php","drupal"]
}, {
"title": "Is test-driven development difficult?",
"date": "1696723200",
"permalink": "/archive/2023/10/08/is-test-driven-development-difficult",
"text": "<p>I recently read a post where the writer said automated testing, test-driven development, continuous integration, trunk-based development, etc, are difficult.<\/p><p>I'm familiar with them and have been using them for some time, but I think trunk-based development is easier as there's only a single branch instead of many.<\/p><p>Continuous integration is\u00a0pulling everyone else's code at least once daily and pushing yours to ensure it doesn't conflict.<\/p><p>Test-driven development is writing failing tests before any implementation code and refactoring once it passes.<\/p><p>I don't think these are technically difficult, but they do require an open mind, a willingness to learn, evaluate and consider alternative approaches and, in some cases, change existing behaviour.<\/p><p>Change can be the difficult part, not which brand you commit to, how often you push your code or when you write your tests.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","continuous-integration","trunk-based-development"]
}, {
"title": "A breakdown of tests from a current project",
"date": "1696636800",
"permalink": "/archive/2023/10/07/a-breakdown-of-tests-from-a-current-project",
"text": "<p>I've just added the hundredth test to a client project I'm developing.<\/p><p>I'm following <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/09\/14\/outside-in-or-inside-out\">the outside-in approach<\/a>, starting with functional tests and moving to kernel and unit tests where needed - meaning more functional tests and fewer unit tests - most of which cover some complex search functionality containing custom blocks, forms, endpoints for autocomplete lists, pattern matching and results pages, which is the core functionality of the project.<\/p><p>Here's the breakdown of the different types of tests:<\/p><ul><li>Functional - 57 tests, 180 assertions<\/li><li>Kernel - 38 tests, 495 assertions<\/li><li>Unit - 5 tests, 18 assertions<\/li><\/ul><p>The tests are run automatically in a CI pipeline by GitHub Actions and Docker and usually run in two or three minutes.<\/p><p>The project is still in progress, so I'll add more tests for the remaining functionality and possibly remove some too, as I refactor some of the code.<\/p><hr \/><p>P.S. Are you interested in automated testing and test-driven development? I'm speaking about it at DrupalCon Europe on the 17th of October!<\/p><p>You can also pre-register for my free 10-day automated testing email course at https:\/\/opdavi.es\/testing-email-course.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Software development is like going to the Dentist",
"date": "1696550400",
"permalink": "/archive/2023/10/06/software-development-is-like-going-to-the-dentist",
"text": "<p>Working on software development tasks is like going to the Dentist.<\/p><p>Releasing new features, bug fixes, dependency updates, and refactoring is better and less painful when done regularly.<\/p><p>Doing these changes in small and regular batches is less risky than less frequent and larger releases.<\/p><p>It's easier to identify the cause of any issues and correct course if things aren't going to plan.<\/p>",
"cta": "",
"tags": ["software-development","refactoring","deployments"]
}, {
"title": "Some solutions are good enough",
"date": "1696464000",
"permalink": "/archive/2023/10/05/some-solutions-are-good-enough",
"text": "<p>Once you have a passing test and you're confident your code works as expected, what do you do next?<\/p><p>Do you keep refactoring and changing it, or is it good enough?<\/p><p>Do you need to extract additional classes and methods now, or as the test is passing, do you move on to the next task?<\/p><p>The main objective is to ship the change and for it to provide value to users, not to have a perfect or \"gold-plated\" solution.<\/p><p>Once it's shipped, because you have tests, you can confidently refactor it in the future.<\/p>",
"cta": "",
"tags": ["software-development","technical-debt"]
}, {
"title": "The best solution is the one that gets the tests to pass",
"date": "1696377600",
"permalink": "/archive/2023/10/04/the-best-solution-is-the-one-that-gets-the-tests-to-pass",
"text": "<p>As I said yesterday, there is no perfect solution or approach for every situation.<\/p><p>However, when doing test-driven development, there is a best solution.<\/p><p>The simplest thing that gets a failing test to pass.<\/p><p>Whether it's hard-coding a return value or putting the initial logic in a Controller, that's the objective.<\/p><p>Once the test is passing, you can refactor the code or continue writing tests, which will each have their own best solution.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "There is no perfect solution",
"date": "1696291200",
"permalink": "/archive/2023/10/03/there-is-no-perfect-solution",
"text": "<p>Something I've said recently when mentoring bootcamp students and working with Junior Developers is that there isn't a perfect solution to each problem, and there are multiple ways to achieve the same result.<\/p><p>Similarly, there isn't a perfect tool for every situation.<\/p><p>You can use different tools and get the same outcome.<\/p><p>In some of my early emails, I talked about <code>run<\/code> files and <code>just<\/code> - two ways to write project-specific commands or aliases that simplify complex commands or group multiple commands together.<\/p><p>Both do the same thing, but each have pros and cons.<\/p><p><code>run<\/code> files are files written in Bash, which are more verbose but can run anywhere.<\/p><p>just is its own program that needs to be installed for it to be available, so Developers will need to have it installed, and it will need to be added to a CI pipeline to be available.<\/p><p>I've had CI pipelines fail because they can't download just, and not because of anything in the application code.<\/p><p>I like the simplicity of justfiles, though, and that the files are simpler.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>If there isn't a perfect solution, approach, or tool, it comes down to the pros and cons of each. Which option is best for you, your project, or your team?<\/p><p>There isn't a \"one size fits all\" solution that works for everyone all the time.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Only comment what needs to be commented",
"date": "1696204800",
"permalink": "/archive/2023/10/02/only-comment-what-needs-to-be-commented",
"text": "<p>\"If you comment everything, people won't read them.\"<\/p><p>\"As soon as one comment is incorrect, the result will be ignored.\"<\/p><p>These are two comments I heard recently referring to code comments.<\/p><p>If there are too many comments, people will get lost in the information. They won't be able to differentiate boilerplate comments from valuable ones, and as soon as one comment is incorrect, people will assume that others could likely be incorrect too and ignore them.<\/p><p>A solution to these is to only comment what needs to be commented.<\/p><p>Only write comments that add value, and if there are fewer comments, they are easier to read and maintain - making it more likely they will be incorrect.<\/p><p>This is an example from an open source pull request:<\/p><pre><code class=\"language-php\">\/** * An interface for field access override. *\/interface FieldAccessOverrideInterface {<\/code><\/pre><p>In my opinion, this doesn't add any value or additional context as it repeats what's already there.<\/p><p>Something I put in my project configuration files is to tweak the coding standards to not check, for example, for class and method docblocks - allowing me to add them where I want and where I think they're needed and add value.<\/p><p>I think this is better than having comments everywhere, and I can focus on the ones that matter.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "TDD: repeat and refactor",
"date": "1696118400",
"permalink": "/archive/2023/10/01/tdd--repeat-and-refactor",
"text": "<p>With test-driven development, you start with a failing test and focus on getting it to pass.<\/p><p>But what do you do once it's passing?<\/p><p>You either repeat the process, adding more assertions to the same test until you generate the next failure or write the next failing test, or take the opportunity to refactor the code.<\/p><p>Is there something you'd like to change within the implementation or test code? You can do that whilst the tests are passing.<\/p><p>You may want to extract a new class or method to improve the implementation or create some test helpers to reduce duplication within the tests.<\/p><p>You just need to keep the tests passing to ensure the code still works. If something breaks, you fix it as soon as possible, either by fixing the code or reverting to the previously passing code.<\/p><p>Then, once you've completed the refactoring, move back into the red\/green phase with the next test failure.<\/p>",
"cta": "",
"tags": ["automated-testing","software-development","test-driven-development","refactoring"]
}, {
"title": "Automated testing offers repeatability",
"date": "1696032000",
"permalink": "/archive/2023/09/30/automated-testing-offers-repeatability",
"text": "<p>You work on feature or bug fix.<\/p><p>It gets tested manually by you, a tester, and the person who requested the feature or reported the bug.<\/p><p>It may get tested on multiple environments.<\/p><p>It passes and it moved to production.<\/p><p>But now it's live, it's not tested again.<\/p><p>Although it works now, there's no guarantee it's not broken or regressed by subsequent changes.<\/p><p>It's definitely not tested manually before every future release.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Automated testing offers repeatability.<\/p><p>The tests pass, so the functionality works when you wrote it, and you can re-check it by re-running the test.<\/p><p>The test suite can be run by Developers whilst working on other changes, before code review and before deployments.<\/p><p>The test suite can be run automatically in a CI pipeline for every change that's pushed, and you'll know your change not only worked at the time but will continue to work.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "92 changed files with 885 additions and 156 deletions",
"date": "1695945600",
"permalink": "/archive/2023/09/29/92-changed-files-with-885-additions-and-156-deletions",
"text": "<p>Today, I refactored some code on a client's Drupal project I've been working on.<\/p><p>This is what the commit says:<\/p><blockquote> <p>Showing 92 changed files with 885 additions and 156 deletions<\/p><\/blockquote><p>So, it's not a small refactor.<\/p><p>As I worked on the custom modules needed for the site, I noticed that some common functionality was spread over multiple modules. This refactor moved that functionality into its own module, which is now a dependency of the others.<\/p><p>The code is better, and the responsibilities of the modules are clearer.<\/p><p>Whilst a large amount of those additions are adding test modules with test configuration, it's not a small refactor.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>This is what it says at the bottom of the CI pipeline output:<\/p><blockquote> <p>OK (79 tests, 565 assertions)<\/p><\/blockquote><p>This is the same number of passing tests and assertions I had before I started the refactor, so I know the functionality still works.<\/p><p>If I didn't have those tests, I wouldn't have done the refactor.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","refactoring"]
}, {
"title": "Feature flags enable continuous integration",
"date": "1695859200",
"permalink": "/archive/2023/09/28/feature-flags-enable-continuous-integration",
"text": "<p>I was recently working on a feature over a few mob programming sessions.<\/p><p>After the session, we implemented part of the feature but couldn't merge it as it wasn't complete.<\/p><p>After working on other things that day, I'd need to rebase my local commits and push the last-but-one commit to the remote repository to keep the incomplete feature only in my local repository (I forgot a few times and almost pushed it accidentally).<\/p><p>The commit prevented me from following continuous integration - where everyone commits and pushes their code a minimum of once daily.<\/p><p>What if someone else wanted to look at that code between mob sessions? They couldn't, as it was only on my laptop.<\/p><p>If I'd made a temporary branch, it would be outdated and behind other changes to our mainline branch.<\/p><h2 id=\"feature-flags-to-the-rescue\">Feature flags to the rescue<\/h2><p>As this commit was part of a larger change, it couldn't be merged, so we added a feature flag around it.<\/p><p>The values were set to null and hidden by default, and populated by the new changes and displayed if the flag was enabled.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>This meant we could safely push the commit, make the changes available to everyone and enable the feature on the environments we wanted - preventing it from showing on production.<\/p><p>This allowed us to get back to our usual working practices, and I didn't need to worry about accidentally pushing the commit and prematurely showing our changes in production.<\/p>",
"cta": "",
"tags": ["software-development","git","continuous-integration","feature-flags"]
}, {
"title": "Separating environments with feature flags",
"date": "1695772800",
"permalink": "/archive/2023/09/27/separating-environments-with-feature-flags",
"text": "<p>You have two or more environments and versions of your application, but you do trunk-based development, so you only have a single branch that you use on all environments.<\/p><p>But if all environments have the same code, how can we have differences between them?<\/p><p>What if we want a feature enabled on one environment and not the other?<\/p><h2 id=\"feature-flags\">Feature flags<\/h2><p>Feature flags are an approach I've previously written about. You have two branches of logic within your code, and the flow changes based on whether a flag is enabled.<\/p><p>If a flag is enabled, execute the first block of code. Otherwise, execute the second.<\/p><p>Now, you enable and disable the required feature flags for each environment.<\/p><p><strong>The code is the same for all environments, but the enabled features and functionality are different.<\/strong><\/p><p>Then, once the feature has been deployed and released in production, the feature flag can be removed.<\/p>",
"cta": "",
"tags": ["software-development","feature-flags"]
}, {
"title": "Which branch should be in which environment?",
"date": "1695686400",
"permalink": "/archive/2023/09/26/which-branch-should-be-in-which-environment",
"text": "<p>A common question is which [Git] branch should be on which environment.<\/p><p>Most projects I've worked on have two or more environments: production, staging (or test) and development.<\/p><p>Earlier in my career, we used Git Flow heavily. A Git branching workflow based on having different branches - i.e. <code>develop<\/code>, <code>master<\/code> and any arbitrary short-lived feature, hotfix and release branches.<\/p><p>These matched nicely with our three environments.<\/p><p>Usually, the <code>develop<\/code> branch would be used in the development environment. The <code>master<\/code> branch would be on staging and a tagged release from <code>master<\/code> on production.<\/p><h2 id=\"what-about-now%3F\">What about now?<\/h2><p>I prefer trunk-based development, where there is one long-lived branch to which everyone commits their changes.<\/p><p>There's only one branch, so you can either follow continuous deployment and use the same branch for all environments - including production - or separate production using a dedicated branch or tag if you need more control.<\/p><p>The mainline branch is used in all pre-production environments, such as staging and development.<\/p><h2 id=\"what-about-differences-between-the-environments%3F\">What about differences between the environments?<\/h2><p>What if we need differences, such as a feature that must be enabled in a particular environment if the same code is on both?<\/p><p>My go-to approach is feature flagging, and this approach is something I'll describe more in tomorrow's email.<\/p>",
"cta": "",
"tags": ["software-development","git","trunk-based-development","feature-flags"]
}, {
"title": "Should you use a staging environment?",
"date": "1695600000",
"permalink": "/archive/2023/09/25/should-you-use-a-staging-environment",
"text": "<p>The purpose of any pre-production version of your website or application (any version that isn't the public live one) is to mimic the production version and as a test run for deployments.<\/p><p><strong>If I deploy this feature, will it break the website?<\/strong><\/p><p>The issue with most staging and other pre-production environments is that they differ from what's on production. It may have been some time since the latest data was added, and its value is only as good as how close to production it is and how likely it is to find potential issues in production.<\/p><p>If they differ greatly, the staging environment offers no value.<\/p><p>It's not a true comparison, and instead of being a test run for a deployment to production, you're only reviewing the deployment to the staging environment itself.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>The best situation I've experienced is where a sanitised snapshot was synced to all pre-production environments every night.<\/p><p>I knew that my environment was, at most, a single day out of date, and I was confident that my changes would work in production if they did there.<\/p><p>In that situation, the staging site works and testing it has value, but if it's weeks or months out of date, it doesn't, as there are too many differences for it to be an accurate representation.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Test to save your job",
"date": "1695513600",
"permalink": "/archive/2023/09/24/test-to-save-your-job",
"text": "<p>I've recently been going through my YouTube \"Watch Later\" list and watching (or rewatching) videos of conference and meetup talks that I saved to watch later.<\/p><p>Today's talk was by Matt Stauffer at one of the previous Laracon conferences.<\/p><p>I've quoted Matt previously when explaining what to test on applications. The answer: \"The thing you'd lose your job for if it broke\".<\/p><p>In this talk, Matt has a slide that goes further into this, titled \"Test to save your job\".<\/p><h2 id=\"what-matt-said\">What Matt said<\/h2><p>The best place to start your tests is by asking yourself: \"What part of this app, if broken, would make me worried for my job?\"<\/p><ul><li>What's most likely to break?<\/li><li>What do I have the least control over?<\/li><li>What are we about to refactor?<\/li><li>What would make my clients stress out?<\/li><li>What would make me stressed out?<\/li><\/ul><h2 id=\"what-about-you%3F\">What about you?<\/h2><p>Do you have any other ways to decide what code to test? Reply and let me know, as I'd love to know.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Everyone tests their code, but not everyone writes automated tests",
"date": "1695427200",
"permalink": "/archive/2023/09/23/not-everyone-writes-automated-tests",
"text": "<p>Everyone tests their code.<\/p><p>No one writes code and ships it to production before testing it works.<\/p><p>It's just that most Developers test their code manually.<\/p><p>They write the code, switch to a browser or terminal, and run it.<\/p><p>It might be a quick task, such as reloading a page or executing a command, or it could be complex and time-consuming, such as filling in a long form and checking the results.<\/p><p>In this case, automated testing is a good option.<\/p><p>Instead of filling in the form, have the tests do it for you.<\/p><p>It will be quicker and more reliable than doing it manually.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing"]
}, {
"title": "Documentation and comments get stale. Tests don&#039;t.",
"date": "1695340800",
"permalink": "/archive/2023/09/22/documentation-and-comments-get-stale",
"text": "<p>I'm sure you've seen code comments that say the code will do something when, in fact, it does something different.<\/p><p>Or documentation that has become outdated and stale and no longer correct.<\/p><p>Automated tests and other tools, such as static analysis, are executable documentation, so they can't become stale.<\/p><p>If the implementation code changes and no longer matches the tests, the tests will fail, and either the implementation or test can be updated.<\/p><p>Then, if you need to refer to the test, as long as it's passing, you know what it shows is still applicable.<\/p><p>The same can't be said for markdown files, Confluence pages, Word documents or other static documentation.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","static-analysis"]
}, {
"title": "Buggy software causes reputational damage",
"date": "1695254400",
"permalink": "/archive/2023/09/21/buggy-software-causes-reputational-damage",
"text": "<p>As well as taking longer to fix than locally or in a failed CI pipeline, shipping buggy software to production causes reputational damage.<\/p><p>If an application goes down or doesn't run as expected, it could get noticed by your customers, clients, or your clients' customers.<\/p><p>You want your customers and clients to be assured you're writing the correct software based on their needs and requirements, and doing so with as few bugs and issues as possible.<\/p><p>While there are always bugs in software and occasional unexpected downtime, having these happen regularly can damage your and, if applicable, your client's reputation.<\/p><p>Therefore, it's in everyone's interest to write high-quality and well-tested software.<\/p><p>There will be fewer bugs, and by following practices such as feature flags and continuous integration and delivery, they can be fixed faster.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","feature-flags","continuous-integration","continuous-delivery"]
}, {
"title": "Why I prefer types",
"date": "1695168000",
"permalink": "/archive/2023/09/20/why-i-prefer-types",
"text": "<p>Whether it's PHP or JavaScript\/TypeScript, I prefer type declarations in my code.<\/p><p>As well as benefits like auto-completion in your IDE or text editor and being able to more effectively statically analyse the code, to me, the code is more readable and easier to understand with the types included.<\/p><p>It's more to read, but I can do so easily and immediately know what a function expects as function arguments and what it will return.<\/p><p>Here's the code from my previous email on types from a few days ago, with and without the types declared:<\/p><pre><code class=\"js\">add(...numbers) { \/\/ ...}subtract(...numbers) { \/\/ ...}add(...numbers: number[]): number { \/\/ ...}subtract(...numbers: number[]): number { \/\/ ...}<\/code><\/pre><p>Without types, I can infer what the function accepts and returns, but that's based on my assumption, which could be incorrect.<\/p><p>What if <code>numbers<\/code> was an array of strings of numbers - e.g. <code>['one', 'two', 'three']<\/code> - and what if instead of returning the result, it stored it in state to return from a different method like <code>equals()<\/code> or <code>calculate()<\/code>?<\/p><p>With the type declarations included, I don't need to presume, infer or make best guesses.<\/p><p>It's clear from just reading the code.<\/p>",
"cta": "",
"tags": ["software-development","types","javascript","typescript"]
}, {
"title": "Stop writing tests",
"date": "1695081600",
"permalink": "/archive/2023/09/19/stop-writing-tests",
"text": "<p>A few years ago, I worked at an agency on a client project.<\/p><p>We were writing automated tests and doing test-driven development. We were releasing features, and everything was going well.<\/p><p>Mid-way through the project, we were told to stop writing tests as it was taking \"too long\".<\/p><p>We did, and the number of bugs increased almost instantly.<\/p><p>We went from essentially no bugs to having a number of tickets being rejected through our quality assurance and the client's user-acceptance testing, as well as in production by the website's users.<\/p><p>The time we spent re-working the issues, fixing the bugs and doing remedial work in production would likely have been less than the time it would have taken to write the tests initially and avoided any reputational damage.<\/p><p>We started writing tests again later during that project, but the middle phase was the most stressful part, and the most bugs were created.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>It's not just about how long it takes to write the tests.<\/p><p>Having tests will save time overall by having fewer bugs that need to be fixed, less remedial work in production, and less reshuffling of priorities to re-work tickets that affect the project plan and timescales as well as the team's output and velocity.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing"]
}, {
"title": "Increasing test coverage with regression tests",
"date": "1694995200",
"permalink": "/archive/2023/09/18/increasing-test-coverage-with-regression-tests",
"text": "<p>Automated test suites don't tell you everything works - they tell you what you've tested isn't broken.<\/p><p>Having tests doesn't mean your code is bug-free. There could be edge cases or scenarios you haven't tested for that contain bugs, even though your test suite is passing.<\/p><h2 id=\"what-do-we-do%3F\">What do we do?<\/h2><p>When you find a bug, try replicating it within an automated test before attempting to fix it.<\/p><p>Once you have a failing test and can replicate the issue, go ahead and fix it.<\/p><p>If the test passes, you know you've fixed the bug and solved the issue.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Now you have this test, you cannot re-add the bug again without the test failing. You've prevented anyone from accidentally re-introducing it in the future and increased your test coverage.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "How much refactoring should I be doing?",
"date": "1694908800",
"permalink": "/archive/2023/09/17/how-much-refactoring-should-i-be-doing",
"text": "<p>I watched a webinar recently, and one of the panellists asked, \"How much refactoring should I be doing?\".<\/p><p>The reply was, \"More than you're doing now.\".<\/p><p>It was quite tongue-in-cheek, but I agree that, in general, code isn't refactored enough.<\/p><p>One main reason is a fear of introducing regressions, and to avoid that, you need a good automated test suite.<\/p><p>If you break the existing functionality whilst refactoring, you want the test suite to fail so you can identify and fix the regression.<\/p><p>If the test suite passes, you can release the new code.<\/p><p>How many tests and how much coverage do you need? There's no specfic answer - enough for you to be confident everything still works.<\/p>",
"cta": "",
"tags": ["software-development","test-driven-development","automated-testing","refactoring"]
}, {
"title": "How not to break 36,000 websites",
"date": "1694822400",
"permalink": "/archive/2023/09/16/how-not-to-break-36-000-websites",
"text": "<p>I've maintained the Override Node Options module for Drupal since early 2012.<\/p><p>I've maintained the Drupal 7 version and written new versions for Drupal 8 onwards.<\/p><p>At the time of writing, the module is used on at least 36,244 active Drupal websites.<\/p><p>I don't want to break 36,000 websites, and automated testing is my way of avoiding that.<\/p><p>I have three examples of how automated testing helped me when working on this module.<\/p><h2 id=\"upgrading-to-drupal-8\">Upgrading to Drupal 8<\/h2><p>When writing the initial Drupal 8 version of the module, as I started re-writing a feature, the first thing I did was recreate the tests from the Drupal 7 version.<\/p><p>Then, I followed a test-driven development approach to get the test passing using the Drupal 7 code for reference.<\/p><p>When the whole test suite was in place and passing, I knew there was feature parity between the two versions.<\/p><h2 id=\"resolving-a-large-merge-conflict\">Resolving a large merge conflict<\/h2><p>I was reviewing a feature request that had been open for some time, which included a large patch file with the code changes to implement it.<\/p><p>However, the patch no longer applied to the code, which caused various merge conflicts.<\/p><p>There were no additional tests within the patch, but I was able to use the existing tests to ensure the original functionality worked once the merge conflicts were resolved and there were no regressions caused by committing the patch.<\/p><p>I did later add tests for the new functionality, but without the original test suite, I would have likely not have accepted the patch and not committed the feature.<\/p><h2 id=\"refactoring-the-code\">Refactoring the code<\/h2><p>A few years ago, a colleague and I wanted to refactor the module code to make it more maintainable and easier to work on.<\/p><p>Then, the module was used on around 30,000 websites, so this could have been risky.<\/p><p>However, we had the test suite to ensure the functionality still worked and that our refactors were successful.<\/p><p>If we broke something and introduced a regression, a test would fail, and we could fix it.<\/p><p>Following the release containing the refactored code, there were no reported issues or regressions from the community.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Automated testing is about providing confidence.<\/p><p>Confidence the software works as expected and is releasable, either to clients for custom software or consumers of open-source software.<\/p><p>With a passing test suite, you can add and change code with confidence and without worrying about breaking it.<\/p>",
"cta": "",
"tags": ["drupal","php","automated-testing","test-driven-development"]
}, {
"title": "Types or no types",
"date": "1694736000",
"permalink": "/archive/2023/09/15/types-or-no-types",
"text": "<p>Here are two versions of some example code I've recently been working on.<\/p><p>One has types and uses TypeScript, the other is JavaScript and has no types.<\/p><p>Which do you prefer and why?<\/p><h2 id=\"typescript-with-types\">TypeScript (with types)<\/h2><pre><code class=\"js\">add(...numbers: number[]): number { return numbers.reduce((a: number, b: number) =&gt; a + b, 0);}subtract(...numbers: number[]): number { let total = numbers[0]; for (var i = 1, length = numbers.length; i &lt; length; i++) { total -= numbers[i]; } return total;}<\/code><\/pre><h2 id=\"javascript-no-types\">JavaScript (no types)<\/h2><pre><code class=\"js\">add(...numbers){ return numbers.reduce((a, b) =&gt; a + b, 0);}subtract(...numbers) { let total = numbers[0]; for (var i = 1, length = numbers.length; i &lt; length; i++) { total -= numbers[i]; } return total;}<\/code><\/pre>",
"cta": "",
"tags": ["software-development","types","JavaScript","TypeScript"]
}, {
"title": "Outside-in or inside-out?",
"date": "1694649600",
"permalink": "/archive/2023/09/14/outside-in-or-inside-out",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/09\/13\/which-type-of-test-should-i-use\">In yesterday's email<\/a>, I described the different types of tests available in Drupal and how to determine which test I should use.<\/p><p>I start with functional tests and move to kernel or unit tests when needed, so I usually have more functional tests, some kernel tests and a few unit tests.<\/p><p>This is the outside-in approach to testing.<\/p><p>The opposite is inside-out testing when you start with unit tests and have fewer functional tests.<\/p><p>Tests written outside-in are slower to run as they need to perform tasks like HTTP requests and interact with the database, compared to unit tests, which are fast to run but do reply on mocking dependencies rather than using real services and content.<\/p><p>Which do you prefer? Reply and let me know.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development"]
}, {
"title": "Which type of test should I use?",
"date": "1694563200",
"permalink": "/archive/2023/09/13/which-type-of-test-should-i-use",
"text": "<p>Drupal offers a few different types of tests you can use, but how do you know which one to pick?<\/p><p>This is how I decide based on what I need to test by asking these questions:<\/p><h2 id=\"do-i-need-to-test-http-requests-and-responses%3F\">Do I need to test HTTP requests and responses?<\/h2><p>Do I need to make GET or POST requests to a URL and check its response code, e.g. to check the endpoint exists, that I get an expected \"Page not found\" or \"Forbidden\" message, or to check if an item was created or updated?<\/p><p>If so, use a <code>Functional<\/code> test like <code>BrowserTestBase<\/code>.<\/p><h2 id=\"do-i-need-to-test-with-javascript%3F\">Do I need to test with JavaScript?<\/h2><p><code>BrowserTestBase<\/code> doesn't include JavaScript, so use a <code>FunctionaJavaScript<\/code> test if needed.<\/p><h2 id=\"do-i-need-to-retrieve-services-from-the-service%2Fdependency-injection-container%3F\">Do I need to retrieve services from the service\/Dependency Injection container?<\/h2><p>If I don't need to make HTTP requests but need access to the service container, I use a Kernel test such as <code>KernelTestBase<\/code>.<\/p><p>There's more setup for kernel tests compared to functional tests, such as installing the required configuration and creating schema tables in the database. However, having less installed means the tests run faster.<\/p><p>There are different base classes, such as <code>EntityKernelTestBase<\/code>, that can be used depending on the situation to simplify the setup.<\/p><h2 id=\"can-i-test-the-code-in-isolation-without-the-service-container%3F\">Can I test the code in isolation without the service container?<\/h2><p>If I can test the code without needing the service container and mock simple dependencies, then use a <code>Unit<\/code> test.<\/p><p>These are very fast to run, but you can overuse mocks and sometimes test the mocks instead of the code you intended to test.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>As well as the regular unit test type, Drupal offers various types of test that can be used depending on the situation.<\/p><p>I like to start with functional tests first and switch to kernel or unit tests when needed. They're slower to run but easier to write as they need less setup and arguably provide the most value.<\/p><p>If you're just getting started with testing, they're probably the quickest to learn too.<\/p>",
"cta": "",
"tags": ["drupal","php","automated-testing","test-driven-development"]
}, {
"title": "Don&#039;t inject too many dependencies",
"date": "1694476800",
"permalink": "/archive/2023/09/12/dont-inject-too-many-dependencies",
"text": "<p>While dependency injection is a good practice - i.e., passing dependencies into a class, usually via a constructor method - you want to be aware of how many dependencies you inject into each class.<\/p><p>There's no hard and fast rule, but I usually notice when I get to three dependencies and rarely inject more than four or five into a class.<\/p><p>Having too many dependencies suggests that the class is doing too much and has too many responsibilities and that another class may be needed.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Having smaller and simpler classes makes them easier to read, maintain and review. Ideally, each class should only have one responsibility, so it adheres to the Single Responsibility Principle (the \"S\" in SOLID).<\/p><p>Creating classes is cheap, so why not split one large and difficult-to-maintain class with many dependencies into multiple smaller and easier-to-work-with ones?<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Don&#039;t use &quot;else&quot;",
"date": "1694390400",
"permalink": "/archive/2023/09/11/dont-use-else",
"text": "<p>A popular approach to writing clean code is to avoid the \"else\" keyword and, if possible, avoid nesting <code>if<\/code> statements within other <code>if<\/code> statements.If I look at some code, I want to see as few indentation levels as possible, making the code easier to read and understand.<\/p><h2 id=\"what-should-i-do-instead%3F\">What should I do instead?<\/h2><p>Instead, you check for a condition; if that isn't met, you return early.For\u00a0example, here is some code I saw recently during a meetup talk:<\/p><pre><code class=\"language-php\">$callingClass = $scope-&gt;getClassReflection()-&gt;getName();if ($callingClass === TextMessageQueueProcessor::class) {\u00a0 \u00a0 return [];}$type = $scope-&gt;getType($node-&gt;var);foreach ($type-&gt;getReferencedClasses() as $targetClass) {\u00a0 \u00a0 if ($targetClass === TextMessageSender::class) {\u00a0 \u00a0 \u00a0 \u00a0 return [\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 RuleErrorBuilder::message(\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 sprintf(\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \"Can not call %s from %s\",\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 $targetClass,\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 $callingClass\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 )\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 )-&gt;build()\u00a0 \u00a0 \u00a0 \u00a0 ];\u00a0 \u00a0 }}return [];<\/code><\/pre><p>There are no <code>else<\/code> statements.<\/p><p>If the calling class isn't of the required type, it returns immediately with no violations, and we continue, knowing the calling class must be what we need.<\/p><p>If the target class is one where the code shouldn't be called from, it returns immediately with the\u00a0violation.<\/p><p>Finally, if no violations were found within the referenced classes, it returns an empty array.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>The code always returns an array of rule violations but does so as soon as possible at each point.<\/p><p>The code is clean and readable, and I can understand it, knowing once each condition is passed, I don't need to continue thinking about it.<\/p><p>Whilst there are some situations to use <code>else<\/code>, most of the time I've found that I can use an early return instead.<\/p>",
"cta": "",
"tags": ["software-development","clean-code"]
}, {
"title": "Code is read more than it&#039;s written",
"date": "1694304000",
"permalink": "/archive/2023/09/10/code-is-read-more-than-it-s-written",
"text": "<p>A lot of code is written once by one person and not changed again.<\/p><p>But it's read by multiple people at multiple times.<\/p><p>If the code is read more than it's written, we should be optimising it for readability so it's easier for people to understand.<\/p><p>The application doesn't care whether you wrote the code the \"clever\" way or the \"boring\" way, but people will appreciate the more readable version.<\/p><p>If I need to review or work on the code in the future, I want to read and understand it easily.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "A lack of tests discourages refactoring",
"date": "1694217600",
"permalink": "/archive/2023/09/09/a-lack-of-tests-discourages-refactoring",
"text": "<p>A common cause of not refactoring code is a lack of test coverage.<\/p><p>Why change some code if it works? What if we break it whilst refactoring it and introduce a regression?<\/p><p>If the code has accompanying automated tests, this can't happen.<\/p><p>The tests should be passing before starting a refactor and should be passing once the refactor is complete.<\/p><p>If the tests fail, the refactor was unsuccessful and should be reverted.<\/p><p>If you have a CI pipeline, a failing test should break the pipeline and prevent any further steps if you're doing continuous delivery or deployment whilst signalling to the Developer their refactor was unsuccessful and the pipeline needs to be fixed.<\/p><p>Without tests, the code could be broken during the refactor, and we wouldn't know.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development","refactoring","software-development"]
}, {
"title": "Do you proactively refactor your code?",
"date": "1694131200",
"permalink": "/archive/2023/09/08/do-you-proactively-refactor-your-code",
"text": "<p>Do you go back and proactively refactor code you've previously written?<\/p><p>In my experience, once some code is working, it's usually not reviewed again and refactored, and any TODO comments are still there.<\/p><p>If code is refactored, it's usually triggered by adding a new feature or fixing a bug that will be difficult or impossible with the existing code - i.e., make the change easy, then make the easy change.<\/p><p>Very rarely have I seen code be refactored to make it easier to read or change in the future.<\/p><p>Do you proactively refactor code or wait until something forces it to happen?<\/p><p>Do you not refactor code at all once it's been written?<\/p><p>Reply to this email and let me know which and why.<\/p>",
"cta": "",
"tags": ["software-development","refactoring"]
}, {
"title": "What&#039;s the simplest test to begin with?",
"date": "1694044800",
"permalink": "/archive/2023/09/07/what-s-the-simplest-test-to-begin-with",
"text": "<p>When giving talks and workshops or coaching on automated testing and test-driven development, some people may not have written tests before and aren't familiar with the structure or know where to begin.<\/p><p>In the workshops I ran for DrupalCamp London and DrupalCamp NYC, I wanted to cover this first before writing any implementation code.<\/p><p>Where do you put a test class, and what does it contain?<\/p><p>How do you run the tests, and how can you make it pass or fail?<\/p><h2 id=\"what-we-did\">What we did<\/h2><p>To start, we wrote a test for existing functionality within Drupal core - anonymous users can visit the front page.<\/p><p>This is the whole test:<\/p><pre><code class=\"language-php\">&lt;?phpnamespace Drupal\\Tests\\my_module\\Functional;use Drupal\\Tests\\BrowserTestBase;use Symfony\\Component\\HttpFoundation\\Response;class MyModuleTest extends BrowserTestBase {\u00a0 protected $defaultTheme = 'stark';\u00a0 \/** @test *\/\u00a0 public function the_front_page_loads_for_anonymous_users() {\u00a0 \u00a0 $this-&gt;drupalGet('&lt;front&gt;');\u00a0 \u00a0 $this-&gt;assertResponse(Response::HTTP_OK);\u00a0 }}<\/code><\/pre><p>This is a test someone can write, run and see the test pass.<\/p><p>They can then experiment by changing the values to make the test fail in different ways.<\/p><h2 id=\"what-next%3F\">What next?<\/h2><p>Then, we tested anonymous users cannot access the administration pages, which is also already the case in Drupal core, and then authenticated users with the correct permissions could access them.<\/p><p>People were getting the idea by now, and we moved on to writing and testing some of our own code.<\/p>",
"cta": "",
"tags": ["software-development","automated-testing","test-driven-development","php","drupal"]
}, {
"title": "Verbosity over abstraction",
"date": "1693958400",
"permalink": "/archive/2023/09/06/verbosity-over-abstraction",
"text": "<p>Recently, a steamer said they \"prefer verbosity over abstraction\/confusion\".<\/p><p>In that scenario, it was regarding the name of a microservice they were creating. It was long and verbose, but it described what it did.<\/p><p>It was clear to anyone working on that project what that service did, now and in the future.<\/p><p>I prefer this to shorter, less-descriptive names.<\/p><p>I hardly ever create a variable called <code>$x<\/code>, <code>$k<\/code> or <code>$v<\/code>. I only would if it was clear what it meant within its context.<\/p><p>I like to write descriptive names for test methods that explain what the test is doing. Even if I start with a vague name, I'll refactor it to make it more specific and clearer.<\/p><p>I prefer not to use PHP functions like <code>compact<\/code> and to write it out and avoid the abstraction and any confusion it could cause.<\/p><p>I prefer code to be verbose, descriptive and easy to read, understand and change.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Spring clean before upgrading",
"date": "1693872000",
"permalink": "/archive/2023/09/05/spring-clean-before-upgrading",
"text": "<p>One of the first things I do when reviewing whether an application can be upgraded is to look for anything that can be removed.<\/p><p>If it has modules that aren't used, uninstall and remove them.<\/p><p>A common one for Drupal projects is modules left from previous migrations, such as from Field Collections to Paragraphs that are no longer needed but still present.<\/p><p>Remove any old themes that are no longer used.<\/p><p>If you have content types, fields or views that aren't used, remove them, assuming you don't need the data.<\/p><p>Remove unused routes, Controllers or other classes not used in custom modules, or any other unused custom code.<\/p><p>Less moving parts means less to upgrade now and maintain in the future.<\/p>",
"cta": "",
"tags": ["drupal","software-upgrades"]
}, {
"title": "Charging more _not_ to write tests",
"date": "1693785600",
"permalink": "/archive/2023/09/04/charging-more-not-to-write-tests",
"text": "<p>Joel Clermont <a href=\"https:\/\/twitter.com\/jclermont\/status\/1690872089878691840\">replied to a previous email on Twitter<\/a>:<\/p><blockquote> <p>I once toyed around with the idea of charging MORE to do it without tests. Had a client pushing back very hard when I mentioned testing (what I thought they\u2019d perceive as a benefit). Ended up not pursuing it, but was a fun idea at the time.<\/p><\/blockquote><p>It's an interesting idea.<\/p><p>How much more would you charge not to write tests?<\/p><p>How much more would make you feel comfortable and confident that the application works as expected, and would cover the additional time for finding and fixing the bugs caused by not writing tests?<\/p><p>As Joel said, it was a fun idea, though it seems counter-intuitive to me, as the a client would be paying more for worse software.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Including time for tests in estimates",
"date": "1693699200",
"permalink": "/archive/2023/09/03/including-time-for-tests-in-estimates",
"text": "<p>If you need to provide estimates for your tasks and intend to write tests, include the time for the tests within the estimate.<\/p><p>Don't provide different estimates for testing and the implementation, or with tests and without tests - give one estimate that includes both.<\/p><p>Writing tests and testable code will take longer to begin with, but practice makes perfect and will save time in the long run.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development","software-development","estimation"]
}, {
"title": "Planning first or reviewing last?",
"date": "1693612800",
"permalink": "/archive/2023/09/02/planning-first-or-reviewing-last",
"text": "<p>Code reviews are something that happens after the code has been written.<\/p><p>Usually, a task is assigned to someone who completes it and makes the code available to their team members before it's merged.<\/p><p>The problem is that if the implementation is wrong, it's already been written, which costs time and money.<\/p><p>If the change needed to be rewritten or majorly changed before it could be merged, as well as being an awkward conversation, it would cost more time and money to do.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Instead of reviewing the code after it's been written, invest more time into planning how the implementation should work upfront.<\/p><p>What potential solutions exist, and which would work best in this situation?<\/p><p>Write technical design documents and, if needed, create a small proof of concept.<\/p><p>Do this as a team and decide on the approach before any code is written and time or effort is spent.<\/p><p>Then, the person working on the task will have a clearer path, and if you still want to review the code afterwards, you have something to compare it to.<\/p>",
"cta": "",
"tags": ["code-review","pair-programming","mob-programming"]
}, {
"title": "Non-blocking code reviews",
"date": "1693526400",
"permalink": "/archive/2023/09/01/non-blocking-code-reviews",
"text": "<p>If your team wants or needs to do code reviews, but you don't want it to slow down development, you could implement non-blocking code reviews.<\/p><p>Instead of creating a topic branch for a feature or fix, creating a pull or merge request and waiting for it to be reviewed before merging, the commit is merged, and the code is reviewed afterwards.<\/p><p>The ticket workflow could look like this:<\/p><p>To Do -> Doing -> Merged -> Reviewed -> Tested -> Deployed<\/p><p>Or:<\/p><p>To Do -> Doing -> Merged -> Deployed -> Tested -> Reviewed<\/p><p>The focus is getting the update to production, and the review is deferred.<\/p><p>The same CI pipeline rules apply - it must be passing before the code can be deployed, so the same quality checks are run.<\/p><p>With this approach, the code is still reviewed, either in the pull or merge request or by the commits on the mainline branch if doing trunk-based development. It's just done later.<\/p>",
"cta": "",
"tags": ["ci-pipelines","code-review"]
}, {
"title": "Code review discourages small refactorings",
"date": "1693440000",
"permalink": "/archive/2023/08/31/code-review-discourages-small-refactorings",
"text": "<p>If, for every change to a codebase, you need to create a topic branch, create a pull or merge request, and wait for it to be reviewed and approved - which can take days, weeks or longer - does that discourage you from making small changes?<\/p><p>If you spotted some unused commented-out code whilst working in a file and went to remove it or a variable that could have a better name, would you change it?<\/p><p>Alternatively, if you could make the change and know from a CI pipeline within a few minutes that everything still worked, would you be more likely to make the change and improve the code for yourself and the next person to work on it?<\/p>",
"cta": "",
"tags": ["code-reviews","trunk-based-development"]
}, {
"title": "TDD and &quot;Unexpected errors&quot;",
"date": "1693353600",
"permalink": "/archive/2023/08/30/tdd-and-unexpected-errors",
"text": "<p>When working on projects, it's common to see messages like \"The website encountered an unexpected error. Please try again later.\".<\/p><p>Usually, this is the message shown to the user, whilst a more detailed error message is logged for Developers to diagnose and fix the underlying error.<\/p><p>The wording \"unexpected error\" has been intriguing to me, though. When do you expect an error?<\/p><p>The best example I can think of for an expected error is when doing test-driven development.<\/p><p>When doing TDD, you want to see an error to start as you start with a failing test.<\/p><p>Then, you write the code to remove the error and get the test passing.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "CI pipelines are an automated code review",
"date": "1693267200",
"permalink": "/archive/2023/08/29/ci-pipelines-are-an-automated-code-review",
"text": "<p>I've worked on various teams over the last 13 years on which we've needed to do feature branches, pull requests and code reviews.<\/p><p>If the request isn't approved by (usually) two people, it won't be merged.<\/p><p>Instead of focusing on the problem that needed to be solved and how I'd done it, many reviews focused on the small details.<\/p><p>Do the lines have the correct number of spaces before them?<\/p><p>Do the comments end with a full stop?<\/p><p>Do the lines wrap at the correct point, and are your variable names in the right case?<\/p><p>Essentially, does the code comply with the agreed coding standards?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Whilst important (you want the code to follow standards and be in a consistent format), doing these checks manually is not a good use of time and is not what the code review should focus on.<\/p><p>These checks can be automated using CI pipelines or Git hooks to run tools like PHPCS to review and sometimes fix coding standards issues.<\/p><p>Automating these checks means the Developers can focus on what they should be reviewing.<\/p><p>How are they solving the problem, not how many spaces is the code indented by.<\/p>",
"cta": "",
"tags": ["code-review","ci-pipelines"]
}, {
"title": "Pair and mob programming are continuous code review",
"date": "1693180800",
"permalink": "/archive/2023/08/28/pair-and-mob-programming-are-continuous-code-review",
"text": "<p>Instead of a single Developer working individually on a task and submitting it for a code review once complete, try pair or mob programming.<\/p><p>As well as extra benefits, such as knowledge sharing and shared responsibility for the code, it's continuously reviewed and improved during the session.<\/p><p>Questions from \"Why are we doing it this way?\" to \"What's the best name for this variable?\" can be asked, and decisions and changes can be made in real time.<\/p><p>So, why wait until the task is complete and the code is harder to change to review it?<\/p><p>Why not have it reviewed as it's written?<\/p>",
"cta": "",
"tags": ["code-review","pair-programming","mob-programming"]
}, {
"title": "Pull requests are great for open-source, but not for teams",
"date": "1693094400",
"permalink": "/archive/2023/08/27/pull-requests-are-great-for-open-source",
"text": "<p>Code review with pull and merge requests is great for open-source but not for development teams or soloists.<\/p><p>On an open-source project, the code changes are most likely being submitted by someone you don't know and don't work with regularly, so having a step to review the code prior to merging it and decide if you want to take on the responsibility of maintaining it is a big decision.<\/p><p>On a development team, you work closely with the person submitting the change request and you have a shared responsibility and ownership of the code being added. The person isn't going to submit their change and not be seen again.<\/p><p>It takes time for code to be reviewed, which means it takes longer for the change to be released to users.<\/p><p>If you're a soloist, are you going to submit a request for you to review your own code?<\/p><p>If you don't need to do code review on your team, do you need to create feature or topic branches?<\/p><p>I'd suggest sticking to one canonical branch and doing trunk-based development instead.<\/p>",
"cta": "",
"tags": ["code-review","git","trunk-based-development"]
}, {
"title": "Work in small chunks",
"date": "1693008000",
"permalink": "/archive/2023/08/26/work-in-small-chunks",
"text": "<p>When working with teams who are starting with automated tests and test-driven development, a common issue is being stuck on a failing test and trying to do too much at once while getting it to pass.<\/p><p>Instead, work in small bite-sized iterations and focus on getting the test to pass as quickly as possible.<\/p><p>You don't want to be stuck in a failing state for longer than you need to.<\/p><p>Run the tests often, write the simplest code possible and don't write any code that isn't driven by a failing test.<\/p><p>Don't make too many changes at once so, if you do get stuck, you can reset to the last working test and start again.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Start with a vague test",
"date": "1692921600",
"permalink": "/archive/2023/08/25/start-with-a-vague-test",
"text": "<p>If you're unsure what your first test should be, start by writing a test with an intentionally vague name, just to get you started.<\/p><p>It may not be clear straight away what you're trying to test.<\/p><p>Once you get the ball rolling and you write more, it will usually become clear.<\/p><p>Then you can go back and rename the test method to something more specific.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Testing multiple implementations with contract tests",
"date": "1692835200",
"permalink": "/archive/2023/08/24/testing-multiple-implementations-with-contract-tests",
"text": "<p>If you have multiple implementations of a service, as I <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/08\/23\/dont-use-third-party-services-directly\">mentioned in yesterday's email<\/a>, you need to ensure they all provide the same functionality.<\/p><p>You need to be able to run the same tests against each implementation and have them pass.<\/p><h2 id=\"how-do-you-do-this%3F\">How do you do this?<\/h2><p>In PHP, I use a trait that contains the test methods and then have a test class for each implementation that uses the trait and sets up any test data.<\/p><p>Then, each test class will run the methods from the contract test trait and ensure they all provide the same behaviour, regardless of how it does so - whether it communicates with an API, uses an SDK, or returns fake values.<\/p><p>If one implementation doesn't return the same result as the others, its test will fail.<\/p><p>If you add a new implementation, you create a new test class, use the trait and get the tests to pass.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Don&#039;t use third-party services directly",
"date": "1692748800",
"permalink": "/archive/2023/08/23/dont-use-third-party-services-directly",
"text": "<p>If you need to integrate your application with a third-party service, don't integrate it directly - even if it has an SDK.<\/p><p>Doing so locks you into a single implementation and a single vendor.<\/p><p>If you write your own integration layer, it's possible to add multiple implementations, such as different payment gateways, that conform with a single interface.<\/p><p>If you need to switch to a different provider or add multiple options, you can without changing the existing code.<\/p><p>It also makes it easier to test as you can write a fake implementation and use it for testing.<\/p>",
"cta": "",
"tags": ["automated-testing"]
}, {
"title": "Deployments with your CI pipeline",
"date": "1692662400",
"permalink": "/archive/2023/08/22/deployments-with-your-ci-pipeline",
"text": "<p>You have a CI pipeline in your project.<\/p><p>Every time you push a commit, the CI pipeline runs and performs its checks.<\/p><p>It runs the automated tests and verifies they pass, statically analyses the code to identify any issues and validates the code follows the correct coding style and standards.<\/p><p>Everything passes.<\/p><h2 id=\"what-next%3F\">What next?<\/h2><p>If the pipeline passes, your change is deployable.<\/p><p>So, why not extend the pipeline to deploy the change once the checks pass?<\/p><p>If the checks don't pass, don't deploy.<\/p><p>It could be as simple as pushing the code to an S3 bucket, a separate Git branch or repository for managing deployments, or creating an artifact like a Docker image.<\/p><p>Instead of waiting for someone to do this manually, remove a step and automate it within the pipeline.<\/p><p>The sooner it's deployed, the sooner it provides value for your application's users.<\/p>",
"cta": "",
"tags": ["continuous-integration","pipelines"]
}, {
"title": "Which part of the CI pipeline has the most value?",
"date": "1692576000",
"permalink": "/archive/2023/08/21/which-part-of-the-ci-pipeline-has-the-most-value",
"text": "<p>The main part of my CI pipeline tasks are running the automated tests, coding standards checks and static analysis.<\/p><p>But which of these are the most valuable?<\/p><p>I used to run the coding standards check first as it was the quickest, followed by static analysis and the automated tests.<\/p><p>If a task were going to fail, it would fail quickly.<\/p><p>But is that the objective of the CI pipeline?<\/p><p>Whilst it needs to be quick, the main reason to run these is to ensure things work as expected.<\/p><p>Recently, I changed my pipelines to run the tests first, as these verify the code's behaviour.<\/p><p>I want to know if the code works but has a coding standard error that needs to be fixed rather than the pipeline failing on the error and not knowing whether the code works.<\/p>",
"cta": "",
"tags": ["continuous-integration","automated-testing","static-analysis"]
}, {
"title": "PHP types and assertions",
"date": "1692489600",
"permalink": "/archive/2023/08/20/php-types-and-assertions",
"text": "<p>Following yesterday's email about input validation, guard clauses and assertion libraries, these can be used to compliment PHP's native types and checking.<\/p><p>For example:<\/p><pre><code class=\"language-php\">function createJourney(string $from, string $to, int $duration): void { var_dump($from, $to, $duration);}<\/code><\/pre><p>In this code, each parameter has a type, but there's no validation on the values.<\/p><p>If I run this:<\/p><pre><code class=\"language-plain\">createJourney('', '', -10);<\/code><\/pre><p>I would get this output:<\/p><pre><code class=\"language-plain\">string(0) \"\"string(0) \"\"int(-10)<\/code><\/pre><p>This is probably not what you want.<\/p><p>I expect <code>$to<\/code> and <code>$from<\/code> to be not empty and the duration to be greater than zero.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>I can use an assertion library or throw my own Exceptions if the values pass the type checks but aren't what I need.<\/p><p>For example:<\/p><pre><code class=\"language-php\">function createJourney(string $from, string $to, int $duration): void { Assert::stringNotEmpty($from); Assert::stringNotEmpty($to); Assert::positiveInteger($duration); var_dump($from, $to, $duration);}<\/code><\/pre><p>Now, if an empty string or negative duration is passed - in my implementation or test code - an Exception will be thrown.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Asserting all the things",
"date": "1692403200",
"permalink": "/archive/2023/08/19/asserting-all-the-things",
"text": "<p>As well as assertions within tests, you can also check within implementation code that things are in an expected state or contain a certain value.<\/p><p>In PHP, this is done by throwing an Exception if a condition is met.<\/p><p>For example:<\/p><pre><code class=\"language-php\">if (!is_array(false)) { throw new \\Exception('Not an array');}<\/code><\/pre><p>There's also the <code>assert<\/code> construct which, since PHP 8.0, throws an Exception by default:<\/p><pre><code class=\"language-php\">assert(is_array(false));<\/code><\/pre><p>You can also use an assertion library, such as <code>webmozart\/assert<\/code> or <code>beberlei\/assert<\/code> which provide assertions and guard methods:<\/p><pre><code class=\"language-php\">use Webmozart\\Assert\\Assert;Assert::isArray(false);<\/code><\/pre><p>Similarly, if the condition fails, it throws an Exception that can be caught elsewhere.<\/p><p>As well as basic assertions such as the item is the expected type or don't match the condition, there are more complex assertions, such as all items within an array are a certain type or that an integer is positive.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>I use guard conditions a lot within my code. If something is not as I'd expect, I like for an error to be thrown. This makes is easy to test and to debug any failures compared to failing silently.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Types vs tests",
"date": "1692316800",
"permalink": "/archive/2023/08/18/types-vs-tests",
"text": "<p>Today, I saw a Twitter poll - \"Poll: Imagine your team has to build a project with either types or tests. You can't have both.\".<\/p><p>The results were:<\/p><ul><li>Types - 50.9%<\/li><li>Tests - 49.1%<\/li><\/ul><p>I was surprised by this.<\/p><p>If I can't add type declarations (type hints) or return types, I can still write tests to check what happens when different types are used.<\/p><p>I can also perform checks and throw errors or Exceptions if something isn't what I'd expect.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>I use types heavily, but I'd be more confident that my application would work if I had tests and that's the main objective when writing code for myself or clients and for my clients' customers.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development","static-analysis"]
}, {
"title": "Writing custom assertions in your tests",
"date": "1692230400",
"permalink": "/archive/2023/08/17/writing-custom-assertions-in-your-tests",
"text": "<p>Writing custom assertions is a great way to clean up your test code.<\/p><p>Here's an example from one of my client Drupal projects:<\/p><pre><code class=\"language-php\">private static function assertProductVariationHasPrice(ProductVariationInterface $productVariation, string $expectedPrice): void { self::assertSame( actual: $productVariation-&gt;getPrice()-&gt;getNumber(), expected: $expectedPrice, );}<\/code><\/pre><p>This one wraps a single assertion, but they could also include multiple assertions or additional steps.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>A custom assertion is a simple function but it makes the test code more readable and less repetitive.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Writing tests in your own time",
"date": "1692144000",
"permalink": "/archive/2023/08/16/writing-tests-in-your-own-time",
"text": "<p>This is how I first started writing automated tests.<\/p><p>I was working at a well-known digital agency, so I didn't want it to affect my output and cause me to deliver work late.<\/p><p>I wanted to give myself a less pressured opportunity to learn and experiment with different options and approaches.<\/p><p>So, when creating custom modules, I wrote the implementation code during billable work hours and the tests during the evening on my own time.<\/p><p>I was investing time in learning a new skill and one that I knew would pay dividends.<\/p><h2 id=\"how-did-it-go%3F\">How did it go?<\/h2><p>As I'd already written the implementation code, I wasn't doing test-driven development, so most of the tests were confirming what I'd written was correct with a passing test and being able to make it fail in expected ways.<\/p><p>One time, though, I found a bug I'd written that day. I think it was an incorrect permission name I'd typed.<\/p><p>I was able to fix it before it was submitted for quality assurance checks and client testing.<\/p><p>This saved the time and effort of creating another issue and branch, fixing it, going through the development cycle again and having it re-tested.<\/p><p>After that, for me, there was no going back.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Writing test and implementation code are the same task",
"date": "1692057600",
"permalink": "/archive/2023/08/15/writing-test-and-implementation-code-are-the-same-task",
"text": "<p>In Sunday's email, I said not to estimate separately for testing and implementation.<\/p><p>But you can't do this anyway if you're doing test-driven development.<\/p><p>With TDD, you aren't writing all of your tests and all of the implementation code or vice versa.<\/p><p>You're continuously switching back and forth, starting by writing a failing test and then enough implementation code for it to pass.<\/p><p>Then you write more test code, whether expanding the same test or writing a new one until you have a new failure.<\/p><p>You get it to pass, refactor, and repeat the process until the task is complete.<\/p><p>It's all part of the same task and the same estimate.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Why keep a dotfiles repository",
"date": "1691971200",
"permalink": "/archive/2023/08/14/why-keep-a-dotfiles-repository",
"text": "<p>A few days ago, I said it's been 8 years since I started my dotfiles repository and kept my configuration files in version control.<\/p><p>But why do this?<\/p><p>It makes it easy to share the same configuration across multiple computers, such as personal and work or different setups for clients.<\/p><p>It's also a backup of my configuration. If I need to reinstall my system or start fresh, I don't need to configure everything again manually.<\/p><p>If you work on a team, you can share your configuration with colleagues, find things that work well for the team, and anything that could cause issues.<\/p><p>I can experiment with settings and programs and then revert them again if I want to.<\/p><p>If I add or remove a program or change a setting, I have the Git commit log to refer to, and I can document why I made that change and what problem it solves in the message body.<\/p><p>I can review it in the future in case I need it again or want to re-evaluate it.<\/p><p>Like on other projects, capturing the why is important. The what can be seen in the diff and speaks for itself, but it doesn't explain why I made the change and won't help if I look at that commit in the future.<\/p>",
"cta": "",
"tags": ["dotfiles"]
}, {
"title": "Don&#039;t estimate separately for testing",
"date": "1691884800",
"permalink": "/archive/2023/08/13/dont-estimate-separately-for-testing",
"text": "<p>A common issue I see for people introducing automated testing is estimating the testing and implementation of a task separately.<\/p><p>Something like, \"It'll take x to do the work and x to write the tests for it\".<\/p><p>As well as implying you'd write all the code and then all the tests or vice versa, if you provide separate estimates, it's easy for someone to think the tests are optional and can be removed.<\/p><p>If you provide one estimate for both, this can't happen.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Does not writing tests actually save time?",
"date": "1691798400",
"permalink": "/archive/2023/08/12/does-not-writing-tests-actually-save-time",
"text": "<p>One of the most common responses to why people don't write tests is, \"We don't have time\".<\/p><p>So, people don't write tests to save time.<\/p><p>While you write less code, it takes longer to test everything manually during development, and more bugs will likely be found, which also takes longer to diagnose, fix, and deal with any knock-on effects.<\/p><p>Bugs in production add more administrative overhead as new tickets need to be created and managed, prevent other tickets from being worked on whilst they're fixed, and require more communication with clients and customers.<\/p><p>If you save ten minutes not writing a test but spend hours later fixing bugs, you didn't save time - you spent more time in the end.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Everyone tests their code",
"date": "1691712000",
"permalink": "/archive/2023/08/11/everyone-tests-their-code",
"text": "<p>No one writes code, commits it and pushes it to production without checking it works.<\/p><p>Everyone tests their code, but they usually do it manually. They switch from the code to a browser or terminal, run the code and evaluate the result.<\/p><p>This takes time, you need to switch contexts, and the test is only valid for that time.<\/p><p>There's no guarantee it will still work in the future.<\/p><p>Automated testing, however, means you can write your code and run the tests without leaving your IDE or text editor.<\/p><p>The tests can also be run in the future to ensure the functionality works without needing to re-test it manually.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Testing, fixed prices and bug-free guarantees",
"date": "1691625600",
"permalink": "/archive/2023/08/10/testing-fixed-prices-and-bug-free-guarantees",
"text": "<p>After my lightning talk for NWDUG on automated testing with Drupal, the question was asked how to find time for testing.<\/p><p>I've written about whether you need to ask for permission to write tests (you don't), and if you need to estimate tasks, you include the time and effort for writing tests as part of the estimate.<\/p><p>As someone who only offers fixed prices for development work and covers all work with a bug-free guarantee, I want to provide well-written, stable and tested software to my customers so I'm not always fixing bugs for free.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Vim is my lightsaber",
"date": "1691539200",
"permalink": "/archive/2023/08/09/vim-is-my-lightsaber",
"text": "<p>\"Vim is my lightsaber\" is the final chapter of Jess Archer's Neovim course on Laracasts.<\/p><p>In this summary, Jess explains that some Star Wars characters have lightsabers customised to their preferences and fighting style.<\/p><p>Vim is her lightsaber - her personalised tool to develop software. It works how she wants it to, with the features she needs.<\/p><p>I've written before about mastering your tools and thought this was a nice spin on it.<\/p>",
"cta": "",
"tags": ["vim"]
}, {
"title": "8 years of dotfiles",
"date": "1691452800",
"permalink": "/archive/2023/08/08/8-years-of-dotfiles",
"text": "<p>Today, I was speaking with a colleague about configuring Git, which led to a conversation about dotfiles repositories - somewhere where you version the changes to your configuration files and, usually, create symlinks to their expected locations.<\/p><p>Afterwards, I realised the first commit to <a href=\"https:\/\/github.com\/opdavies\/dotfiles\">my personal dotfiles repository<\/a> was over eight years ago, in July 2015.<\/p><p>What started as a repository to put my own Git configuration has undergone various changes since the tools I use changed, as well as the tools to manage the files themselves.<\/p><p>In 2021, I switched my <code>.vimrc<\/code> configuration file to an <code>init.vim<\/code> and switched to Neovim full-time and, most recently, almost a year ago, I started to use the Nix package manager and later adopted NixOS as my primary Linux distribution.<\/p><p>My complete NixOS and Home Manager configurations are within my <code>dotfiles<\/code> repository, and the configuration for tools, including Neovim, tmux and Git.<\/p><p>I wonder what the repository will look like in another eight years...<\/p>",
"cta": "",
"tags": ["dotfiles","open-source"]
}, {
"title": "Tests make upgrades less risky",
"date": "1691366400",
"permalink": "/archive/2023/08/07/tests-make-upgrades-less-risky",
"text": "<p>I recently reviewed a client's Drupal 9 website to gather information about upgrading it to Drupal 10.<\/p><p>The site has a number of custom modules. They all require changes to make them Drupal 10-compatible - some are a <code>core_version_requirement<\/code> update, and some are more complex.<\/p><p>None of these modules have automated tests.<\/p><p>If they did, I'd be able to run them and see if they pass, make my changes, and rerun the tests to verify they still pass, and the module works as it did previously.<\/p><p>But I can't.<\/p><p>I'd need to test each module beforehand to understand what it does manually and again after making the changes.<\/p><p>This is more time-consuming, riskier, and easier for me to introduce regressions or new bugs.<\/p><p>Whether it's a major CMS version upgrade, updating a contrib module or refactoring custom code, having a passing test suite you can use and rely on makes updates easier and less risky.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development","drupal"]
}, {
"title": "YAGNI",
"date": "1691280000",
"permalink": "/archive/2023/08/06/yagni",
"text": "<p>During a recent coding dojo session, we spoke about YAGNI - i.e. \"You aren't going to need it\".<\/p><p>In this situation, we discussed how many numbers we should support passing to a method in a calculator application.<\/p><p>There's no technical limit to how many numbers we can pass, but there may be a requirement where we only need to add or subtract two numbers. In that case, we don't need to calculate three or more numbers, so there's no benefit or value to writing that code.<\/p><p>If we follow YAGNI, we only write the code we need now. If the requirement changes in the future, we revisit the code and change it as required.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Use Drupal to own your content",
"date": "1691193600",
"permalink": "/archive/2023/08/05/use-drupal-to-own-your-content",
"text": "<p>I recently saw a social media website taking over users' handles - renaming them so they can have the original.<\/p><p>There were similar issues a few years ago when a website put a paywall in front of articles written by its users.<\/p><p>I've written articles and tutorials for companies I've worked at that no longer exist as the companies have been acquired.<\/p><p>This is why I like to own and control my content. I still have my versions if a website shuts down or changes its settings.<\/p><p>There are a lot of options, including Drupal, that can help with this. It's easy to set up a new website and start publishing your own content.<\/p>",
"cta": "",
"tags": ["drupal","open-source"]
}, {
"title": "Laravel Prompts and framework-agnostic tools",
"date": "1691107200",
"permalink": "/archive/2023/08/04/laravel-prompts",
"text": "<p>Although I wouldn't consider myself a \"Laravel Developer\", I enjoy watching the talks from the Laravel conferences, most recently Laracon US, that took place last week.<\/p><p>I like to learn from other communities and adopt relevant practices or tools within my projects. I did this with Laravel Collections, which I use on nearly every project.<\/p><h2 id=\"laravel-prompts\">Laravel Prompts<\/h2><p>I watched Jess Archer's talk on the new Laravel Prompts and was happy when she said it worked with plain PHP projects, not just Laravel.<\/p><p>This means I can potentially use it with Drupal and Drush or Symfony Console applications, too, such as my build configuration file generator.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>I like tools I can use across multiple technologies and prefer framework-agnostic tools to specific ones.<\/p><p>Then, if I'm working on a different project, I can use the tools I already know instead of learning something different just for that.<\/p>",
"cta": "",
"tags": ["php","laravel","open-source"]
}, {
"title": "What problem are we trying to solve?",
"date": "1691020800",
"permalink": "/archive/2023/08/03/what-problem-are-we-trying-to-solve",
"text": "<p>The Override Node Options module that I said yesterday is used on 35,000 websites isn't a complicated module.<\/p><p>It doesn't add a lot of features.<\/p><p>It solves a problem by adding additional permissions to Drupal that site administrators can assign to user roles and not need to give a more global permission like \"administer nodes\".<\/p><p>The problem being solved is allowing users to set node options, like the created date or published status, in a secure way.<\/p><p>If it wasn't solving a problem, it wouldn't be used on 35,000 Drupal websites.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "A crash course into automated testing with Drupal",
"date": "1690934400",
"permalink": "/archive/2023/08/02/a-crash-course-into-drupal-testing",
"text": "<p>Next week, I'll be presenting a lightning talk at the North West Drupal user group (NWDUG)'s August meetup.<\/p><p>It'll be a crash course into automated testing and test-driven development with Drupal, in which I plan to show how to get started by writing and running your first automated tests whilst exploring the different types of tests that are available.<\/p><p>It's an online event, so if you'd like to see this and other lightning talks on the 8th of August, RSVP at <a href=\"https:\/\/www.meetup.com\/nwdrupal\/events\/293429104\">https:\/\/www.meetup.com\/nwdrupal\/events\/293429104<\/a>.<\/p>",
"cta": "",
"tags": ["drupal","automated-testing","test-driven-development"]
}, {
"title": "Maintaining a module used on 35,000 Drupal websites",
"date": "1690848000",
"permalink": "/archive/2023/08/01/maintaining-a-module-used-on-35000-drupal-websites",
"text": "<p>Note: The numbers within this post are taken from my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">Test-Driven Drupal talk<\/a>, in which I also talk about this.<\/p><p>My first commit to the 7.x-1.x branch of the Override Node Options module was in March 2012. According to Drupal.org, the module was used on 9,212 websites then.<\/p><p>As well as the 7.x-1.x branch, there's the 8.x-2.x branch which supports Drupal 9 and 10, and previously Drupal 8.<\/p><p>The most recent statistics show the module is currently used on 34,981 websites and is consistently around 35,000.<\/p><h2 id=\"what-does-that-mean%3F\">What does that mean?<\/h2><p>The module is considered feature complete, but I'm not ruling out any new additions.<\/p><p>The main thing is ensuring that any changes don't break 35,000 websites!<\/p><p>I do this by relying on the module's automated test suite and ensuring that tests are added for any features or bugs and that the tests are passing before any new release.<\/p><h2 id=\"this-has-worked-well\">This has worked well<\/h2><p>A few years ago, I committed a feature request to both versions. While it didn't include additional tests, I verified the existing functionality worked after resolving a large merge conflict by ensuring the original tests passed.<\/p><p>More recently, a colleague and I refactored the module and split each override into its own class, making adding and maintaining overrides easier.<\/p><p>Because the tests were still passing, we knew our refactor was successful and not causing regressions.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Having automated tests and ensuring they're always passing has allowed me to add features and refactor code that I wouldn't have done or had the confidence to do otherwise.<\/p><p>It's great to have a popular module, but on the other hand, I don't want to break 35,000 websites which makes the tests invaluable.<\/p>",
"cta": "",
"tags": ["drupal","open-source"]
}, {
"title": "Upgrading from Drupal 9 is easier",
"date": "1690761600",
"permalink": "/archive/2023/07/31/upgrading-from-drupal-9-is-easier",
"text": "<p>Upgrading from Drupal 7 to 8, 9 or 10 is a large task.<\/p><p>You must create a new empty site, migrate your configuration and data, manually recreate anything else and rewrite any custom modules and themes.<\/p><p>Since Drupal 8, things have been different.<\/p><p>You can upgrade your site in place.<\/p><p>No large code rewrite or data migration.<\/p><p>Many contributed modules support multiple major Drupal versions simultaneously, so they may not need upgrading.<\/p><p>Others may need small changes to remove deprecated code or be compatible with breaking changes, and some tools can automate some or all of the changes.<\/p><p>The same applies to upgrading from Drupal 9 to 10, which will be the same for Drupal 11 next year.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Commit often, deploy often",
"date": "1690675200",
"permalink": "/archive/2023/07/30/commit-often-deploy-often",
"text": "<p>This is a follow-up to Friday's email on generic commit messages.<\/p><p>In it, I discussed seeing commit messages like <code>Week 20 development<\/code> in project codebases and why you should write specific commit messages for each change.<\/p><p>The other thing is, if you only commit once a week, you can only deploy once a week.<\/p><p>That's assuming that, on this project, the changes were committed and pushed weekly. It could have been fortnightly, monthly, or longer.<\/p><p>As well as increasing the time between deployments, it also makes them larger and riskier as they include more changes.That commit changed 106 files, added 3,453 lines and removed 17 lines, including custom module and theme changes, contrib module updates and library updates.<\/p><p>If the dependencies were committed and deployed first, followed by a series of small custom module and theme changes, even though it would have resulted in more deployments, each one would have been smaller and less risky as there were fewer changes and easier to debug any issues and fail forward.<\/p><p>I recommend that everyone commits and pushes their changes at least daily and use trunk-based development so everyone's changes apply and work together and are not separated on feature branches.<\/p><p>I recommend that they're pushed live daily, too, or as often as possible - reducing the chance of errors and getting the changes providing value for customers and clients.<\/p>",
"cta": "",
"tags": ["git","deployments"]
}, {
"title": "Should I wait to upgrade from Drupal 7?",
"date": "1690588800",
"permalink": "/archive/2023/07/29/should-i-wait-to-upgrade-from-drupal-7",
"text": "<p>It was announced at DrupalCon that Drupal 7 support was being extended one final time until January 2025.<\/p><p>But if you have a Drupal 7 website, does that mean you should wait to start upgrading it?<\/p><p>I recommend starting the process as soon as possible.<\/p><p>Even though Drupal core support is extended, I've looked at projects that use modules marked as unsupported by their maintainers for some time as they focus on versions for Drupal 8, 9 or 10.<\/p><p>In that case, those modules will have no new features, bug fixes or security updates, although Drupal core support has been extended.<\/p><p>You may have a lot of custom code that needs to be ported to Drupal 10 or a complex data structure that needs to be migrated, These things will take time, so it's best not to leave it until the last minute.<\/p><p>If you're stuck on Drupal 7, book an <a href=\"https:\/\/www.oliverdavies.uk\/call\">upgrade consultation call<\/a> with me or purchase an <a href=\"https:\/\/www.oliverdavies.uk\/drupal7\">upgrade roadmap for your project<\/a> and I'll get you unstuck.<\/p>",
"cta": "",
"tags": ["drupal","drupal-7","php"]
}, {
"title": "Don&#039;t write generic commit messages",
"date": "1690502400",
"permalink": "/archive/2023/07/28/generic-commit-messages",
"text": "<p>This week, I reviewed a client's Drupal 9 website and investigated the steps needed to upgrade to Drupal 10.<\/p><p>Looking at the Git log to see the commits for a module, I see <code>Week 20 development<\/code> as the latest commit message.<\/p><p>That commit changed 106 files, added 3,453 lines and removed 17 lines, including custom module and theme changes, contrib module updates and library updates.<\/p><p>This should have been several commits, each performing a clear and separate task.<\/p><p>Updating the dependencies should be its own commit, and changes to the custom modules and theme should be separate commits.<\/p><p>Then each commit could have its own clear and descriptive commit message explaining why each change was needed, any issues that were encountered during the change, and any alternative approaches considered.<\/p><p>That would have been more useful for me whilst looking through the logs than <code>Week 20 development<\/code>.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Stick to conventions",
"date": "1690416000",
"permalink": "/archive/2023/07/27/stick-to-conventions",
"text": "<p>If you're performing a task as there's already a convention on how to do it, stick to it.<\/p><p>If the codebase follows a particular coding standard, use it.<\/p><p>If a project uses repository classes instead of interacting directly with a database, do that with your code too.<\/p><p>If you use a framework with a service container and uses dependency injection, do that instead of manually creating classes.<\/p><p>If you need additional functionality for a Drupal project and there's an established and well-known module that adds it, use it. Unless it doesn't meet your needs, in which case, document why that's the case and why you used a different module or wrote a custom implementation.<\/p><p>If you need to create a content listing page, use the Views module, which is a standard approach. If not, document why and then explore other solutions.<\/p><p>If you don't follow a convention, it will be harder for you or others to work on it in the future.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Prove the concept",
"date": "1690329600",
"permalink": "/archive/2023/07/26/prove-the-concept",
"text": "<p>When starting a new task, find the simplest way to prove the concept.<\/p><p>Investigate upfront and evaluate potential approaches.<\/p><p>What's the smallest or quickest thing you could do to validate an idea?<\/p><p>It could be a small script that you can run and verify something works before moving it to its correct place within your application or creating a first implementation with hard-coded data that you refactor once you've proven the concept.<\/p><p>If you can't, you'll know it won't work without investing a large amount of time and you can move on to the next potential approach.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Working backwards",
"date": "1690243200",
"permalink": "/archive/2023/07/25/working-backwards",
"text": "<p>Today, I did a show-and-tell session with my team where I demonstrated an integration I've been working on for a few months and recently released to production.<\/p><p>The simplified workflow is we collate some data, send it to a third-party system for translation, receive the translated file and import the translations into Drupal's translation system.<\/p><h2 id=\"where-did-i-start%3F\">Where did I start?<\/h2><p>The first thing I did was not to collate the data and generate the file but to send a minimal, hard-coded version of the contents to the third-party system.<\/p><p>I'd have started with the code to import the translated strings if I hadn't already done this in an earlier spike.<\/p><p>This allowed me to send the file, check the response from the third party and ensure they could work with that file type and my proposed content structure.<\/p><p>If needed, I could have changed direction and avoided investing much time. This wouldn't have been the case if I'd left this until the end of the process.<\/p><p>I also have a working end-to-end test, and I can send a file and get the response I need.<\/p><p>What if I'd written all the code and discovered something wouldn't work?<\/p><h2 id=\"what-next%3F\">What next?<\/h2><p>Now, I can work backwards and start to make the content dynamic.<\/p><p>I can introduce more authentic and complicated data, remove the hard-coded test data, and check that things still work.<\/p><p>I still have the quick feedback loop, as I can always send the data to the third-party system and verify things work as I iterate on my implementation.<\/p><p>With the main pieces of the puzzle in place, I can continue building and filling in the others.<\/p><p>Once I have a complete feature with all the pieces in place, I can refactor as needed.<\/p><p>I still have the same finished puzzle - I just built it in a different order.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Testing is all about confidence",
"date": "1690156800",
"permalink": "/archive/2023/07/24/testing-is-all-about-confidence",
"text": "<p>Testing - manual or automated - is about building confidence.<\/p><p>If we deploy this change or release this feature, are we confident it will work as expected and not cause regressions elsewhere?<\/p><p>What if someone asked you on a scale between one and ten?<\/p><p>From an automated perspective, have you written enough tests for the feature to be confident it works?<\/p><p>If you're fixing a bug, do you have a test that reproduces the bug that was originally failing but now passing since you've added the fix?<\/p><p>Do the tests have enough assertions, and have you covered enough use cases and scenarios?<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>You can utilise code coverage metrics, but no hard rule says that the feature will work once x percentage is covered. Something with 100% coverage can still contain bugs.<\/p><p>For me, it's about the answer to the question:<\/p><p>If we deploy this change, how confident are you that it will work as expected?<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Tomorrow is easier if today&#039;s code is simpler",
"date": "1690070400",
"permalink": "/archive/2023/07/23/tomorrow-is-easier-if-todays-code-is-simpler",
"text": "<p>If you write simple code, it is quicker and easier to read, extend and change.<\/p><p>If you need to work on that code in the future - either tomorrow or in months or years - it will be easier to add the new feature or fix the bug.<\/p><p>It will also be easier for others who didn't write it, so they must understand what it does (or doesn't do) before making changes.<\/p><p>It will also likely be easier to debug with tools like Xdebug and PHPStan or upgrade with tools like Rector.<\/p>",
"cta": "",
"tags": []
}, {
"title": "More code, more problems",
"date": "1689984000",
"permalink": "/archive/2023/07/22/more-code-more-problems",
"text": "<p>The more code you have, the more potential problems you have.<\/p><p>More code means more opportunities for bugs in your software.<\/p><p>There's more code to maintain and more chance of encountering breaking changes as you update between major software versions of your project's dependencies, such as a CMS or framework.<\/p><p>If you can keep your amount of code to a minimum and reduce the maintenance overhead, you are less likely to experience issues.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Comments as communication",
"date": "1689897600",
"permalink": "/archive/2023/07/21/comments-as-communication",
"text": "<p>I often hear that code should be \"self-documenting\".<\/p><p>Instead of writing a comment, you should create a function or class with that name instead.<\/p><p>Whilst I agree with this, I think that code comments shouldn't describe what the code is doing - they should explain why the code is needed and provide any additional context to the person reading it.<\/p><p>If a comment just says <code>Returns true<\/code> or <code>Sends an email<\/code>, that can be understood by reading the code, so isn't providing any extra value or context. They can also become outdated as the code changes.<\/p><p>If a line of code is needed to fix a certain state or situation, or if a piece of code isn't particularly readable and isn't obvious what it does, those are good times to add comments.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Tests as communication",
"date": "1689811200",
"permalink": "/archive/2023/07/20/tests-as-communication",
"text": "<p>Automated tests aren't just checks to verify your software is working.<\/p><p>They're a communication tool that shows people working on the code how it's supposed to be used.<\/p><p>It's a form of documentation.<\/p><p>They are living examples of how to use the code with the benefit that you can run them and see if they still work, which isn't the case for markdown files or other types of static documentation that can become outdated.<\/p><p>Something I often do when evaluating or using software that has a test suite is review the tests and see how it's supposed to be used.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "TDD is like clicker training",
"date": "1689724800",
"permalink": "/archive/2023/07/19/tdd-is-like-clicker-training",
"text": "<p>During a webinar I watched recently, someone described test-driven-development as clicker training for Developers.<\/p><p>Similar to when people want to train an animal, the short cycles and quick feedback loops make it easier to stay focussed as you work on a task, and the satisfaction of getting a test to pass, completing a feature, or refactoring some messy code is the reward.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "TDD as a concept is simple, but TDD is difficult",
"date": "1689638400",
"permalink": "/archive/2023/07/18/tdd-as-a-concept-is-simple-but-tdd-is-difficult",
"text": "<p>Test-driven development as a concept is easy.<\/p><p>Before you write any code, you write a failing test and then write enough code to get it to pass.<\/p><p>But implementing test-driven development is harder.<\/p><p>As well as overcoming the initial reluctance to write the tests first, it takes time to learn how to use it well.<\/p><p>Code katas are great for practising TDD, but it can take time to progress from that to using it in a full application with more pieces.<\/p><p>As with many things, practice and perseverance are key.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Too many choices?",
"date": "1689552000",
"permalink": "/archive/2023/07/17/too-many-choices",
"text": "<p>I've recently considered moving my infrastructure automation code from Pulumi to Terraform.<\/p><p>One of Pulumi's features is that you can write your automation in a programming language instead of a domain-specific language (DSL) with Terraform.<\/p><p>As a Developer, this seems appealing, but it poses an important question - which programming language should you use?<\/p><p>I've written and re-written Pulumi code in TypeScript and Python and experimented with Go to see which feels best for me.<\/p><p>If one of these were my primary language, it would be a no-brainer.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>When I go into my automation repository, I want to write my code as quickly and simply as possible. I don't want to be thinking about how to write it or what language would be best to write it in.<\/p><p>Whilst I'd have to learn another DSL for Terraform, it would simplify my options by removing that choice for me, but also if I write automation code and hand it over to a client.<\/p><p>It's like taking my children to a restaurant.<\/p><p>They'll get overwhelmed if there are too many options on the menu. If we limit the options or order for them, they won't.<\/p>",
"cta": "",
"tags": ["automation","terraform"]
}, {
"title": "When writing a failing test, you&#039;re designing your code",
"date": "1689465600",
"permalink": "/archive/2023/07/16/when-writing-a-failing-test-youre-designing-your-code",
"text": "<p>When doing test-driven development, you start by writing a failing test and then write the code to make it pass.<\/p><p>This is the design phase where you ask questions and decide how you want the code to work.<\/p><ul><li>Are you going to use a global function or a method on a class?<\/li><li>Will you create a new class or add a method to an existing class?<\/li><li>What will it be called?<\/li><li>Will you use a named method or make the class invokable like a single-method Controller or Action?<\/li><li>Will it accept any parameters?<\/li><li>If so, what will the parameters be, what will they be named, and will they take any default values?<\/li><li>Will it return a value?<\/li><li>Should it throw an Exception?<\/li><\/ul><p>You might iterate on the design and change it as you write more assertions or tests, but take the opportunity to decide how you want the code to work at this point before you start writing the implementation.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Test-driven development makes you more productive",
"date": "1689379200",
"permalink": "/archive/2023/07/15/test-driven-development-makes-you-more-productive",
"text": "<p>I think that test-driven development (TDD) makes you productive.<\/p><p>Firstly, you save time by not needing to switch from your code to a terminal or browser to test it.<\/p><p>But, just as importantly, TDD reduces procrastination. It's much clearer to see what the next steps are.<\/p><p>You're either thinking and designing your code when writing a failing test or fixing the test failures in the implementation code to get the test to pass. You can focus on each failure and message separately and get them to pass instead of thinking about the whole feature or the rest of the application.<\/p><p>Once you have a working test, you can focus on refactoring any code or moving on to writing the next assertion or the next test.<\/p><p>I think that achieving small tasks with short feedback loops using test-driven development makes it much easier to remain productive and focussed.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Automated testing is more than just unit testing",
"date": "1688601600",
"permalink": "/archive/2023/07/06/automated-testing-is-more-than-just-unit-testing",
"text": "<p>When I speak to people about automated testing or hear others speak about it, it's often confused with unit testing.<\/p><p>Drupal and many other projects use PHPUnit. Its website describes PHPUnit as \"a programmer-oriented testing framework for PHP\", whereas Wikipedia explicitly says \"PHPUnit is a unit testing framework\".<\/p><p>But automated testing includes much more.<\/p><h2 id=\"other-types-of-tests\">Other types of tests<\/h2><p>In Drupal, whilst there are unit tests, PHPUnit also does feature (aka functional or browser) testing, where it can make an HTTP request to an endpoint and perform assertions on the response's status code and the returned text. This is great for checking if a page exists at a certain path, whether the correct users can access it and whether it contains the expected text. This isn't something that can be done with a unit test.<\/p><p>There are also integration (aka kernel) tests which don't access the browser but have access to Drupal's service container to interact with its services and can save and retrieve values from the database. Again, this isn't available in a unit test which relies heavily on mocking.<\/p><h2 id=\"what-else-is-there%3F\">What else is there?<\/h2><p>In Drupal, I've also used Behat - a behaviour-driven development testing framework that allows writing tests in a plain English syntax called Gherkin instead of PHP.<\/p><p>Pest PHP has an architecture plugin.<\/p><p>There are dedicated front-end testing frameworks like Cypress for UI testing.<\/p><p>Other quality tools like static analysis can also be considered testing tools.<\/p><h2 id=\"want-to-learn-more%3F\">Want to learn more?<\/h2><p>If you want to learn more about automated testing in Drupal, <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">I have a talk about that<\/a>.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Services vs Actions",
"date": "1688515200",
"permalink": "/archive/2023/07/05/services-vs-actions",
"text": "<p>When creating a custom module, where do you put your business logic?<\/p><p>You want to keep classes like Controllers and Commands simple and move any reusable logic into separate files.<\/p><p>Usually, this means 'Service' classes, but another approach I like is to use 'Action' classes.<\/p><h2 id=\"what-is-an-action-class%3F\">What is an Action class?<\/h2><p>An Action is a PHP class representing a single action that must be performed.<\/p><p>It usually contains a single method with a descriptive name summarising the task, such as <code>GetAccessToken<\/code>.<\/p><p>This differs from a generic service like <code>ApiService<\/code> with multiple methods like <code>getAccessToken()<\/code>.<\/p><h2 id=\"using-action-classes\">Using Action classes<\/h2><p>I'll register Action classes in the service container to use dependency injection and autowiring and easily inject the Action into other classes that need it, like Controllers and Commands.<\/p><p>If you need multiple implementations, multiple actions can implement the same Interface and make them swappable, such as having <code>GetAccessToken<\/code> and <code>GetAndCacheAccessToken<\/code> implement the same <code>GetsAccessToken<\/code> interface.<\/p><p>That also enables using design patterns like Decorators with Actions.<\/p><h2 id=\"why-i-like-actions\">Why I like Actions<\/h2><p>I like more readable and meaningful class names and prefer working with multiple simpler classes than those with fewer complex ones.<\/p><p>I like leveraging design patterns I'm used to, such as the Decorator pattern, by having common interfaces and contracts.<\/p><p>I like that if I need to add another implementation, I can add it without changing the existing code, so it follows the SOLID principles.<\/p><h2 id=\"what-about-you%3F\">What about you?<\/h2><p>Do you use Action classes in your code, or do you use Services or something else?<\/p><p>Reply to this email and let me know.<\/p>",
"cta": "",
"tags": ["software-development","software-architecture"]
}, {
"title": "Think smaller with TDD",
"date": "1688428800",
"permalink": "/archive/2023/07/04/think-smaller-with-tdd",
"text": "<p>I've recently added several custom search blocks and pages to a client project.<\/p><p>Each requires a results page, a list of autocomplete suggestions for users to select from, a custom form, and a block to place it on the required pages.<\/p><p>For each search, I'm first testing the results page, ensuring it exists and contains the correct results before testing the autocomplete results, creating the block and form, and linking everything together.<\/p><h2 id=\"thinking-small\">Thinking small<\/h2><p>This could seem like a large and daunting task, but with test-driven development, I can break everything into smaller, more manageable tasks.<\/p><p>My objective is either to write the next failing test and then get it to pass or to refactor what I've written.<\/p><p>I can focus on these small steps and make progress towards the end goal, guided by the tests I'm writing, instead of needing to focus always on one large and complex task.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Why write custom assertions in your tests?",
"date": "1688342400",
"permalink": "/archive/2023/07/03/why-write-custom-assertions-in-your-tests",
"text": "<p>I'm refactoring some code on a client project - creating a Repository class to centralise some logic before implementing the next feature.<\/p><p>The repository class is responsible for finding and returning any nodes with a specified field value and some base conditions (it must be the correct node type, published, etc.).<\/p><h2 id=\"adding-a-custom-assertion\">Adding a custom assertion<\/h2><p>I'm using PHPUnit's native assertions to check it returns a Collection (I regularly include the <code>illuminate\/collections<\/code> library from Laravel in other projects) and that each item is an instance of a <code>NodeInterface<\/code>, but there isn't an assertion to check each node is of the correct type.<\/p><p>My initial implementation was to loop over each node and use <code>assertSame<\/code> on its bundle before refactoring to create an array of unique bundle names and comparing it to my expected names:<\/p><pre><code class=\"language-php\">self::assertSame( expected: [$nodeType], actual: $haystack -&gt;map(fn (NodeInterface $item): string =&gt; $item-&gt;bundle()) -&gt;unique() -&gt;toArray(),);<\/code><\/pre><h2 id=\"why-write-a-custom-assertion%3F\">Why write a custom assertion?<\/h2><p>Whilst this works, it likely won't be clear in the future what it's testing.<\/p><p>My initial thought was to add a comment describing it, but then I decided to wrap it in a custom assertion - <code>assertContainsOnlyNodesOfType<\/code> - a private static function within my test class that wraps the native assertions.<\/p><p>This approach makes the test more readable now and in the future and more domain-focused by giving it a descriptive name.<\/p><p>It can be easily reused within the same test case or elsewhere.<\/p><p>Although I only perform one assertion in this case, I can combine multiple assertions and perform any other required steps.<\/p><p>Finally, I can contain any implementation details within the custom assertion. Here, I'm matching the result against an array of expected values, not just a single node type which is what I want. This detail can be contained within the assertion, making it easier to read and reuse in the future.<\/p>",
"cta": "",
"tags": ["automated-testing"]
}, {
"title": "Docker or Nix?",
"date": "1688256000",
"permalink": "/archive/2023/07/02/docker-or-nix",
"text": "<p>I've been a Nix user for about a year, starting with its package manager on my previously installed Linux distribution.<\/p><p>I started to use Home Manager for my user configuration and dotfiles and later switched to the NixOS operating system.<\/p><h2 id=\"using-nix-for-software-development\">Using Nix for software development<\/h2><p>I've also been using Nix Flakes for per-project configuration.<\/p><p>A Flake file is a simple file written in the Nix language that defines the project's dependencies and installs them from the Nix package manager.<\/p><p>Here is an example Flake for a PHP CLI application:<\/p><pre><code class=\"nix\">{\u00a0 inputs.nixpkgs.url = \"github:NixOS\/nixpkgs\/nixos-unstable\";\u00a0 outputs = inputs@{ flake-parts, ... }:\u00a0 \u00a0 flake-parts.lib.mkFlake { inherit inputs; } {\u00a0 \u00a0 \u00a0 systems = [ \"x86_64-linux\" ];\u00a0 \u00a0 \u00a0 perSystem = { config, self', inputs', pkgs, system, ... }: {\u00a0 \u00a0 \u00a0 \u00a0 devShells = {\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 default = pkgs.mkShell {\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 buildInputs = with pkgs; [ php82 php82Packages.composer ];\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 };\u00a0 \u00a0 \u00a0 \u00a0 };\u00a0 \u00a0 \u00a0 };\u00a0 \u00a0 };}<\/code><\/pre><p>It declares that PHP 8.2 and Composer are available, even if I have different versions installed globally.<\/p><h2 id=\"will-nix-replace-docker%3F\">Will Nix replace Docker?<\/h2><p>Nix and Flakes have replaced Docker for me on some projects.<\/p><p>If I have a simple setup and need a specific version of PHP or Node and some additional programs, I can get those from the Flake.<\/p><p>I don't know if it'll replace Docker for me completely and work on more complex projects, but it's working well for me where I'm using it.<\/p>",
"cta": "",
"tags": ["docker","nix"]
}, {
"title": "Once you start writing tests, you can&#039;t stop",
"date": "1688169600",
"permalink": "/archive/2023/07/01/once-you-start-writing-tests-you-cant-stop",
"text": "<p>Once you start testing\/TDD, you can't go back<\/p><p>Once you start writing automated tests or doing test-driven development, you can't go back to not doing it.<\/p><p>When adding a new feature, you'd need to test every situation and use case manually in a browser or command line - and, very likely, do so multiple times.<\/p><p>When fixing a bug, you'd need to follow the exact steps to replicate it and see it before attempting a fix. Again, you'd also need to test it manually.<\/p><p>Also, because it passes a manual test, there's no guarantee it won't break unexpectedly in the future.<\/p><p>While refactoring code without tests, bugs and regressions could be introduced as there's no test suite to run and ensure they're still passing.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>When you're used to writing tests and doing test-driven development, you get used to the quick feedback loops and the confidence to make changes.<\/p><p>It's easier to create a test that proves a bug exists and shows it'safixed because the test passes.<\/p><p>Once you have these things, you can't stop and go back to not having tests.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "How did you learn automated testing?",
"date": "1688083200",
"permalink": "/archive/2023/06/30/how-did-you-learn-automated-testing",
"text": "<p>I started to learn about automated testing in 2012 when I took over maintainership of the Drupal module, Override Node Options.<\/p><p>At the time, it had around 9,000 active installations (now more than 35,000), and I was concerned about breaking those sites if I pushed a bug and wanted confidence to make changes without introducing regressions.<\/p><p>Later, I started to learn about test-driven development and how to develop and design software by writing the tests first.<\/p><p>Although I'm not a Laravel Developer, Adam Wathan's \"Test Driven Laravel\" course was a great resource and information, as well as a number of presentations and talks at PHP meetups and conferences.<\/p><p>Once I understood how to write tests and do TDD, I took any opportunity to practice it, whether on projects or coding katas.<\/p><p>At one point, I was writing module code during work hours and writing tests for it during the evening.<\/p><h2 id=\"what-about-you%3F\">What about you?<\/h2><p>How did you learn automated testing or test-driven development? Reply to this email and let me know.<\/p><p>Bonus points if it was at one of my conference talks or workshops!<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Tests won&#039;t tell you if your code works",
"date": "1687996800",
"permalink": "/archive/2023/06/29/tests-wont-tell-you-if-your-code-works",
"text": "<p>Having a passing test suite or CI pipeline doesn't tell you if your appliction works.<\/p><p>There could be scenarios or edge-cases that aren't covered within the test suite and contain bugs, but aren't covered by the test suite.<\/p><p>There could be untested code that isn't covered at all.<\/p><p>A passing test suite proves that the tests that have been written so far pass and that there are no regressions introduced by the latest change.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>Instead of telling you that your application works by passing, the test suite tells you something is broken when it fails.<\/p><p>If a previously-passing test is failing, the application is broken and should not be deployed - not that the application is working if the tests don't fail.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "There&#039;s no value in a broken CI pipeline",
"date": "1687910400",
"permalink": "/archive/2023/06/28/theres-no-value-in-a-broken-ci-pipeline",
"text": "<p>The value in a CI pipeline is when its commands and checks are running successfully, and the pipeline is passing.<\/p><p>And then keeping it passing.<\/p><p>If the pipeline fails, it loses all of its value.<\/p><p>Passing should be its default state, and effort should be made to ensure it continues to pass.<\/p><p>If a pipeline fails, the change is not deployed, and the failure should be investigated and rectified so the pipeline is returned to a passing state and providing value.<\/p>",
"cta": "",
"tags": ["continuous-integration","pipelines"]
}, {
"title": "A CI pipeline is like an additional team member",
"date": "1687824000",
"permalink": "/archive/2023/06/27/ci-pipeline-additional-team-member",
"text": "<p>Imagine having a team member who tests each feature before every deployment, reviews the code to ensure its style is consistent, runs quality checks like linting and static analysis, and checks for insecure dependencies.<\/p><p>If those checks all pass, they automatically deploy the changes and make them live or update a pre-production environment.<\/p><h2 id=\"here%27s-the-thing\">Here's the thing<\/h2><p>A CI pipeline can do that. Automatically. For every commit and change to your codebase.<\/p><p>Having a CI pipeline is like having an additional team member and one who's always ready and waiting for someone to push a change to test.<\/p>",
"cta": "",
"tags": ["continuous-integration","pipelines"]
}, {
"title": "Is any code without tests legacy code?",
"date": "1687737600",
"permalink": "/archive/2023/06/26/is-any-code-without-tests-legacy",
"text": "<p>While I can't find the original quote, I've heard numerous people describe any code without automated tests as legacy.<\/p><p>Legacy code is typically inherited from other Developers and is riskier to work on and harder to change, as there is no guarantee changing one piece of code won't cause breakages elsewhere in the codebase.<\/p><p>This is true for code that doesn't have accompanying automated tests, regardless of when it was written.<\/p><p>I can release a feature to an environment, and although it may be checked and tested at the time, it likely won't be again for every subsequent release. Automated tests can run automatically for every commit and before every deployment, ensuring the code continues to work and for it to be edited without causing regressions.<\/p>",
"cta": "",
"tags": ["automated-testing"]
}, {
"title": "Do you need permission to do Test-Driven Development?",
"date": "1687651200",
"permalink": "/archive/2023/06/25/do-you-need-permission-test-driven-development",
"text": "<p>Something I've been asked before is \"Do you need permission to write automated tests or do Test-Driven Development?\".<\/p><p>A response I heard recently was \"Does a surgeon ask if they can wash their hands before operating?\".<\/p><p>The same as when I take my car to a garage, I expect the mechanic to do the appropriate diagnostic, repair work and testing to make it's working correctly and safely.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Credited on 200 fixed issues on Drupal.org",
"date": "1687564800",
"permalink": "/archive/2023/06/24/credited-on-200-fixed-issues",
"text": "<p>While writing yesterday's email, I saw this on my Drupal.org profile (https:\/\/www.drupal.org\/u\/opdavies):<\/p><blockquote> <p>Credited on 200 fixed issues<\/p><\/blockquote><p>This is not the number of commits I've made to projects and doesn't include issues on other websites like GitHub, but that I've been tagged as a contributor in 200 fixed issues on Drupal.org - aka \"contribution credits\".<\/p><p>It includes issues for projects I maintain, like Override Node Options and the Tailwind CSS starter kit, as well as contributions for events I've spoken at, like DrupalCon Europe and BADCamp, and modules for Drupal.org itself that I worked on whilst at the Drupal Association.<\/p><p>It also includes contrib projects others maintain, such as the Feature Toggle module and Drupal Commerce, and distributions like Commerce Kickstart and Open Atrium.<\/p><p>In particular, I'm proud of the 17 issues for Drupal core - some for patches I've contributed, some I've reviewed, and some whilst I've mentored at events like DrupalCons and DrupalCamps.<\/p><p>I've been allocating more open-source time recently, so expect the number of contributions on Drupal.org and GitHub to continue.<\/p>",
"cta": "",
"tags": ["drupal","open-source"]
}, {
"title": "Why keep a Changelog?",
"date": "1687478400",
"permalink": "/archive/2023/06/23/why-keep-a-changelog",
"text": "<h2 id=\"what-is-a-changelog%3F\">What is a Changelog?<\/h2><p>A Changelog is a file that documents changes made to a codebase.<\/p><p>In its simplest form, it's a plain text file within a code repository, or it can be written in Markdown or reStructuredText or kept within a separate tool like Confluence or Sharepoint. Regardless of where it's kept, the main thing is the content.<\/p><p>It's not a copy of the Git log. It's a summary of the changes to be read by humans and for them to see what's changed, not a list of Git commits.<\/p><p>If you're considering using my open-source package, you can see what changes I've released, when, and what changes are due to release.<\/p><h2 id=\"how-is-it-structured%3F\">How is it structured?<\/h2><p>Each version should have a heading specifying the version number and\/or release date and a list of changes grouped by their type - whether something was added, changed, deprecated, removed, etc. This works well if you use conventional commits!<\/p><p>I like to follow a format called <a href=\"https:\/\/keepachangelog.com\">Keep a Changelog<\/a>.<\/p><p>The headings link to a diff so you can see all of the commits and changes made to the code, and there's an <code>Unreleased<\/code> section that shows commits that have yet to be tagged and released.<\/p><p>If you need to present changes to a review or approval board, having an easy-to-read list of changes, separated by their type, is a much clearer format than a list of Git commits.<\/p><h2 id=\"when-should-it-be-updated%3F\">When should it be updated?<\/h2><p>I recommend continually updating the Changelog rather than leaving it to just before a deployment. It's quick to add it to the <code>Unreleased<\/code> section as part of the commit and update the headings later.<\/p><h2 id=\"can-i-see-an-example%3F\">Can I see an example?<\/h2><p>Sure. See the one I added to the <a href=\"https:\/\/github.com\/opdavies\/national-rail-enquiries-feed-parser\/blob\/main\/CHANGELOG.md\">National Rail Enquiries feed parser library<\/a> I've been working on or the <a href=\"https:\/\/git.drupalcode.org\/project\/tailwindcss\/-\/blob\/5.x\/CHANGELOG.md\">Tailwind CSS starter kit theme for Drupal<\/a>.<\/p>",
"cta": "",
"tags": ["changelog"]
}, {
"title": "It&#039;s only a bad situation if you fail to learn from it",
"date": "1687392000",
"permalink": "/archive/2023/06/22/fail-to-lear",
"text": "<p>I heard this on a non-tech podcast but it applies to tech too:<\/p><blockquote> <p>It's only a bad situation if you fail to learn from it<\/p><\/blockquote><p>Whether its a missed deadline, a failed deployment, a production outage or pushing a bug to production, there are opportunities to learn and improve.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Deployments or releases",
"date": "1687305600",
"permalink": "/archive/2023/06/21/deployments-or-releases",
"text": "<p>\"Deployments\" and \"releases\" are often used interchangeably but mean different things.<\/p><p>A deployment moves a change from one place to another, such as some updated code from a staging environment to production.<\/p><p>A release is when the change made is available to users.<\/p><p>They can happen at the same time, or you can use feature flags to separate them, deploying the code in advance, and the change is only released (or unreleased) by toggling the feature flag.<\/p>",
"cta": "",
"tags": ["deployments","releases"]
}, {
"title": "Should you deploy on a Friday?",
"date": "1687219200",
"permalink": "/archive/2023/06/20/should-you-deploy-on-a-friday",
"text": "<p>There's a common saying about not deploying changes on a Friday to prevent outages or issues before the weekend.<\/p><p>I've also seen this where people won't deploy after a particular time of the day as it's too close to the evening.<\/p><h2 id=\"when-did-you-last-deploy%3F\">When did you last deploy?<\/h2><p>The longer it's been since the last deployment, the risker each deployment is.<\/p><p>If there are weeks or months of changes, it will be risky regardless of which day it is.<\/p><p>If your last deployment was an afternoon, deploying a small change the following morning will be low risk, even on a Thursday and Friday.<\/p><h2 id=\"conclusion\">Conclusion<\/h2><p>If you're nervous about deploying on a Friday, I think you need to aim for smaller and more frequent deployments to minimise the risk.<\/p><p>The issue isn't when you're deploying. You likely need to do so more often.<\/p><p>If there is an issue after a large release, it will take more time to debug or roll back compared to a small release which is easier to find and fix the problem or revert that single change.<\/p>",
"cta": "",
"tags": ["deployments"]
}, {
"title": "Should you upgrade from Drupal 7 to Drupal 10?",
"date": "1687132800",
"permalink": "/archive/2023/06/19/should-you-upgrade-from-drupal-7-to-drupal-10",
"text": "<p>If you're stuck on Drupal 7, why should you upgrade to Drupal 10 instead of moving to another platform?<\/p><h2 id=\"familarity\">Familarity<\/h2><p>Although there is a new admin theme, it works in the same way as it did in earlier versions of Drupal, so it will be familiar to anyone who is used to using or developing in it.<\/p><p>And whilst there have been differences since Drupal 8, creating modules and themes should seem familiar too with similar concepts such as <code>.info<\/code> files (now <code>.info.yml<\/code> files), hooks, preprocess functions and templates.<\/p><h2 id=\"code-reuse\">Code reuse<\/h2><p>If you have existing custom modules, you should be able to reuse some of its code in newer versions of Drupal. It might need to be restructured or refactored and will depend on how tightly coupled your business logic is to your Drupal code, but if, for example, you have a custom module that creates a node programmatically, the same can be done in newer Drupal versions.<\/p><h2 id=\"built-in-migration-tools\">Built-in migration tools<\/h2><p>Whilst you do need to migrate your data from Drupal 7 into Drupal 10, the newer versions come with built-in migration tools that recreate your content types etc first as well as moving the data so you don't need to start from scratch.<\/p><h2 id=\"new-versions-of-existing-modules\">New versions of existing modules<\/h2><p>Many modules and themes you use in Drupal 7 will either have equivalent versions for Drupal 10 or a nominated alternative (such as Field Collection to Paragraphs), so you don't need to look for a new solution if there's an updated version of something you already use.<\/p><h2 id=\"conclusion\">Conclusion<\/h2><p>These are the initial things that I thought of, but there are many other reasons to upgrade to Drupal 10 instead of moving to something else.<\/p><p>TLDR - you don't need to start from scratch if you can re-use parts of your existing code, and you can use the built-in modules to handle the data migration.<\/p><p>If you have a reason, reply to let me know, and I'll post another list.<\/p>",
"cta": "",
"tags": ["drupal","drupal-7"]
}, {
"title": "Are you really doing CI/CD?",
"date": "1687046400",
"permalink": "/archive/2023/06/18/are-you-doing-ci-cd",
"text": "<p>Does your team really do CI\/CD (continuous integration and delivery)?<\/p><p>I recently watched a recording of a talk from another daily emailer, <a href=\"https:\/\/jhall.io\">Jonathan Hall<\/a>, who started by asking the audience to raise their hands and keep them raised if...<\/p><ul><li>They did a release to production in the last week.<\/li><li>They did a release to production yesterday.<\/li><li>They do not have a permanent branch called <code>develop<\/code>.<\/li><li>They do not have a special \"hotfix\" procedure.<\/li><li>Every Developer on their team merged work into <code>main<\/code> yesterday.<\/li><li>They have no pull requests more than 24 hours old.<\/li><\/ul><h2 id=\"ci%2Fcd-is-about-process\">CI\/CD is about process<\/h2><p>This is an excellent way to highlight that CI\/CD is about processes, not technologies.<\/p><p>Continuous integration is about how often everyone merges and pushes their changes, and continuous delivery and deployment is how you create releasable software and how long it takes for a change to get into production - not whether or not you use GitHub Actions, GitLab CI, CircleCI or Jenkins.<\/p>",
"cta": "",
"tags": ["continuous-integration","continuous-delivery","continuous-deployment"]
}, {
"title": "Avoid Git merge hell with trunk-based development",
"date": "1686960000",
"permalink": "/archive/2023/06/17/avoid-git-merge-hell-with-trunk-based-development",
"text": "<p>Regardless of whether I was working as part of a team or individually, I used to create a new branch for every change. I'd do the work and merge the feature branch back into the mainline branch - usually either <code>main<\/code> or <code>develop<\/code>.<\/p><p>When working on a team, conflicts are common that prevent different changes from being merged, and they're more likely the more time it's been since the last merge and how large the change is.<\/p><p>Once, when demoing some in-progress work to a freelance client, I needed to switch branches as the changes were on different feature branches. Doing so broke my local environment and derailed the demo.<\/p><h2 id=\"trunk-based-development\">Trunk-based development<\/h2><p>These days, I advocate for and prefer to use trunk-based development. Instead of committing changes to feature branches, they are made directly to the mainline branch.<\/p><p>As there are no feature branches, there are no merge conflicts when merging into mainline.<\/p><p>Although there can still be conflicts when pulling remote changes, trunk-based development pairs nicely with continuous integration - when everyone works in small commits and pushes changes at least once daily. This makes conflicts less likely but also smaller and easier to resolve, and because everyone's changes are not hidden on feature branches, you know they will integrate and work together.<\/p><p>It also stops me from breaking my environment during client demos!<\/p>",
"cta": "",
"tags": ["git","trunk-based-development"]
}, {
"title": "Make the change easy, then make the easy change",
"date": "1686873600",
"permalink": "/archive/2023/06/16/make-the-easy-change",
"text": "<p>Have you worked on some code, whether it's to add or extend functionality or fix a bug and thought, \"This would be much easier if...\"?<\/p><p>A quote by Kent Beck:<\/p><blockquote> <p>For each desired change, make the change easy (warning: this may be hard), then make the easy change<\/p><\/blockquote><p>If you can refactor the code and make it easier to implement your required change, do so.<\/p><p>Any automated tests should be passing before and after, and I'd commit the refactored code to ensure any CI pipelines and checks are still passing.<\/p><p>Then, go ahead and make the required change - add the feature or fix the bug - which should now be easy.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Done is better than perfect",
"date": "1686787200",
"permalink": "/archive/2023/06/15/done-is-better-than-perfect",
"text": "<p>Whether I'm doing test-driven development or not, I focus on making the feature work or fixing the bug in the simplest way possible.<\/p><p>Then, once this is done, I can pass through the code again and refactor it as needed.<\/p><p>I can split code into separate files, move logic from the Controller into separate services, ensure that patterns like dependency injection are followed, and checks like coding standards and static analysis are passing.<\/p><p>I might deploy a change in its passing state and leave TODO comments or create follow-up issues to describe potential refactors or changes to be addressed later.<\/p><p>The main goal is to get the application working and providing value for its users.<\/p>",
"cta": "",
"tags": []
}, {
"title": "What if there was no open-source software",
"date": "1686700800",
"permalink": "/archive/2023/06/14/what-if-there-was-no-open-source-software",
"text": "<p>I was listening to a podcast today, and the question was mentioned - \"What if there was no open-source software?\".<\/p><p>As a self-taught Developer who has worked with open-source technologies and become an expert in Drupal - an open-source content management system - this would have had a big effect.<\/p><p>If there were no open-source frameworks or CMSes like Drupal, Symfony, Laravel or Vue.js, Developers would need to write everything from scratch, and companies would need to pay for the extra time.<\/p><p>There would be no reusable knowledge as Developers move to different companies as everything would be written in-house.<\/p><p>There would be no communities and events like conferences and meetups for open-source technologies.<\/p><p>As well as frameworks, what about languages like PHP that are open-sourced? Would companies also need to write and maintain their own programming languages?<\/p><p>What about Linux, which I use every day for my desktop environment and servers, and other tools like Neovim, PHPStan, PHPUnit and Pest that are all open-source?<\/p><p>Even as someone who contributes to and sponsors open-source projects and their Developers, it's still a shock to think how things would work without open-source software.<\/p><p>If you use open-source software, please consider sponsoring, supporting or contributing to the projects you use and depend on.<\/p>",
"cta": "",
"tags": ["open-source"]
}, {
"title": "Should you feature flag everything?",
"date": "1686614400",
"permalink": "/archive/2023/06/13/should-you-feature-flag-everything",
"text": "<p>Whilst it's probably impractical to feature flag every new feature or change to your application, considering it is something I do for each change.<\/p><p>If you find a bug after a feature has been released, if it's feature flagged, you can quickly disable it without needing to make a code change or release another version.<\/p><p>Instead of needing a rollback plan for a release and reverting to the previous version, it can be as simple as disabling the feature flag again to turn it off whilst the cause is investigated.<\/p><p>There is a maintenance overhead to adding a feature flag, and it can cause complexity by creating separate paths within the code but using feature flags gives a lot of benefits too.<\/p>",
"cta": "",
"tags": ["feature-flags"]
}, {
"title": "Feature flags in a multi-tenancy application",
"date": "1686528000",
"permalink": "/archive/2023/06/12/feature-flags-in-a-multi-tenancy-application",
"text": "<p>A scenario for having long-lived feature flags is in a multi-tenant application where the same codebase serves multiple projects - e.g. a multi-site Drupal application or a module reused on multiple websites.<\/p><p>This is the use case I have for a client project which uses a multi-site setup to serve multiple websites from the same Drupal codebase.<\/p><p>If I need to add a feature to sites 1 and 3 but not site 2 or test a change to only site 2, I can do this by enabling a per-site feature flag.<\/p><p>Instead of being removed, these flags will remain until the change can be made permanent on all websites, meaning it can be toggled on and off as needed - allowing each site to be configured separately whilst keeping it easy to maintain by having a single canonical codebase.<\/p>",
"cta": "",
"tags": ["feature-flags"]
}, {
"title": "Failing fast",
"date": "1686441600",
"permalink": "/archive/2023/06/11/failing-fast",
"text": "<p>Usually, failing fast in software development refers to errors in code, but another interpretation of this is \"What's the quickest and simplest way to validate or prove an idea\"?<\/p><p>If it's fixing a bug or architecting a new feature, what's the simplest thing that can be done to achieve that? It could be writing a technical document or creating a simple proof of concept rather than building the entire feature.<\/p><p>If it fails, your sunk cost is low as you've not invested much time, money or energy.<\/p>",
"cta": "",
"tags": []
}, {
"title": "How do you know when to remove a feature flag?",
"date": "1686355200",
"permalink": "/archive/2023/06/10/how-do-you-know-when-to-remove-a-feature-flag",
"text": "<p>But once a feature has been enabled, how do you know if you can remove its flag?<\/p><p>A simple suggestion I've heard is to add a \"Remove when...\" comment above where the flag is used and detail what conditions need to be in place before the flag can be removed.<\/p><p>It might be a period of time or after another feature has been shipped, but it will give some clarity when you see the flag in the code to if or when it can be removed.<\/p>",
"cta": "",
"tags": ["feature-flags"]
}, {
"title": "Drupal is built by people",
"date": "1686268800",
"permalink": "/archive/2023/06/09/drupal-is-built-by-people",
"text": "<p>A quote I heard from DrupalCon, made by my former colleague Tim Lehnen - CTO at the Drupal Association - when talking about contribution:<\/p><blockquote> <p>Contribution is what makes Drupal thrive.<\/p> <p>Drupal is built by people.<\/p> <p>No one entity, no one person builds Drupal.<\/p> <p>It's you who builds Drupal.<\/p><\/blockquote>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Write less Drupal code",
"date": "1686182400",
"permalink": "/archive/2023/06/08/write-less-drupal-code",
"text": "<p>An approach I like to make my Drupal code more maintainable is to write less of it and move any generic PHP code into separate framework-agnostic libraries.<\/p><p>These could be in open-sourced packages installed from Packagist or kept within the same repository.<\/p><p>Having less Drupal-specific code keeps modules smaller and easier to maintain and upgrade.<\/p><p>If I need to upgrade a module from Drupal 7 to Drupal 10, I can reuse the generic code and focus on changing its integration points with Drupal to make it compatible.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "What does the Drupal 7 EOL extension mean to you?",
"date": "1686096000",
"permalink": "/archive/2023/06/07/what-does-the-drupal-7-eol-extension-mean-to-you",
"text": "<p>Following the announcement at DrupalCon, the official announcement has been released regarding Drupal 7's end-of-life extension:<\/p><blockquote> <p>Today, we are officially announcing that Drupal 7 will reach its end of life on January 5, 2025.<\/p> <p>With this final extension, the Drupal Security Team is also adjusting the level of support provided.<\/p> <p>This will be the final extension.<\/p><\/blockquote><p>If you're involved with one of the ~400,000 Drupal 7 websites (according to https:\/\/www.drupal.org\/project\/usage\/drupal), what does the additional year and a half of Drupal 7 mean to you?<\/p><p>Will you use the time to find the budget to upgrade, assemble a migration plan, port any missing contributed modules or refactor your custom modules or theme to make it easier to upgrade?<\/p><p>Is it different knowing it\u2019s the final extension compared to the previous time when it wasn\u2019t known if it would be extended again?<\/p><p>If you're stuck on Drupal 7 or staying on it into 2024 or 2025, what's stopping you from upgrading?<\/p>",
"cta": "",
"tags": ["drupal","drupal-7","php"]
}, {
"title": "Drupal 7 end-of-life extended",
"date": "1686009600",
"permalink": "/archive/2023/06/06/drupal-7-end-of-life-extended",
"text": "<p>It was announced this week at DrupalCon that the end-of-life date for Drupal 7 has been extended until the 5th of January 2025, giving another year for people to upgrade the 40,000+ Drupal 7 websites.<\/p><p>Whilst there's no official announcement yet, it seems this is the final extension and will be when support ends.<\/p><p>Of course, it doesn't mean all of the contributed modules, themes and distributions will be supported or updated until then, but this will give additional time to plan and migrate the remaining Drupal 7 websites whilst still giving clarity by setting a final date that will not be extended again.<\/p><p>If you're still on Drupal 7 and need to learn more about upgrading to Drupal 10, <a href=\"https:\/\/www.oliverdavies.uk\/call\">book an advisory call<\/a> or <a href=\"https:\/\/www.oliverdavies.uk\/drupal7\">an upgrade roadmap<\/a> for your Drupal 7 project.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "How long should a feature flag live?",
"date": "1685923200",
"permalink": "/archive/2023/06/05/how-long-should-a-feature-flag-live",
"text": "<p>Instead of creating a branch that lives for as long as the code takes to write, if it's behind a feature flag, the code can be merged into the mainline branch without affecting the rest of the codebase.<\/p><p>Being able to release changes incrementally lowers the risk compared to releasing a large change all at once.<\/p><p>But the same issue can occur with feature flags, and the longer that code is behind a feature flag, the more risk there will be when enabling the feature.<\/p><p>So, like feature branches, feature flags should be short-lived and only used for as long as is needed to create the first releasable version of the feature. The feature flag can be removed once the feature is live, and the feature can continue to be iterated on and improved.<\/p>",
"cta": "",
"tags": ["software-development","software-engineering","feature-flags"]
}, {
"title": "Drupal 9: almost end-of-life already",
"date": "1684627200",
"permalink": "/archive/2023/05/21/drupal-9-almost-end-of-life-already",
"text": "<p>With the focus being on Drupal 7's potential end-of-life this November, it's also worth being aware that Drupal 9 (released in June 2020) will also be unsupported as of November 2023.<\/p><p>This is because of its dependency on Symfony 4, which is ending its security support in November.<\/p><p>Drupal 10 was released in December 2022 and will be the main version until Drupal 11 is released in 2024.<\/p><p>Luckily, major upgrades of Drupal are much easier these days, with no large code rewrite or data migration required.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "A minor breaking change",
"date": "1684540800",
"permalink": "/archive/2023/05/20/a-minor-breaking-change",
"text": "<p>Today, in the repository of an open-source project, I saw an issue comment saying, \"This is a minor breaking change.\".<\/p><p>It detailed what was removed and suggested an alternative.<\/p><p>I don't know how you define a \"minor\" breaking change.<\/p><p>Is it because it's a single line and easy to replace, or is it part of the code that is rarely used by consumers and less likely to cause an issue?<\/p><p>Regardless, if it's a breaking change, anyone using that project will need to update their code if they use something that was removed, whether it's minor or not.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Semantic versioning",
"date": "1684454400",
"permalink": "/archive/2023/05/19/semantic-versioning",
"text": "<p>The version number of a release is a key indicator of whether it\u2019s compatible with existing code.<\/p><p>Semantic versioning is a popular approach used by Drupal core, and many contributed modules, themes and distributions.<\/p><p>It uses version numbers like 1.0.0 to show the major, minor and patch versions.<\/p><p>If the second or third number changes, e.g. 1.1.0 or 1.0.1, the release contains new backwards-compatible features or fixes, so it\u2019s safe to update.<\/p><p>If the first number changes, e.g. 2.0.0, the release is not backwards compatible and contains breaking changes that you\u2019ll need to review and update your code accordingly.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Why is backward compatibility important?",
"date": "1684368000",
"permalink": "/archive/2023/05/18/why-is-backward-compatibility-important",
"text": "<p>In yesterday's email, I mentioned that deprecating code allows it to be backwards compatible - but what does that mean?<\/p><p>If I were to remove a function like <code>drupal_set_message()<\/code> that is used code elsewhere in an application, the code would no longer work and would break.<\/p><p>As a module or library maintainer, I don't want to cause applications to break by making backward incompatible changes (a \"BC break\" or a \"breaking change\").<\/p><p>Maintaining backward compatibility means that people who use the code can update to the latest version without breakages, and if they use any deprecated code, they know to update it to be compatible with future versions.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "What is deprecated code?",
"date": "1684281600",
"permalink": "/archive/2023/05/17/what-is-deprecated-code",
"text": "<p>Deprecating code is a way of identifying code that will be removed in a future major version.<\/p><p>For example, the <code>drupal_set_message()<\/code> function was deprecated in Drupal 8.5 and removed in Drupal 9 as the <code>messenger<\/code> service replaced it.<\/p><p>Once it was deprecated, the function was changed to use the new service to avoid duplicating code and a message was added to notify Developers:<\/p><pre><code class=\"language-php\">function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) { @trigger_error('drupal_set_message() is deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0. Use \\Drupal\\Core\\Messenger\\MessengerInterface::addMessage() instead. See https:\/\/www.drupal.org\/node\/2774931', E_USER_DEPRECATED); $messenger = \\Drupal::messenger(); if (isset($message)) { $messenger-&gt;addMessage($message, $type, $repeat); } return $messenger-&gt;all();}<\/code><\/pre><p>This approach means that code can be refactored without breaking backwards-compatibility and, to upgrade any custom code to be compatible with Drupal 9, any references to <code>drupal_set_message()<\/code> just needed to be updated to use the new Messenger service.<\/p><p>No large rewrite needed!<\/p>",
"cta": "",
"tags": ["php","drupal","software-development"]
}, {
"title": "Mastering your tools improves productivity",
"date": "1684195200",
"permalink": "/archive/2023/05/16/mastering-your-tools-improves-productivity",
"text": "<p>Spending time to learn and master your tools, whether it's your IDE or text editor, CMS or framework, or something else that you use regularly like Git, spending time to expand on the basics and learn it more thoroughly is an investment in your future.<\/p><p>I try to keep up to date with the latest additions and changes to Drupal and the PHP language so that I can be more productive and write better and cleaner code.<\/p><p>I invest time to make my development environment and tools work as effectively and efficiently as possible. If I can make it easier and quicker to perform simple tasks like navigating to and creating files, and scaffolding new content within them, that time will be paid back in future time saved.<\/p><p>If I find a new plugin, module, theme or tool that will make future tasks easier - even something as easy as commenting out a line or block of code - putting aside some time to investigate and evaluate it and decide if I want to use it is time well spent.<\/p><p>As someone said in a video recently, \"you invest time now to buy back time later\".<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Is the Drupal release cycle too fast?",
"date": "1684108800",
"permalink": "/archive/2023/05/15/is-the-drupal-release-cycle-too-fast",
"text": "<p>Compared to Drupal 7, <a href=\"https:\/\/oliverdavies.dev\/archive\/2023\/04\/30\/will-we-see-drupal-7-100\">which is almost at version 100<\/a>, the release cycle from Drupal 9 onwards has been quite different.<\/p><p>We've adopted semantic versioning with new feature releases every six months, and we've already sunsetted Drupal 8 and moved on to Drupal 9 and 10.<\/p><p>Major versions are released more quickly, with Drupal 9 support ending in November 2023 and Drupal 11 potentially being released in May or November 2024.<\/p><p>But is it too quick, as someone asked on Twitter?<\/p><p>The main reason I'm aware of is to keep in sync with major versions of projects that Drupal uses, such as the components used by Symfony. As they update and release new major versions, we also need to do so.<\/p><p>As a module and theme maintainer, I don't think it's too fast and have been happy with the number of changes to upgrade them and make them Drupal 10 compatible. In most cases, I only had to change the <code>core_version_requirement<\/code> key to include the new version.<\/p><p>It depends on how well the project is maintained during the earlier versions. If you keep up to date with changes in minor versions and remove any deprecated code, there will be less to do in the future.<\/p><p>The same applies to any custom code within website projects, not just contributed modules and themes.<\/p><p>The more often you maintain and update what you have; the easier it will be.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "Releasing small changes often is less risky",
"date": "1684022400",
"permalink": "/archive/2023/05/14/releasing-small-changes-often-is-less-risky",
"text": "<p>Contrary to what many think (at least to begin with), releasing small, incremental changes often - maybe daily or weekly - is less risky than larger releases containing weeks or months of changes.<\/p><p>If there is an issue after a large release, diagnosing and fixing it can take longer than a smaller release with fewer changes.<\/p><p>You might have to revert and roll back to the previous release instead of being able to push a fix for a small change.<\/p><p>With a small change, the risk of an issue is much lower as it has less chance to impact any other part of the application and is much easier for others to read, understand and debug.<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "When You Do Things Right, People Won&#039;t Be Sure You&#039;ve Done Anything at All",
"date": "1683936000",
"permalink": "/archive/2023/05/13/when-you-do-things-right",
"text": "<p>I think this quote from Futurama also applies well to software development:<\/p><blockquote> <p>When You Do Things Right, People Won\u2019t Be Sure You\u2019ve Done Anything at All<\/p><\/blockquote><p>Today I did multiple releases to production websites. There were no outages or downtime, or messages from clients or colleagues.<\/p><p>Processes were followed, and everything worked as it should. As far as everyone's concerned, everything still \"just works\".<\/p><p>So, did I do anything at all?<\/p>",
"cta": "",
"tags": ["software-development"]
}, {
"title": "Always listen to the mob",
"date": "1683849600",
"permalink": "/archive/2023/05/12/always-listen-to-the-mob",
"text": "<p>Something I'm aware of when working in a pair or mob is to always listen to input from other team members.<\/p><p>A pair or mob session isn't just focused on one person's ideas or solution. It's a collaborative effort based on everyone's input, experience and ideas.<\/p><p>If there are conflicting or different ideas or approaches, they can be discussed, and everyone can agree on the way forward. Approaches may also change as you learn more together during the session.<\/p><p>Together, you will come up with the best solution - even if it's different from what you had in mind to begin with.<\/p>",
"cta": "",
"tags": ["pair-programming","mob-programming"]
}, {
"title": "Why I like pair and mob programming",
"date": "1683763200",
"permalink": "/archive/2023/05/11/why-i-like-pair-and-mob-programming",
"text": "<p>When working as part of a team, I like to do pair or mob programming as much as possible.<\/p><p>I like being able to give and receive feedback in real-time; everyone can contribute to the solution and more shared knowledge, so there's less siloing, and it's much harder to block multiple people than a single person.<\/p><p>Working in pairs or a mob is a great opportunity to onboard new team members, train and mentor, and share tips and tricks.<\/p><p>It's usually more productive than working separately, and it's nice to speak and socialise with other team members whilst working on a task.<\/p>",
"cta": "",
"tags": ["pair-programming","mob-programming"]
}, {
"title": "Tailwind CSS makes change easier",
"date": "1683676800",
"permalink": "/archive/2023/05/10/tailwind-css-makes-change-easier",
"text": "<p>CSS usually has a global scope which can make change risky.<\/p><p>How do you know that changing CSS in a global stylesheet to fix a bug won't cause more elsewhere?<\/p><p>Tailwind CSS and utility classes change CSS to a local scope.<\/p><p>You can see what styling is applied to an element by looking at its classes and easily make changes without worrying that it will cause unexpected issues elsewhere.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "The single responsibility principle",
"date": "1683590400",
"permalink": "/archive/2023/05/09/the-single-responsibility-principle",
"text": "<p>Today, I added a new feature to a project that allows a member to search for a node based on either its title or a specified field on that node, select a result from an autocomplete list and then be redirected to their selected node.<\/p><p>I've already implemented this for other node types but needed to do the same for this node type.<\/p><p>There are some differences, such as the node type to query for; the additional field depends on which node type as does the text shown in the autocomplete list.<\/p><p>To do this, I needed to add a custom block and form, update the <code>AutocompleteController<\/code>, create a new instance of a <code>NodeQuery<\/code> class (a custom class within the custom module), register it as a service and update the <code>SearchQueryFactory<\/code> class.<\/p><p>A principle that I follow as much as possible is the single responsibility principle, or SRP (the 'S' in SOLID), where each function or class only has one responsibility - such as returning a response for the autocomplete list, determining the correct node query to use based on the search being run or building the query itself - these are separated and split into their own files.<\/p><p>Although more files and functions are created when coding in this way, though they are smaller and more straightforward to work with - which makes them easier to read, debug and maintain. It also makes code like the node query classes reusable as they aren't embedded within a larger class and are easier to test.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Only write enough code to get a failing test",
"date": "1683504000",
"permalink": "/archive/2023/05/08/only-write-enough-code-to-get-a-failing-test",
"text": "<p>Instead of writing a whole test and then attempting to make it pass, only write enough code to get the test to fail.<\/p><p>This could be by starting with a failing assertion that is fixed with a hard-coded value and then iterating on the test to introduce the next failure before repeating the process.<\/p><p>This allows you to keep the feedback loop small and not write more code than is needed, to focus on the objective of the test, and not code yourself into a corner.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "You don&#039;t need to think about what to do next",
"date": "1683417600",
"permalink": "/archive/2023/05/07/you-dont-need-to-think-about-what-to-do-next",
"text": "<p>When practising test-driven development, you don't need to think about what to do next.<\/p><p>If you have a failing test, the objective is to get that test to pass as quickly and simply as possible, and you rely on the error from the failing test to tell you the next step.<\/p><p>It could be a failing assertion, an undefined variable or function, or a yet-to-be-implemented service.<\/p><p>Once you've fixed that error, the test will either pass or fail. If it fails, you'll have a new error and know the next step.<\/p><p>When working in this way, it's like being on autopilot. You can focus only on fixing each error until the feature or fix is complete and the test is passing.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Why it&#039;s important to see the test fail",
"date": "1683331200",
"permalink": "/archive/2023/05/06/why-its-important-to-see-the-test-fail",
"text": "<p>With automated testing and test-driven development, it's important to see a test fail.If a test passes straight away, how do you know that you're testing the right thing? You could be accidentally testing a different piece of functionality, or it could be a false positive.<\/p><p>If the functionality already exists, do you need another test for it?<\/p><p>When you see a test fail, you know that the functionality hasn't been implemented, that you're testing the correct thing, and you have a clear goal to work towards.<\/p><p>If you're fixing a bug, writing a test and seeing it fail verifies the bug exists and that, once the bug is fixed, the test will pass.<\/p><p>Usually, you can anticipate why a test will fail as it evolves and know when it will pass. If a test passes before I expect, I'm immediately sceptical and will look into why rather than assuming it passed for the right reasons.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Getting to green",
"date": "1683244800",
"permalink": "/archive/2023/05/05/getting-to-green",
"text": "<p>When doing test-driven development, once you've written a failing (a.k.a. red) test, the main objective is to get to a green (a.k.a. passing) test as quickly as possible via the simplest method.<\/p><p>Even if that means returning a hard-coded value.<\/p><p>Once the test passes, it or the code it's testing can be refactored.<\/p><p>Or you can move on to the next test and, if you need to change the hard-coded value to get both tests to pass, then it is the right time to do so.<\/p>",
"cta": "",
"tags": ["automated-testing","testing","test-driven development"]
}, {
"title": "Speaking at the Symfony UK meetup in London",
"date": "1683158400",
"permalink": "/archive/2023/05/04/speaking-at-the-symfony-uk-meetup-london",
"text": "<p>After registering as an attendee, I've been upgraded to a speaker for next week's event and the first in-person Symfony UK meetup in two years.<\/p><p>I'll be speaking about my experiences so far with mob programming - something that I spoke about at a PHP South Wales meetup last year.<\/p><p>If you're interested and in London on the 11th of May, <a href=\"https:\/\/www.meetup.com\/symfony\/events\/293153957\">find out more and register<\/a>.<\/p><p>Also, Happy Star Wars Day!<\/p>",
"cta": "",
"tags": ["speaking","mob-programming","php","phpc","symfony"]
}, {
"title": "Just because core is supported...",
"date": "1683072000",
"permalink": "/archive/2023/05/03/just-because-core-is-supported",
"text": "<p>Just because Drupal core is supported, it doesn't mean that all of the other modules your project uses are still also supported or actively worked on.<\/p><p>Since the Drupal 8 release in 2015, I've seen numerous examples of modules that haven't been updated for some time as maintainers focus on writing and maintaining the versions for Drupal 8 and now 9 and 10.<\/p><p>Whilst it isn't marked as unsupported, it isn't being updated either.<\/p><p>I recently explained to a client that their site uses a module last released in 2014. It\u2019s buggy, but there\u2019s no newer version to use and issues in the queue are no longer being fixed or triaged.<\/p><p>Override Node Options - a popular module I maintain - is in a similar situation. The most recent Drupal 9\/10 version was in February 2023, whereas the last Drupal 7 release was in March 2018.<\/p><p>I don't have any official figures to support this, but feel the contribution rate for Drupal 7 projects (as in modules, themes and distributions) has been slowing for some time.<\/p><p>Meanwhile, Drupal 7 core is still supported, at least for now.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "Does it depend on who you ask?",
"date": "1682985600",
"permalink": "/archive/2023/05/02/does-it-depend-on-who-you-ask",
"text": "<p>The answer to \"<a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/05\/01\/should-drupal-7-support-be-extended-again\">Should Drupal 7 support be extended again?<\/a>\" might depend on who you ask.<\/p><p>If you ask a Developer or agency, the answer would likely be that it shouldn't be extended again, and D7 should be sunsetted.<\/p><p>Clients and end-users who haven't yet upgraded would likely say it should be extended.<\/p><p>But if it's extended - and maybe again next year and the next - where's the incentive to upgrade?<\/p><p>Some people won't upgrade regardless and will continue until their site breaks.<\/p><p>That would be messy (and costly) to fix, though!<\/p><p>P.S. Are you still using Drupal 7 and don\u2019t know what\u2019s involved to upgrade to Drupal 10? Book a <a href=\"https:\/\/www.oliverdavies.uk\/call\">Drupal 7 upgrade consultation call<\/a>.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "Should Drupal 7 support be extended again?",
"date": "1682899200",
"permalink": "/archive/2023/05/01/should-drupal-7-support-be-extended-again",
"text": "<p>Drupal 7, which was released in 2011, was originally supposed to be end-of-life in November 2022.<\/p><p>This would mean there would be no more Drupal 7 versions and there would be no further support or bug fixes from the core Developer team.<\/p><p>However, in February 2022, support was extended until November 2023 with a potential for it to be extended by another 12 months, which would be announced by July 2023.<\/p><p>There are still over 425,000 active Drupal 7 websites according to <a href=\"https:\/\/www.drupal.org\/project\/usage\/drupal\">https:\/\/www.drupal.org\/project\/usage\/drupal<\/a> - almost 100,000 fewer than Feburary 2022. That's still a lot of websites!<\/p><p>Should support be extended again or should Drupal 7 be marked as end-of-life and unsupported?<\/p><p>If so, those websites will continue to work, and an argument could be made that there's been enough time to upgrade projects since Drupal 8's first release in 2015.<\/p><p>That said, it's a tricky upgrade - migrating data into a new Drupal website and re-writing custom modules and themes to make them compatible.<\/p><p>It's definitely work upgrading, in my opinion, as the updates between Drupal 8, 9 and 10 are much simpler and quicker, and don't involve large rewrites or data migrations.<\/p><p>Hit reply and let me know what you think.<\/p><p>P.S. Are you still using Drupal 7 and don\u2019t know what\u2019s involved to upgrade to Drupal 10? Book a <a href=\"https:\/\/www.oliverdavies.uk\/call\">Drupal 7 upgrade consultation call<\/a>.<\/p>",
"cta": "",
"tags": ["drupal","php","phpc"]
}, {
"title": "Will we see Drupal 7.100?",
"date": "1682812800",
"permalink": "/archive/2023/04/30/will-we-see-drupal-7-100",
"text": "<p>Drupal 7, first released in January 2011, is now on version 7.97.<\/p><p>As things stand, it's supported until November 2023, which makes me wonder whether we'll see the first version of Drupal to get 100 releases.<\/p><p>It was originally supposed to be end-of-life in November 2022, I also wonder if it'll be extended again and whether it should be.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Write the test backwards",
"date": "1682553600",
"permalink": "/archive/2023/04/27/tdd-write-the-test-backwards",
"text": "<p>When writing a test, something that I like to do is start by writing the first assertion first, and then work backwards.<\/p><p>My first assertion might be <code>self::assertTrue($result)<\/code>.<\/p><p>If I ran this test, it would fail because of the undefined <code>$result<\/code> variable - but it's clear to me what I need next by asking, \"Where does <code>$result<\/code> come from?\".<\/p><p>If I need to call a method on another class and get the result, I'll add it before the assertion. Then I repeat the process and ask, \"What do I need for this to work?\".<\/p><p>Maybe I need to create some users or content in the application for the class to query and return a result based on it, so I'll create those.<\/p><p>With this approach, I'm not making any assumptions about the test's prerequisites, and I usually find that I end up with cleaner and more focused tests.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Structure a new test by writing comments first",
"date": "1682467200",
"permalink": "/archive/2023/04/26/tdd-structure-a-new-test-by-writing-comments-first",
"text": "<p>Test cases are usually split into two or three sections - \"Arrange, Act, Assert\" or \"Given, When, Then\".<\/p><p>If the test has a prerequisite, such as some users or content to be created or in a given state, you create the required environment for the test. With unit tests, this would include mocking any dependencies you need to use.<\/p><p>Then you perform an action on the subject under test and, finally, assert that the system is in the desired state.<\/p><p>Maybe a user was pending initially, and they're active after running a command or a cron task. You can assert the initial state of the user as well as the final state to ensure the action did what it was supposed to do.<\/p><h2 id=\"option-1\">Option 1<\/h2><p>To help me get started, I'll sometimes write a test like this with placeholders to separate the test into its separate stages:<\/p><pre><code class=\"language-php\">\/** @test *\/function should_activate_a_pending_user(): void { \/\/ Arrange. \/\/ Act. \/\/ Assert.}<\/code><\/pre><p>This makes me think about the different stages and what each might need to contain.<\/p><h2 id=\"option-2\">Option 2<\/h2><p>Or I might write it out in the \"Given, When, Then\" format:<\/p><pre><code class=\"language-php\">\/** @test *\/function should_activate_a_pending_user(): void { \/\/ Given I have a user. \/\/ And the user is pending. \/\/ When I run the user update command. \/\/ Then the user should no longer be 'pending'. \/\/ And the user status should be 'active'.}<\/code><\/pre><p>This takes a little longer to write but feels more familiar if you're used to a behavioural testing framework like Behat.<\/p><p>Either way, sometimes, I'll remove the comments once I've written the code around them or leave them to provide additional context.<\/p>",
"cta": "",
"tags": ["automated-testing","test-driven-development"]
}, {
"title": "Shortening the feedback loop even more",
"date": "1682380800",
"permalink": "/archive/2023/04/25/shortening-the-feedback-loop-even-more",
"text": "<p>Yesterday's email was about shortening the feedback loop of a CI pipeline by running some of the checks like PHPCS and PHPStan locally and dealing with any errors before they get pushed to the code repository.<\/p><p>What's even better than writing and committing code and then waiting until just before pushing it to test it? Seeing the errors in real-time and being able to fix them immediately.<\/p><p>In my Neovim setup (I talked about this at the PHP London meetup recently), I have the Intelephense language server configured to add IDE-like features such as code completion, go-to definition, symbol renaming, etc.<\/p><p>I also have another plugin - <code>null-ls.nvim<\/code> - that adds errors from command-line tools to Neovim's diagnostics list.<\/p><p>So, if I try to do something that would cause a PHPStan failure, such as using an unknown variable or missing a return type, I can see that and fix it immediately and not even wait for a Git hook to run.<\/p>",
"cta": "",
"tags": ["development","devops","neovim"]
}, {
"title": "CI pipelines should start locally",
"date": "1682294400",
"permalink": "/archive/2023/04/24/ci-pipelines-should-start-locally",
"text": "<p>This week, Solomon Hykes (@solomonstre on Twitter) said:<\/p><blockquote> <p>Your CI\/CD pipeline should start on the developer's laptop. If it only starts after a git push, you're slowing your team down and throwing money down the drain.<\/p><\/blockquote><h2 id=\"what-does-this-mean%3F\">What does this mean?<\/h2><p>My interpretation of this is that if a pipeline is going to fail, and fail for something that could been easily tested locally, then it should have been tested and fixed locally rather than waiting to push the changes to a CI pipeline, watch it fail there, and then need to push a fix and go through the process again.<\/p><p>In PHP projects, a common CI pipeline failure after working on a change is that PHPCS (code style) or PHPStan (static analysis) checks will fail - even though the feature, fix or refactor is working. If those checks can be run locally to shorten the feedback loop and allow the error to be fixed before the pipeline runs, it would be better to do so.<\/p><h2 id=\"my-preferred-solution\">My preferred solution<\/h2><p>My approach for this is using Git hooks - specifically on a pre-push event.<\/p><p>These are scripts that run automatically before the commits are pushed, and if it fails, it prevents the push and allows you to fix the issue.<\/p><p>They're easy to enable using a command like <code>git config core.hooksPath .githooks<\/code> (assuming the scripts are in a directory called <code>.githooks<\/code>), and whilst I wouldn't run everything that I would in a CI pipeline, I would run tasks like PHPCS and PHPStan checks, and maybe the unit and integration tests if they're fast to run.<\/p><p>Anything that would take a longer time to run, like functional or behavioural tests, would only be executed within the pipeline, but for common failures like PHPCS and PHPStan errors, these can be quickly fixed locally and not pushed to a CI pipeline at all.<\/p><p><a href=\"https:\/\/twitter.com\/solomonstre\/status\/1649118014594502656\">Here is Solomon's original tweet<\/a>.<\/p>",
"cta": "",
"tags": ["development","devops","git"]
}, {
"title": "Laravel Pipelines",
"date": "1682208000",
"permalink": "/archive/2023/04/23/laravel-pipelines",
"text": "<p>I've seen a lot on social media and posts and videos recently about Laravel Pipelines - functionality that's been present in Laravel and used within the framework for some time - but there was only documentation added for it last month as part of the Laravel 10 release.<\/p><p>This is an example from the new documentation:<\/p><pre><code class=\"language-php\">$user = Pipeline::send($user) -&gt;through([ GenerateProfilePhoto::class, ActivateSubscription::class, SendWelcomeEmail::class, ]) -&gt;then(fn (User $user) =&gt; $user);<\/code><\/pre><p>Once a user has registered, it is passed through different classes - each performing a task and calling the next class in the list, similar to middleware. Once finished, a final action is performed or a value is returned.<\/p><p>As someone who doesn't use Laravel often but does use standalone components - like <code>illuminate\/collections<\/code> - in other PHP projects, I'm interested to see how I can use this via <code>illuminate\/pipeline<\/code> to refactor some of my existing code.<\/p>",
"cta": "",
"tags": ["php","laravel"]
}, {
"title": "Configuration files as a service",
"date": "1682121600",
"permalink": "/archive/2023/04/22/build-configs-as-a-service",
"text": "<p>After using my \"build-configs\" tool to generate and manage configuration files for several personal and client Drupal projects for the past few months, I'm offering it as a product to purchase.<\/p><p>I can provide an initial Drupal project skeleton built using <code>build-configs<\/code>, and for a recurring monthly amount, ongoing updates and unlimited support via Slack.<\/p><p>I can retrofit it to an existing codebase, but as this will be different every time, I'll need more information to give a price.<\/p><p>See https:\/\/www.oliverdavies.uk\/build-configs for more information and, as a list subscriber, use the code <code>dailyconfigs<\/code> to get an early-bird discount.<\/p>",
"cta": "",
"tags": ["development","devops","drupal","php"]
}, {
"title": "Making my Drupal module template Drupal 10 compatible",
"date": "1682035200",
"permalink": "/archive/2023/04/21/making-my-drupal-module-template-drupal-10-compatible",
"text": "<p>Today, I made my <a href=\"https:\/\/github.com\/opdavies\/drupal-module-template\">Drupal module template<\/a> compatible with Drupal 10.<\/p><p>Because Drupal 10 is developed from Drupal 9, the changes between the two and the changes required are minimal.<\/p><p>In this case, I only needed to change the <code>core_version_requirement<\/code> in <code>drupal_module_template.info.yml<\/code> from <code>^9<\/code> to <code>^9 || ^10<\/code> - meaning the template works for both Drupal 9 and 10, so there's no need for different versions.<\/p><p>If it used any deprecated code that was removed before Drupal 10, I'd have needed to update it to use the Drupal 10-compliant code.<\/p><p>Updating to new major Drupal versions is much easier than it used to be!<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Micro-refactorings",
"date": "1681948800",
"permalink": "/archive/2023/04/20/micro-refactorings",
"text": "<p>Today, I saw a <a href=\"https:\/\/www.linkedin.com\/posts\/petermorlion_refactoring-technicaldebt-softwaredevelopment-activity-7054378097051095040-I545\">LinkedIn post by Peter Morlion<\/a>, in which he describes micro-refactoring - very small and safe refactors like renaming a variable, moving a method in a file to a more logical place, or adding a comment.<\/p><p>He says that micro-refactors are safer than big refactors and have less chance of introducing a regression, are easy to do, improve the code quality over time, make larger refactorings easier later, increase the readability of your code, and reduce technical debt bit by bit.<\/p><h2 id=\"what%27s-the-issue%3F\">What's the issue?<\/h2><p>I agree with what Peter says and also encourage people to make small refactors to the code they're working on and follow the \"<a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/12\/22\/the-boy-scout-rule\">Boy Scout rule<\/a>\".<\/p><p>The main blocker to this I've seen is Git workflows that require people to work in separate branches that need to be reviewed before being merged, as this slows down the process.<\/p><p>As Peter also says, micro-refactorings can be done anytime while working on other tasks. This is hard to do if each refactor requires its own branch and pull request, and the number of pull requests would quickly become unmanageable and take time to review.<\/p><p>If I know that a micro-refactor like renaming a variable is going to take hours, days or weeks to be reviewed and merged, I'd probably be less likely to do the refactor in the first place. Not to mention having to update my working code once it's been merged.<\/p><h2 id=\"what-do-i-prefer-to-do%3F\">What do I prefer to do?<\/h2><p>I prefer to follow trunk-based development where everyone commits to a single branch and continuous integration where everyone is committing, pushing and pulling changes often - removing the need for merging branches and merge conflicts.<\/p><p>Instead of asynchronous code review, I prefer to pair- or mob-program or to rely on automation with CI\/CD pipelines.<\/p><p>If the commit before my change is passing the pipeline checks, and they're still passing after my change, they're good to deploy.<\/p><p>Making the process as frictionless as possible encourages people to make small changes and micro-refactors, and to make codebases better a small piece at a time.<\/p>",
"cta": "",
"tags": ["refactoring","technical-debt","programming"]
}, {
"title": "Camel-case or snake-case for Drupal code?",
"date": "1681862400",
"permalink": "/archive/2023/04/19/camel-case-or-snake-case-for-drupal-code",
"text": "<p>For some time, <a href=\"https:\/\/www.drupal.org\/docs\/develop\/standards\/php\/php-coding-standards#s-functions-and-variables\">Drupal's PHP coding standards<\/a> allows for writing variables in either snake-case (e.g. <code>$my_variable<\/code>) or lower camel-case (<code>e.g. $myVariable<\/code>).<\/p><p>It originally only allowed for snake-case variable names but once it accepted both, I switched to camel-case as my default.<\/p><p>Why? I didn't like the inconsistency of using one approach for variable names and one for method and property names in PHP classes (which were always camel-case).<\/p><p>I'd have had code like this with a mixture of both:<\/p><pre><code class=\"language-php\">class MyClass { private EntityTypeManagerInterface $entityTypeManager; public function __construct(EntityTypeManagerInterface $entity_type_manager) { $this-&gt;entityTypeManager = $entity_type_manager; }}<\/code><\/pre><p>Or even more simply:<\/p><pre><code class=\"language-php\">$entity_type_manager = \\Drupal::entityTypeManager();<\/code><\/pre><p>I prefer not to have to consistently think about which to use and, if possible, like to use standard approaches in different codebases whether I'm working on a Drupal project, a Symfony project, or a PHP library.<\/p><p>Plus, I get to use new PHP features like <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/04\/12\/cleaner-php-code-with-promoted-constructor-properties\">promoted constructor properties<\/a> if everything is named in the same format.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Consistency is key",
"date": "1681776000",
"permalink": "/archive/2023/04/18/consistency-is-key",
"text": "<p>A side effect of <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/03\/04\/why-i-built-a-tool-to-generate-configuration-files\">using a tool to generate build configuration files<\/a> with templates is the consistency that it introduces.<\/p><p>The majority of my projects use a PHP-FPM or PHP CLI container. In my Docker Compose file, the service was mostly named <code>php<\/code> but sometimes it was <code>php-fpm<\/code>. In the templated file, it's always named <code>php<\/code>.<\/p><p>Some projects would use <code>mysql<\/code> or <code>mariadb<\/code> for the database service and <code>nginx<\/code> or <code>caddy<\/code> depending on which server was being used. These are now always <code>database<\/code> and <code>web<\/code> respectively.<\/p><p>As well as being easier to switch between projects and not having to think about which names are used in each codebase, it's also much easier to write tools and automation when the names are consistent.<\/p><p>For example, I'd always write a long-ish command to import a database file - reading and unzipping it, and importing it by connecting to the database running in its container. The command would essentially be the same with slight changes based on that project - such as the database service name.<\/p><p>Now the command is the same for all projects, and I can automate it by writing a script that works on any project meaning I no longer need to write the long command at all.<\/p>",
"cta": "",
"tags": ["automation","devops","docker"]
}, {
"title": "Introducing feature flags to &quot;build-configs&quot;",
"date": "1681689600",
"permalink": "/archive/2023/04/17/introducing-feature-flags-to-build-configs",
"text": "<p>Yesterday, I wanted to make a breaking change to my <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/03\/04\/why-i-built-a-tool-to-generate-configuration-files\">build-configs project<\/a> - changing the default database credentials that are used by Docker Compose.<\/p><p>As I have several projects based on generated files by the tool, changing the values could cause issues in those projects in the future and this is something that I wanted to avoid.<\/p><h2 id=\"what-did-i-do%3F\">What did I do?<\/h2><p>To avoid this issue and needing to update all of my projects at once, I added a feature flag to the <code>build.yaml<\/code> file so I can opt-in to this feature on a per-project basis.<\/p><p>If a project, like my <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal\">Drupal<\/a> and <a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal-localgov\">LocalGov Drupal<\/a> Docker examples, are opted in, its files will get the new credentials. If not, it will continue to use the original ones.<\/p><p><a href=\"https:\/\/github.com\/opdavies\/docker-example-drupal\/commit\/3f496168d5c32f9706970519023b431ee02c4b19\">In this commit<\/a>, you'll see where I enabled the feature flag and committed the resulting change.<\/p><h2 id=\"what-does-this-achieve%3F\">What does this achieve?<\/h2><p>I can continue to work on existing projects without them breaking, and migrate projects one at a time by using the feature flag instead of needing to do them all once.<\/p><p>Once all active projects have been migrated or completed, the feature flag can be removed and I can refactor and simplify the code - removing the feature flag and the legacy values.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Refactoring with readonly classes in PHP 8.2",
"date": "1681603200",
"permalink": "/archive/2023/04/16/refactoring-with-readonly-classes-in-php-8-2",
"text": "<p>Marian Kostadinov (<a href=\"https:\/\/twitter.com\/stochnagara\">stochnagara on Twitter<\/a>) replied to Friday's email about DTOs and value objects to tell me about <code>readonly<\/code> classes, which can be done in PHP 8.2.<\/p><p>Looking at the previous class:<\/p><pre><code class=\"language-php\">class AccountDetails { public function __construct( public readonly string $accountNumber, public readonly string $sortCode, ) {}}<\/code><\/pre><p>Instead of setting each property as <code>readonly<\/code>, the whole class can instead be marked as <code>readonly<\/code>:<\/p><pre><code class=\"language-php\">readonly class AccountDetails { public function __construct( public string $accountNumber, public string $sortCode, ) {}}<\/code><\/pre><p>Thanks for the suggestion, Marian!<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Automatically running commands with nodemon",
"date": "1681516800",
"permalink": "/archive/2023/04/15/automatically-running-commands-with-nodemon",
"text": "<p>Instead of running the same commands over and over again, some of the command-line tools that I use have a <code>watch<\/code> mode and will automatically re-run when files are changed, however, not all do.<\/p><p>Instead of doing this manually, I can achieve the same thing though using a tool called <code>nodemon<\/code> - a script monitor for node projects, but it can work with non-node projects too.<\/p><p>Here's an example where I'm automatically re-running my PHPUnit tests using a <code>just test<\/code> recipe each time a file within my custom modules directory changes:<\/p><pre><code>nodemon \\ --watch web\/modules\/custom \\ --ext '*' \\ --exec \"just test --stop-on-failure --colors=always\"<\/code><\/pre><p>I specify the files or directories I want to watch, which file extensions should trigger a restart (in this case, I've enabled all extensions), and the command to execute.<\/p><p>This watches all files and run all of the tests, but I can filter either if I need to.<\/p><p>As well as PHP tools like PHPUnit and PHPStan, I also use this for other things such as when creating presentation slides with rst2pdf where I can automatically re-generate the PDF whenever I update the rst file.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Data transfer objects and value objects",
"date": "1681430400",
"permalink": "/archive/2023/04/14/data-transfer-objects-and-value-objects",
"text": "<p>In the last few emails, we've seen a data transfer object called <code>AccountDetails<\/code> that stores the account number and sort code for a bank account.<\/p><p>A data transfer object only stores data but we could also use a value object that can do more tasks, like validating the values.<\/p><p>For example, we could validate that the account number is the correct length and the sort code is the correct format:<\/p><pre><code class=\"language-php\">class AccountDetails { public function __construct( public readonly string $accountNumber, public readonly string $sortCode, ) { \/\/ Validate the account number. if (!preg_match('\/^\\d{8}$\/', $accountNumber)) { throw new \\InvalidArgumentException('Account number must be an 8-digit number'); } \/\/ Validate the sort code. if (!preg_match('\/^\\d{2}-\\d{2}-\\d{2}$\/', $sortCode)) { throw new \\InvalidArgumentException('Sort code must be in the format 00-00-00'); } }}<\/code><\/pre><p>Helper methods can also be added to a value object as long as they don't modify the state of the object, such as getting the raw sort code without the separating dashes or performing further checks on the input values.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Immutable read-only properties in PHP 8.1",
"date": "1681344000",
"permalink": "/archive/2023/04/13/immutable-read-only-properties-in-php-8-1",
"text": "<p>Continuing with yesterday's data transfer object (DTO) example, something that can be done since PHP 8.1 is to make properties read-only:<\/p><pre><code class=\"language-php\">class AccountDetails { public function __construct( public readonly string $accountNumber, public readonly string $sortCode, ) {}}<\/code><\/pre><p>This means the public properties can be read and used without the need for getter methods, but cannot be overridden - making the DTO immutable.<\/p><p>Without <code>readonly<\/code>, a DTO can be created and the property values can be changed:<\/p><pre><code class=\"language-php\">$accountDetails = new AccountDetails('12345678', '00-00-00');$accountDetails-&gt;accountNumber = 'banana';<\/code><\/pre><p>With <code>readonly<\/code> set, you'd get a fatal error instead:<\/p><blockquote> <p>Fatal error: Uncaught Error: Cannot modify readonly property AccountDetails::$accountNumber in \/home\/opdavies\/tmp\/example.php:13<\/p><\/blockquote>",
"cta": "",
"tags": ["php"]
}, {
"title": "Cleaner PHP code with promoted constructor properties",
"date": "1681257600",
"permalink": "/archive/2023/04/12/cleaner-php-code-with-promoted-constructor-properties",
"text": "<p>One of my favorite features that was introducted in PHP 8 was promoted constructor properties.<\/p><p>If I'm passing arguments into a constructor, I can declare a visibility and it will be promoted to a property on the class.<\/p><p>Here's an example of a value of a data transfer object that accepts a sort code and account number as strings:<\/p><pre><code class=\"language-php\">class AccountDetails { public function __construct( public string $accountNumber, public string $sortCode, ) {}}<\/code><\/pre><p>Without promoted constructor properties, I'd need to create the properties and assign them manually, and I'd have this:<\/p><pre><code class=\"language-php\">class AccountDetails { public string $accountNumber; public string $sortCode; public function __construct( string $accountNumber, string $sortCode, ) { $this-&gt;accountNumber = $accountNumber; $this-&gt;sortCode = $sortCode; }}<\/code><\/pre><p>Whilst text editors and IDEs can create the properties automatically, I prefer this as it's less code, more readable and easier to understand.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "just vs make",
"date": "1681171200",
"permalink": "/archive/2023/04/11/just-vs-make",
"text": "<p><code>just<\/code> compared to <code>make<\/code> is something that was asked during my PHP London talk, and whilst they are similar, <code>just<\/code> has differences for me that explains why I use it:<\/p><h2 id=\"tabs-or-spaces\">Tabs or spaces<\/h2><p>A Makefile needs to use tabs. Justfiles are more flexible and work with tabs or any number of spaces.<\/p><h2 id=\".phony\">.PHONY<\/h2><p>With a Makefile, you need to declare some targets as \"phony\". I believe that this is for targets that don't generate artifact files with that name, so as I'm not compiling and building files with <code>make<\/code>, this is redundant and adds visual noise.<\/p><h2 id=\"passing-arguments\">Passing arguments<\/h2><p>This is how a <code>composer<\/code> target looks like in a Makefile:<\/p><pre><code class=\"make\">composer: docker compose exec php composer<\/code><\/pre><p>With this, I'd expect to be able to pass arguments to it - e.g. <code>make composer info drupal\/core<\/code>.<\/p><p>But, instead of seeing the expected output, I get an error: <code>make: *** No rule to make target 'info'. \u00a0Stop.<\/code>.<\/p><p>This is what I'd need to do to pass arguments to the <code>composer<\/code> target:<\/p><pre><code class=\"make\">composer: docker compose exec php composer $(COMPOSER_ARGS)<\/code><\/pre><p>Now I can run <code>make composer COMPOSER_ARGS=\"info drupal\/core\"<\/code> and see what I was expecting but the syntax isn't what I'd want.<\/p><p><code>just<\/code>, on the other hand, allows for defining parameters to its recipes:<\/p><pre><code class=\"language-yaml\">composer *args:\u00a0 docker compose exec php composer <\/code><\/pre><p>Here, I can create as many named parameters as needed and use them in the recipe with the syntax that I wanted - <code>just composer info drupal\/core<\/code>.<\/p><p>I can think of a few others but this is is the main reason why I moved from <code>make<\/code> and later adopted <code>just<\/code>.<\/p><p><code>just<\/code>, for me, gives the flexibilty that I need whilst using a simple and familiar syntax but without some of the confusing and complicated behaviours of <code>make<\/code>.<\/p>",
"cta": "",
"tags": ["devops","just","make","linux"]
}, {
"title": "How I use Neovim for writing PHP",
"date": "1681084800",
"permalink": "/archive/2023/04/10/how-i-use-neovim-for-writing-php",
"text": "<p>Since <a href=\"https:\/\/www.oliverdavies.uk\/blog\/going-full-vim\">July 2021<\/a>, I've used Neovim full-time for my development work and writing.<\/p><p>Whilst Vim and Neovim are minimal by default, its functionality can be extended by adding plugins.<\/p><p>I use nvim-lspconfig along with Intelephpense and Phpactor to add code actions and functionality like \"go to definition\" for PHP code.<\/p><p>I use null-ls to apply code formatting and add diagnostic messages for PHPCS and PHPStan so I can see them on the appropriate lines.<\/p><p>I use nvim-dap and nvim-dap-ui to leverage the debug adapter protocol to do step debugging with Xdebug.<\/p><p>Along with others like dadbod.vim for databases, rest.nvim for making HTTP requests, Gitsigns and Fugitive for Git, and Telescope for fuzzy searching, I have all of the functionality that I've previously had in other browsers with the benefit that it's open source and I can add more plugins or write my own if I need to add anything else.<\/p>",
"cta": "",
"tags": ["neovim","php","vim"]
}, {
"title": "Nix, NixOS, Home Manager, and WSL2",
"date": "1680998400",
"permalink": "/archive/2023/04/09/nix-nixos-home-manager-and-wsl2",
"text": "<p>Although I've been using Linux for work computers for a lot longer, a few years ago, I switched from macOS and an Apple MacBook Pro to using Linux full-time on my personal computers.<\/p><p>My current daily driver laptop is a Tuxedo InfinityBook that I've installed NixOS on.<\/p><p>NixOS, as the name suggests, is a Linux operating system based on the Nix package manager. It has access to the 80,000+ packages in the <code>nixpkgs<\/code> repository and can still install and manage them, but also does a lot more including managing hardware.<\/p><p>For user-level configuration, I use Home Manager. I can configure my home directory including user-specific packages and manage my dotfiles, creating files like <code>.gitconfig<\/code> and linking them to the required destination.<\/p><p>Home Manager can be a NixOS module or a standalone tool - it can be added to NixOS or installed on any Linux distribution, even in WSL2, so I have the same packages that I need installed on every machine as well as having my dotfiles in the correct place and ready to be used.<\/p>",
"cta": "",
"tags": ["linux","nix","nixos","wsl2"]
}, {
"title": "Why I use tmux",
"date": "1680912000",
"permalink": "/archive/2023/04/08/why-i-use-tmux",
"text": "<p>tmux is a \"terminal multiplexer\" - a program that makes one terminal window into many.<\/p><p>I use the terminal a lot and am often switching between codebase so this is very useful for me.<\/p><p>I use a different session for each codebase. If I'm working on one and need to switch to another, I can detatch from one session and attach to another. Later, when I'm ready to switch back, I do the same again.<\/p><p>I usually have multiple windows inside a session. Neovim will be in the main one, and I can run separate commands - especially long-running ones like watchers - with their own windows.<\/p><p>If I need to split a window and have Neovim on the left and a terminal for running tests on the right, I can do this with different panes.<\/p><p>Being able to organise my workspace in this way has become a big part blogof my development workflow and my productivity.<\/p>",
"cta": "",
"tags": ["tmux"]
}, {
"title": "Speaking at PHP London",
"date": "1680825600",
"permalink": "/archive/2023/04/07/speaking-at-php-london",
"text": "<p>After a trip away with the family earlier this week, I was happy to speak at the PHP London meetup yesterday evening.<\/p><p>Following on from my previous \"Working from Workspace\" talk, I spoke about my current development setup for my personal and work laptops with Nix and NixOS, Linux, Neovim, tmux, just, Docker and more!<\/p><p>Of course, I spoke about PHP, Drupal, and Symfony too as well as some of the work that we're doing at Transport for Wales.<\/p><p>I learned that the call for papers for the PHP UK conference 2024 is already open so I'll definitely be submitting some proposals for next year's conference. Hopefully, I'll be back in London again before that.<\/p>",
"cta": "",
"tags": ["speaking"]
}, {
"title": "Software development is about solving problems and adding value",
"date": "1679875200",
"permalink": "/archive/2023/03/27/software-development-solving-problems-and-adding-value",
"text": "<p>I've recently started as a Mentor for the School of Code, working with a student on their cohort that started last week. Whilst the Bootcamp is focussed on JavaScript and node, and is currently looking at front-end development and using APIs, we've already started talking about different back-end technologies and frameworks.<\/p><p>Something that I've believed for a while is that software development is about solving problems and different languages and frameworks are tools to use to solve the problem and achieve the desired result. The programming fundamentals that he's learning now can be applied to different languages and some may be better depending on the problem that needs to be solved.<\/p><p>I've also said when speaking with a client this week that development is about adding business value.<\/p><p>Whilst there is some value to doing security updates and maintenance to keep an application running and secure, I'd much rather be working on tasks that directly add value for the client like some of the tasks I've done for them recently like improving eCommerce conversions and adding new payment methods or revenue streams.<\/p><p>It's easier for the client to justify and see the results of the work, it improves the experience for their customers or users, and it's more interesting and fulfilling for me.<\/p>",
"cta": "",
"tags": []
}, {
"title": "With utility styles, your CSS stops growing",
"date": "1679443200",
"permalink": "/archive/2023/03/22/with-utility-styles-your-css-stops-growing",
"text": "<p>When working with traditional CSS, the first thing you do when you need to style a new page or component is to open a stylesheet and start writing new CSS.<\/p><p>Also when editing existing styles, sometimes you'll write new styles to avoid breaking the existing pages in unexpected ways in other parts of the page. This is why I've not seen many projects where the styling is maintained or refactored over time - only added to.<\/p><p>By writing new CSS for every new page or component, the size of your stylesheets will continue to grow and be less performant and harder to maintain over time.<\/p><p>With utility styles and frameworks like Tailwind CSS, this happens a lot less or sometimes not at all.<\/p><p>If you need to use a class like <code>flex<\/code> or <code>grid<\/code> and you already use that in your project, there's no new CSS to add and the stylesheet doesn't grow. Because these type of classes are so specific, they're much more reusable which means less duplication of CSS rules and less CSS in total.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "There isn&#039;t a standard &quot;Tailwind-looking&quot; site",
"date": "1679356800",
"permalink": "/archive/2023/03/21/there-isnt-a-tailwind-looking-site",
"text": "<p>When looking at some websites, you can tell that it was built using a certain CSS framework.<\/p><p>Whether it's using a standard component like a navbar or card, or it's using the default colour palette, you can confidently know that website uses ___.<\/p><p>As Tailwind includes no components (other than the <code>container<\/code>) and only has low-level utility classes for things like spacing and colours (amongst many other things), you can build radically different-looking websites with the same classes.<\/p><p>There are some <a href=\"https:\/\/www.oliverdavies.uk\/blog\/uis-ive-rebuilt-tailwind-css\">examples of UIs that I've rebuilt<\/a> and some websites that I show in my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS talk<\/a>.<\/p><p>If you take a look, you'll see what I mean.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "The benefits of automation",
"date": "1678838400",
"permalink": "/archive/2023/03/15/the-benefits-of-automation",
"text": "<p>I've been working on a project with a client, using <a href=\"https:\/\/fractal.build\">Fractal<\/a> for our component library. I've been working on it locally but yesterday I needed to make it public for the client to review the work I've done.<\/p><p>I recently added <code>node<\/code> support to my <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/03\/04\/why-i-built-a-tool-to-generate-configuration-files\">build configuration file generator<\/a> and used that to generate and use a consistent set of configuration files for a Fractal project.<\/p><p>I've used Terraform in <a href=\"https:\/\/github.com\/opdavies\/rebuilding-acquia\">some codebases<\/a> to create and configure AWS resources like S3 buckets and Cloudfront distributions, so I was able to use that to create what I needed as well as adding the DNS record for a new subdomain to access Cloudfront.<\/p><p>I use a <code>justfile<\/code> to automate tasks such as generating production assets from Fractal and uploading it to the S3 bucket, so I can do this in a single command instead of multiple and in a consistent and reproducible way.<\/p><p>I started with a standalone project on my laptop and finished with a consistent cloud-based environment for my client and their project to review their component library, and because of the automation that I've built and used, this only took a few minutes to do.<\/p>",
"cta": "",
"tags": ["automation"]
}, {
"title": "Automating all the things",
"date": "1678752000",
"permalink": "/archive/2023/03/14/automating-all-the-things",
"text": "<p>As a solo Developer and Consultant, I rely a lot on automation to get my tasks done.<\/p><p>I use tools like <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/03\/09\/in-what-language-should-i-write-my-automation\">Pulumi, Ansible and Terraform<\/a> to automate creating and configuring infrastructure - recently creating new client GitHub repositories using a standard configuration with Pulumi.<\/p><p>I use Nix and Home Manager to automate my local development environment, install packages I need and create files like <code>.gitconfig<\/code> for my needs. These are reusable and stored in my <a href=\"https:\/\/github.com\/opdavies\/dotfiles\">dotfiles<\/a> repository.<\/p><p>For projects, I use tools like Docker, Docker Compose and Nix flakes for consistency.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/03\/04\/why-i-built-a-tool-to-generate-configuration-files\">I wrote a tool for generating configuration files for each project<\/a> - reducing the time it takes me to set up, configure and maintain standard files for tools like Docker and Docker Compose that I always use. If I need to add a new feature or fix a bug in a configuration file, I can do that in my templated version and re-generate each project's files rather than making the same change manually.<\/p><p>Today, I wrote a script that loops over all projects where I commit those files to GitHub, clones a fresh version of it, re-generates the files and pushes any new files or changes back to the repository. This means that any changes will be automatically applied and all of my projects will remain in sync.<\/p><p>Automating all of these things reduces the time that I need to spend on them - allowing me to focus on delivering value and solving problems for my clients.<\/p>",
"cta": "",
"tags": ["automation"]
}, {
"title": "What problem are we trying to solve?",
"date": "1678665600",
"permalink": "/archive/2023/03/13/what-problem-am-i-trying-to-solve",
"text": "<p>This is a question that I always ask before starting any development task, and I was very happy to see a slide in one of the keynote sessions at nor(DEV):con asking this question.<\/p><p>I'd much rather have a collegue or client come to me with a problem that needs solving rather than a self-diagnosis and a decided solution.<\/p><p>Depending what on the problem is, and other factors like timescales, I may suggest a different solution or approach. This happened recently when I suggested a different approach using Drupal's built-in maintenance mode feature.<\/p><p>If there's no problem to solve, what's the reason for doing the work?<\/p>",
"cta": "",
"tags": []
}, {
"title": "In what language should I write my automation?",
"date": "1678320000",
"permalink": "/archive/2023/03/09/in-what-language-should-i-write-my-automation",
"text": "<p>Of the three tools I mentioned in yesterday's email - Ansible, Terraform and Pulumi - I mostly use Pulumi these days for writing automation code.<\/p><p>Why? As someone who is already familiar with writing code in certain programming languages, I like that I can use those languages to also write automation, avoid learning a domain-specific language, and those existing approaches like functions and classes to make reusable components and resources.<\/p><p>I like that it supports a number of languages. I started with TypeScript but since watching a recent episode of the AltF4Stream, I'm looking at Python too. I've written Python before with Fabric and what you can achieve in Pulumi with a small amount of Python code is very impressive compared to other languages like Go and TypeScript.<\/p><p>If you prefer those other languages, why not give Pulumi a try with it?<\/p>",
"cta": "",
"tags": []
}, {
"title": "Automating infrastructure with IaC",
"date": "1678233600",
"permalink": "/archive/2023/03/08/automating-infrastructure-with-iac",
"text": "<p>Are you responsible for creating and maintaining resources like GitHub repositories, DigitalOcean servers, Amazon S3 buckets and Cloudfront distributions or DNS records in Cloudflare?<\/p><p>Do you do that through the various web UIs?<\/p><p>I'd recommend looking into infrastructure as code tools such as Ansible, Terraform and Pulumi.<\/p><p>You can create, manage and destroy these resources by writing text files rather than clicking around in web UIs, which you can store and share using version control tools.<\/p><p>Infrastructure as code (IaC) tools are something that I use when working with infrastructure, whether it's for a client project or <a href=\"https:\/\/github.com\/opdavies\/rebuilding-acquia\/blob\/4efe94398f4d8715d22ca677756beb36017d4e74\/main.tf\">a talk demo<\/a> (this uses Terraform to create an Amazon S3 bucket and Cloudflare distribution, link it to an SSL certificate and create my DNS records - all automatically).<\/p>",
"cta": "",
"tags": ["devops"]
}, {
"title": "Mentoring for School of Code",
"date": "1677974400",
"permalink": "/archive/2023/03/05/mentoring-for-school-of-code",
"text": "<p>I've been a Mentor for students on a coding bootcamp a few times before, and I'm looking forward to doing this again - this time with <a href=\"https:\/\/www.schoolofcode.co.uk\">School of Code<\/a>.<\/p><p>After hearing about them at a PHP meetup last year, I was keen to get involved after the previous bootcamp I was involved with closed its doors.<\/p><p>I've always been impressed to see people with little, or usually no prior coding experience, on these bootcamps and what they can learn and achieve in a short amount of time - and one of the things that drew me to School of Code is that the bootcamp is free for learners.<\/p><p>This week is the mentor kick-off session, with the new cohort starting next week.<\/p><p>I'm looking forward to seeing who I'm paired up with, and helping them take their first steps into a career in software development.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why I built a tool to generate configuration files",
"date": "1677888000",
"permalink": "/archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files",
"text": "<p>I'm always working on various personal and client projects, and they contain a lot of the same configuration files. I exclusively use Docker and Docker Compose on all projects, I use a <code>justfile<\/code> for running tasks, and for PHP projects, I need configuration files for tools like PHPStan, PHPCS and PHPUnit.<\/p><p>The majority of those files are the same with some slight configuration for each project - such as whether it uses <code>web<\/code> or <code>docroot<\/code>, or which paths are checked with static analysis or for coding standards issues.<\/p><p>I've given a talk called <a href=\"https:\/\/www.oliverdavies.uk\/talks\/working-with-workspace\">Working with Workspace<\/a> - a tool that we used at an agency I worked at. It had two functions - to execute project tasks and to generate configuration files from templates.<\/p><p>I use a <code>justfile<\/code> to execute tasks and commands but needed to write my own tool to generate the configuration files.<\/p><p>The result is that I can add one YAML file to a project, enter the values that it needs and when I run the CLI tool, it will generate all of the files the project needs.<\/p><p>As well as being faster to set up a project, like a <a href=\"https:\/\/github.com\/opdavies\/docker-examples\/tree\/main\/drupal-localgov\">LocalGov Drupal Docker example<\/a>, having a canonical set of templated configuration files I can enhance and maintain by adding new features and fixes and they'll be added to every project when I next generate its files.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Adding a LocalGov Drupal example",
"date": "1677801600",
"permalink": "/archive/2023/03/03/adding-a-localgov-drupal-example",
"text": "<p>After <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/10\/24\/looking-at-localgov-drupal\">previously looking at the LocalGov Drupal distribution<\/a>, today I added a LocalGov Drupal example to my <a href=\"https:\/\/github.com\/opdavies\/docker-examples\/tree\/main\/drupal-localgov\">Docker Examples repository<\/a>.<\/p><p>Based on the Drupal 10 example, the LocalGov Drupal example used Composer's <code>create-project<\/code> command to scaffold the project plus some additional configuration files such as the <code>Dockerfile<\/code>, <code>docker-compose.yaml<\/code> and a <code>justfile<\/code>.<\/p><p>A feature on my list is to add to both examples is to install Drupal automatically instead of opening the installation screen or having to run an install command. Once that's in place, it'll remove a manual step and allow people to see the application more quickly.<\/p><p>I have some issues for examples and enhancements to add within <a href=\"https:\/\/github.com\/opdavies\/docker-examples\/issues\">the repository's issue queue<\/a> and would welcome any suggestions or questions.<\/p><p>For LocalGov itself, I hope to find more opportunities to use and contribute to it in the future.<\/p>",
"cta": "",
"tags": ["drupal","localgov-drupal"]
}, {
"title": "Busy working on client projects",
"date": "1677715200",
"permalink": "/archive/2023/03/02/busy-working-on-client-projects",
"text": "<p>As well as starting to speak again at conferences and meetups, I've been very busy lately with various client projects. I've been working on completing the next phase and launch of the next website for a long-term client and handed over some other completed projects.<\/p><p>This has affected me sending out these emails every day and I missed a few days last month.<\/p><p>I'll do better!<\/p>",
"cta": "",
"tags": []
}, {
"title": "Tailwind CSS at the Norfolk Developer Conference",
"date": "1677628800",
"permalink": "/archive/2023/03/01/tailwind-css-at-the-norfolk-developer-conference",
"text": "<p>Last week, I was at the Norfolk Developer's Conference, aka <code>nor(DEV):con<\/code> - my first in-person conference since DrupalCamp London in February 2020.<\/p><p>I've been excited about this conference since I received the acceptance email in November, inviting me to give my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a> talk.<\/p><p>The talk itself went well and included some changes following the Bristol Software Development meetup last month. The last time I gave this talk prior to that was remotely for Nashville PHP in February 2021 and a lot of new things have been added to Tailwind CSS since then for me to include.<\/p><p>My next talk will be at the PHP London meetup next month (subject TBC) as I continue working towards my hundredth presentation.<\/p>",
"cta": "",
"tags": ["speaking","tailwind-css"]
}, {
"title": "Tailwind: why I prefer to extract HTML components",
"date": "1676851200",
"permalink": "/archive/2023/02/20/tailwind-why-i-prefer-to-extract-html-components",
"text": "<p>Tailwind offers the @apply directive that you can use to extract components in your CSS by applying the styles the classes would have added.<\/p><p>For example:<\/p><pre><code class=\"css\">\/* Input *\/.btn { @apply inline-block rounded-3xl bg-blue-500 px-8 py-3 text-lg text-white hover:bg-blue-800 focus:bg-blue-800;}\/* Output *\/.btn { --tw-bg-opacity: 1; --tw-text-opacity: 1; background-color: rgb(59 130 246 \/ var(--tw-bg-opacity)); border-radius: 1.5rem; color: rgb(255 255 255 \/ var(--tw-text-opacity)); display: inline-block; font-size: 1.125rem; line-height: 1.75rem; padding-bottom: 0.75rem; padding-left: 2rem; padding-right: 2rem; padding-top: 0.75rem;}.btn:hover { --tw-bg-opacity: 1; background-color: rgb(30 64 175 \/ var(--tw-bg-opacity));}.btn:focus { --tw-bg-opacity: 1; background-color: rgb(30 64 175 \/ var(--tw-bg-opacity));}<\/code><\/pre><p>Whilst this works and reduced duplication, I prefer to handle this within my HTML instead.<\/p><p>All templating engines I've used have ways to loop over or map through items and including separate files such as separate partials or different components.<\/p><p>The main benefit of this is that you get the HTML structure of the component and not just the styling. If you extract a .btn component, it may depend on a span or other element within it to display correctly but as this isn't obvious, it may be missed when writing an implementation of it in HTML - this can't happen when working inside a loop or importing a canonical version.<\/p><p>Also, by working just in the HTML markup, we continue to get the lower cognitive load and speed benefits that we're used to when styling with utility classes rather than switching between multiple files.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Clients dont care which design pattern you use",
"date": "1676764800",
"permalink": "/archive/2023/02/19/clients-dont-care-which-design-pattern-you-use",
"text": "<p>In most cases, clients don't care which CMS, framework, CSS library or design patterns you use. Clients are focused on the business value that those tools can provide, such as increasing traffic or conversion rate to increase revenue or awareness.<\/p><p>Improving the load speed of a page is good, but what business value does that offer? Are customers more likely to make a purchase if the page is faster?<\/p><p>If you can build the same page with different CMSes or frameworks, and style it in the same way with different CSS libraries, is there a business case for one over the other, such as better maintainability or a quicker time to launch the application?<\/p><p>Can you ship a simple MVP sooner, and refactor to use design patterns later?<\/p><p>Instead of focusing on technologies, tools and strategies, focus on the benefits and business value they can offer.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Creating a Drupal 10 compatible version of Override Node Options",
"date": "1676678400",
"permalink": "/archive/2023/02/18/drupal-10-version-of-override-node-options",
"text": "<p>Today, I reviewed <a href=\"https:\/\/www.drupal.org\/project\/override_node_options\/issues\/3269901\">the issue and merge request<\/a> to make the <a href=\"https:\/\/www.drupal.org\/project\/override_node_options\">Override Node Options<\/a> module compatible with Drupal 10.<\/p><p>It's a small patch that mainly affects the module's test suite so has a low risk of breaking the functionality of the module.<\/p><p>As well as the automated tests, I've done some manual testing with the patch applied on both Drupal 9.5 and 10.<\/p><p>The project page shows the module is currently used on over 34,000 sites including 18,565 Drupal 8 and 9 websites on the 8.x-2.x branch. Hopefully this number will continue to increase once the Drupal 10 version is released.<\/p>",
"cta": "",
"tags": ["drupal","open-source"]
}, {
"title": "Upgrading my Drupal example project to Drupal 10",
"date": "1676592000",
"permalink": "/archive/2023/02/17/upgrading-my-drupal-example-project-to-drupal-10",
"text": "<p>Today I upgraded my <a href=\"https:\/\/github.com\/opdavies\/docker-examples\/tree\/main\/drupal\">Drupal Docker example<\/a> to Drupal 10.<\/p><p>Admittedly, it's a simple project, but upgrading from Drupal 9 to 10 was a straightforward process.<\/p><p>I had to remove the Examples module as there's no Drupal 10 compatible version yet, but updating to Drupal 10 only needed me to change the version constraints in the <code>composer.json<\/code> file and run the <code>composer update<\/code> command.<\/p><p>After completing a number of Drupal 7 upgrade projects which involve migrating content, rewriting custom modules, and rebuilding themes, it's great to be able to upgrade between major modern versions with a few simple commands.<\/p>",
"cta": "",
"tags": ["docker","drupal","open-source"]
}, {
"title": "Tailwind CSS at the Bristol Software Development Meetup",
"date": "1676505600",
"permalink": "/archive/2023/02/16/tailwind-css-at-the-bristol-software-development-meetup",
"text": "<p>Tonight I was lucky to speak at the first <a href=\"https:\/\/www.meetup.com\/south-wales-tech\/events\/291092930\">Bristol Software Development Meetup event<\/a>, organised by South Wales Tech.<\/p><p>Following a great talk from Tom Vaughan, I gave an updated version of my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a> talk.<\/p><p>It's a talk that I first gave in January 2018 and one that I need to continuously update so that it's up to date with the latest version of the framework. The last time I gave this talk was in February 2021 so there was quite a lot of new things to cover.<\/p><p>I was also able to show my recent <a href=\"https:\/\/bootstrap-with-tailwind.oliverdavies.uk\">Tailwind versions of Bootstrap components<\/a> as a demonstration at the end of the talk.<\/p><p>I'm glad to have had the opportunity to test out the updated version before <a href=\"https:\/\/nordevcon.com\">Norfolk Developers conference<\/a> next week and I'm looking forward to attending more South Wales Tech events in Swansea and Bristol in the future.<\/p>",
"cta": "",
"tags": ["public-speaking","tailwind-css"]
}, {
"title": "Creating API endpoints with Astro",
"date": "1675900800",
"permalink": "/archive/2023/02/09/creating-api-endpoints-with-astro",
"text": "<p>As well as <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/02\/08\/fetching-api-data-with-astro\">fetching API data<\/a>, you can also use Astro to generate your own API endpoints.<\/p><p>This is an example of an endpoint that I recently created as part of a demo application:<\/p><pre><code class=\"javascript\">\/\/ trains.json.tsimport data from \"@\/data.json\";import type { APIRoute } from \"astro\";import type { Train } from \"@\/types\";export const get: APIRoute = () =&gt; { return { body: JSON.stringify(data.trains as Train[]), };};<\/code><\/pre><p>The train data is imported from a JSON file, and Astro's <code>APIRoute<\/code> is responsible for setting the appropriate response headers.<\/p><p>For server-side rendered applications, you can also have endpoints for <code>post<\/code>, <code>del<\/code> and <code>all<\/code>, though for this example, I only needed to support GET requests.<\/p><p>This is something that I've used a db-json library for previously, but being able to do this in Astro seemed like a good fit as I can easily manage lists of stations as well as a single station from one JSON file but I can just take the static HTML that Astro generates and upload it to a static hosting solution which simplifies the hosting side of things a lot.<\/p><p>And, as the example application that consumes the data is also written with Astro, having them both using the same solution has advantages too.<\/p>",
"cta": "",
"tags": ["astro"]
}, {
"title": "Fetching external API data with Astro",
"date": "1675814400",
"permalink": "/archive/2023/02/08/fetching-api-data-with-astro",
"text": "<p>As well as using static data like Astro components and Markdown files, Astro allows you to pull in data from external APIs even if you're generating a static website.<\/p><p>Astro's <a href=\"https:\/\/docs.astro.build\/en\/guides\/data-fetching\">Data Fetching documentation<\/a> shows how to do this using the global <code>fetch<\/code> function. This is the same approach that I've been using to build <a href=\"https:\/\/github.com\/opdavies\/oliverdavies.uk\/blob\/39314de34ce22b14cf85f816e4469cc4d6fb822c\/website\/src\/pages\/open-source.astro\">a page of my open-source projects<\/a>. I'm still working on it, but it fetches project information from both Drupal.org and GitHub and displays them on a page.<\/p><p>This is also makes Astro a good option to be used as a front-end for decoupled projects that use a separate back-end CMS like Drupal to store and manage the content which it fetches and uses when generating the site.<\/p>",
"cta": "",
"tags": ["astro"]
}, {
"title": "Astro as a static site generator",
"date": "1675728000",
"permalink": "/archive/2023/02/07/astro-as-a-static-site-generator",
"text": "<p>Since first setting it first during Simon Vrachliotis' workshops, I've started evaluating <a href=\"https:\/\/astro.build\">Astro<\/a> as an option for building static websites alongside PHP options like Sculpin and Jigsaw, and used it to rebuild <a href=\"https:\/\/www.oliverdavies.uk\">my personal website<\/a>.<\/p><p>As well as being a good opportunity to get more experience with JavaScript, TypeScript and JSX templating, Astro includes a number of features that were useful for my website, such as code syntax highlighting and markdown support out of the box, as well as integrations to set up Tailwind CSS, sitemaps and images that I needed.<\/p><p>Its file-based routing is very familiar to what I'd been working with in Next.js, including dynamic and nested routes such as my Blog, Talks, and email archive pages.<\/p><p>A static HTML version of the site can be generated which can be uploaded to a web server - like with other static site generators - with the advantage that Astro includes no JavaScript by default.<\/p><p>As well as my personal website, I've been using Astro for some other mini-projects including <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/22\/building-bootstrap-css-examples-with-tailwind\">building Bootstrap components with Tailwind<\/a>, and I'm using it for the updated examples for my Tailwind CSS talk at nor(DEV):con in a couple of weeks time.<\/p>",
"cta": "",
"tags": ["astro"]
}, {
"title": "To squash or not to squash",
"date": "1674604800",
"permalink": "/archive/2023/01/25/to-squash-or-not-to-squash",
"text": "<p>When reviewing a pull or merge request, tools like GitHub and GitHub offer the option to squash the commits before merging.<\/p><p>If the request had twenty commits, they'd be combined into a single commit before being merged.<\/p><p>But should you do it?<\/p><p>The answer will be \"it depends\" based on the project or team, but I'm personally not a fan of squashing commits.<\/p><p>Even though I commit small changes often, I put quite a bit of effort into <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/24\/small-commits-and-good-commit-messges\">crafting commits and writing detailed commit messages<\/a> that capture the reason for each change. If the commits are squashed, either the messages will be combined into one extra-long commit message or I've seen them be deleted completely.<\/p><p>One large commit message would be very difficult to read and connect specific messages with their changes, and deleting the commit body would lose the history completely and waste the time it took to write the messages and craft the commits. It may be available within the pull or merge request page but there's no guarantee that you'll continue to use the same repository hosting service in the future.<\/p><p>One large commit would also be difficult to debug if there was an error. If the whole feature was added in a single commit, tools like <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/23\/debugging-with-git-bisect\">git bisect<\/a> would no longer work and a single commit couldn't be simply reverted if it contained a bug.<\/p><p>I prefer to keep the original small commits and instead prefer to use rebasing and only fast-forward merges to avoid merge commits and keep a simple, linear history in my Git log, and be able to easily read, find and, if needed, fix the code that's been committed.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Small commits and good commit messges",
"date": "1674518400",
"permalink": "/archive/2023/01/24/small-commits-and-good-commit-messges",
"text": "<p>An important thing when using a tool like <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/23\/debugging-with-git-bisect\">git bisect<\/a> as well as reviewing pull\/merge requests and commits is to have small (aka \"atomic\") commits.<\/p><p>Commits with small changes make them easier to review and, if needed, to revert and debug with bisect. If a commit has ten new or changed lines, it's much easier to see and fix a bug than if the commit had a hundred lines.<\/p><p>If you're doing code reviews or \"Showing\" in a Ship\/Show\/Ask format, you'll likely get better and more valuable feedback if the commits are smaller and only doing one thing.<\/p><p>If you're submitting a change for review, commit a failing test first so that it can be seen failing before committing the code to make it pass. This makes it easier to see that the code is actually making the test pass.<\/p><p>Also take some time to write good, informative commit messages.<\/p><p>As well as the short one-line subject, you can add as much detail as you need to the body of the message about the change that's being committed, why it's needed, what other approaches were considered or tried, as well as links to supporting documentation such as ADRs, technical design documents or diagrams.<\/p><p>Having as much information as possible makes it much easier when someone needs to review or fix a specific commit. I like to use the <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/01\/conventional-commits-changelogs\">conventional commits specification<\/a>, though the main objective is to have all of the information documented so it's available in the future.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Debugging with git bisect",
"date": "1674432000",
"permalink": "/archive/2023/01/23/debugging-with-git-bisect",
"text": "<p>Last week, I had to debug a regression in a codebase.<\/p><p>Something was working at the last release but is now broken.<\/p><p>There have been around 20 commits to the mainline branch since the last release, and the first step to fixing the issue is to determine which commit caused the regression.<\/p><p>Git has a great tool for this - <code>git bisect<\/code>.<\/p><p>You tell Git what the last known working commit was, such as the tag of the last release, and it will start to split the commits and prompt you to tell it whether the commit is good or bad.<\/p><p>If there are 20 commits, it may pick commit number 10, and based on whether the commit is good or bad, it may pick commit 5 or 15.<\/p><p>Based on your answers, Git will then tell you which the first bad commit is.<\/p><p>Even better, if it's something that you can script or is covered with an automated test, <code>git bisect<\/code> can run a command for you and find the failure automatically rather than a human needing to check manually.<\/p><p>Once you've found the commit that breaks, you can view it and find and fix the bug.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Building Bootstrap CSS examples with Tailwind",
"date": "1674345600",
"permalink": "/archive/2023/01/22/building-bootstrap-css-examples-with-tailwind",
"text": "<p>Previously when I gave my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a> talk, I created examples that relate to the event such as something related to that technology or event.<\/p><p>The nor(DEV):con website already uses Tailwind CSS so I've been looking for other examples and have started to build some of the <a href=\"https:\/\/getbootstrap.com\/docs\/4.0\/examples\">Bootstrap CSS components<\/a> with Tailwind CSS.<\/p><p>I've created the <a href=\"http:\/\/bootstrap-with-tailwind.s3-website.eu-west-2.amazonaws.com\/album\">Album<\/a> and <a href=\"http:\/\/bootstrap-with-tailwind.s3-website.eu-west-2.amazonaws.com\/pricing\">Pricing<\/a> components so far but will likely do more before the conference as I think they're good examples.<\/p><p><a href=\"https:\/\/github.com\/opdavies\/bootstrap-with-tailwind\">The source code<\/a> is on my GitHub profile, uses Astro and its Tailwind CSS integration, the default Tailwind configuration with some slight colour and font tweaks, the official Typography plugin and a small custom plugin that adds a \"hocus\" variant for both hover and focus styles.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "Tailwind: Not just translating CSS to utility classes",
"date": "1674259200",
"permalink": "/archive/2023/01/21/tailwind-not-just-translating-css-to-utility-classes",
"text": "<p>Whilst a number of classes that Tailwind CSS generates are single-value utility classes such as <code>.block { display: block; }<\/code> and <code>.relative { position: relative; }<\/code>, it also includes additional things such as <a href=\"https:\/\/tailwindcss.com\/docs\/font-size#setting-the-font-size\">setting a default line height with a font size<\/a>, adding variants for <a href=\"https:\/\/tailwindcss.com\/docs\/hover-focus-and-other-states#styling-based-on-parent-state\">group-hover<\/a> and <a href=\"https:\/\/tailwindcss.com\/docs\/hover-focus-and-other-states#focus-within\">focus-within<\/a> (as well as various other pseudo states).<\/p><p>It includes utilities for adding <a href=\"https:\/\/tailwindcss.com\/docs\/space#add-horizontal-space-between-children\">horizontal or vertical space<\/a> or <a href=\"https:\/\/tailwindcss.com\/docs\/divide-style\">styling dividers between elements<\/a>.<\/p><p>As well prefixing a class using a screen modifier, such as <code>md:flex<\/code>, you can stack them and set a maximum screen value. For example, <code>md:max-lg:flex<\/code> will only flex between the <code>md<\/code> and <code>lg<\/code> breakpoints.<\/p><p>If has official plugins for typography styles, forms, line-clamp (truncating text) and aspect ratios, as well as numerous community plugins and supports arbitrary values if you need them.<\/p><p>If you take a look at the <a href=\"https:\/\/tailwindcss.com\/docs\">Tailwind CSS documentation<\/a>, you'll definitely find some interesting and useful things.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "Tailwind&#039;s classes are your classes",
"date": "1674172800",
"permalink": "/archive/2023/01/20/tailwinds-classes-are-your-classes",
"text": "<p>In my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS talk<\/a>, I've described Tailwind as a CSS utility class generator. You write a configuration file that Tailwind reads and generates the appropriate classes.<\/p><p>Yesterday I mentioned the <a href=\"https:\/\/phpsw.uk\">PHP South West user group<\/a> website. It's a project that <a href=\"https:\/\/twitter.com\/opdavies\/status\/934488762276564993\">I worked on in November 2017<\/a> and uses Tailwind 0.5.<\/p><p>For me, a big advantage of Tailwind was that once it generates the classes, they are ours. They aren't hidden within the framework or an npm package. We can see them, commit them to version control and keep them for as long as we need.<\/p><p>Even if the Tailwind CSS framework disappeared tomorrow (I hope it doesn't), I'd be able to continue using the styles that it generated, and my projects would continue to work and look the same.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "Long-term maintainability with utility classes and Tailwind CSS",
"date": "1674086400",
"permalink": "/archive/2023/01/19/long-term-maintainability-with-utility-classes-and-tailwind-css",
"text": "<p>One of the common initial concerns of utility classes and Tailwind CSS is its maintainability.<\/p><p>How you manage all the classes within the HTML and how easy is it to make changes?<\/p><p>Today, <a href=\"https:\/\/twitter.com\/mauro_codes\/status\/1615726036737576960\">I saw this tweet<\/a>:<\/p><blockquote> <p>You can say whatever you want about @tailwindcss, but I just opened a legacy project with tailwind 0.7 that I didn't touch for almost three years... and I was able to update the whole branding in 30 minutes.<\/p><\/blockquote><p>One of my earliest Tailwind projects was the <a href=\"https:\/\/phpsw.uk\">PHP South West website<\/a>. We <a href=\"https:\/\/twitter.com\/opdavies\/status\/934488762276564993\">worked on this in November 2017<\/a> and it still uses Tailwind CSS 0.5.<\/p><p>These are the classes used on the main menu:<\/p><p><code>bg-grey-lightest hidden absolute z-20 w-full border border-grey-lighter sm:flex sm:relative sm:w-auto sm:border-none<\/code><\/p><p>Even though Tailwind CSS is now on version 3.2.4, I can still read this and know exactly what the classes do, and I'm confident that I could easily make changes to this or any other element on the website.<\/p><p>That probably isn't something that I could say for other projects that use different approaches to styling, and definitely an advantage of styling with small, reusable utility classes.<\/p>",
"cta": "",
"tags": ["css","tailwind-css"]
}, {
"title": "Drupal turns 22!",
"date": "1674000000",
"permalink": "/archive/2023/01/18/drupal-turns-22",
"text": "<p>On Sunday, the Drupal project turned 22 years old.<\/p><p>I've personally been working with Drupal primarily for almost 15 years <a href=\"https:\/\/www.drupal.org\/u\/opdavies\">according to my Drupal.org profile<\/a>, self teaching and working on personal and freelance projects since 2007, and in full-time roles since 2010 when I started at Horse and Country TV to work on their Drupal 6 website.<\/p><p>Last month, I started my first Drupal 10 project for a client.<\/p><p>I'm proud that over a year of that time was spent working for the Drupal Association where I improved the Drupal.org websites and resolved issues that would have blocked the Drupal 8 release in 2015.<\/p><p>I'm also happy to have <a href=\"https:\/\/www.oliverdavies.uk\/talks\">presented talks and workshops<\/a> at events like DrupalCamps, Drupal Developer Days and twice at DrupalCon. I've also organised Drupal events such as the Drupal Bristol meetup and DrupalCamp Bristol conference.<\/p><p>I've had opportunities to contribute to open-source by having patches committed to Drupal core and maintaining modules and themes like <a href=\"https:\/\/www.drupal.org\/project\/override_node_options\">Override Node Options<\/a> and the <a href=\"https:\/\/www.drupal.org\/project\/tailwindcss\">Tailwind CSS starter kit<\/a>. I've also mentored and helped others to get their first commits to Drupal core and open-source.<\/p><p>I plan to continue working with Drupal and being part of the community for a long time, hopefully for at least another 22 years.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Things to know about PHP",
"date": "1673913600",
"permalink": "/archive/2023/01/17/things-to-know-about-php",
"text": "<p>The talk that I gave last week at PHP Stoke was <a href=\"https:\/\/www.oliverdavies.uk\/talks\/things-you-should-know-about-php\">Things to know about PHP<\/a> - a talk that I was originally asked to give at the Swansea Software Development Meetup (SSDC) in January 2019, and this was the second time that I've been asked to give this talk at a PHP meetup.<\/p><p>Originally to give a group of various Software Developers an introduction to PHP, I didn't want the talk to be focused just on the language itself and be a walkthough the PHP manual.<\/p><p>Whilst there is some code in the talk so demonstrate what it can do, the other half of the talk is about the other parts of the PHP ecosystem such as tooling and the community. I talk about tools like Composer, PHPStan, Xdebug, PHPUnit and Pest, the CMSes and frameworks that are available, and the various online learning tools like SymfonyCasts and Laracasts as well as certification programs that are available.<\/p><p>It's great to give this talk at meetups as that's where the community starts, where people come to share and learn, and what larger conferences like PHP UK, php[tek] and others are built on. I love attending meetups and events and meeting other members of the PHP community.<\/p><p>Oh, and elePHPants!<\/p><p>The latest versions of the slides are on the Talks section of my website (the link is at the top of the email).<\/p><p>If you'd like me to come and speak at your meetup or conference, please get in touch!<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Back after PHP Stoke",
"date": "1673827200",
"permalink": "/archive/2023/01/16/back-after-php-stoke",
"text": "<p>I took a bit of time off from these emails whilst I was preparing for the first PHP Stoke event which happened last week in Stoke-on-Trent.<\/p><p>It was a great event with around 35 attendees and two other speakers as well as myself.<\/p><p>The <a href=\"https:\/\/www.oliverdavies.uk\/talks\/things-you-should-know-about-php\">latest version of my slides are online<\/a> as well <a href=\"https:\/\/www.oliverdavies.uk\/things-about-php\">some updated resources<\/a>.<\/p><p>My next talk will be at the Norfolk Developers conference next month where I'll be presenting an updated version of <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a>.<\/p><p>If you have a topic idea for a talk or would like me to speak at your meetup or conference, please get in touch.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Reducing utility class duplication",
"date": "1673049600",
"permalink": "/archive/2023/01/07/reducing-utility-class-duplication",
"text": "<p>One of the main concerns for Developers evaluating or starting with a utility-first approach to styling is maintainability due to the number and duplication of classes.<\/p><p>For example, with this component, as I duplicate it to add more links, I also duplicate the classes applied to the link - making it harder to maintain:<\/p><pre><code class=\"html\">&lt;li&gt; &lt;a class=\"block py-2 border-b-2 border-transparent hover:text-blue-500 hover:border-blue-500 focus:bg-yellow-400 focus:border-current focus:outline-none\" href=\"#0\"&gt;About&lt;\/a&gt;&lt;\/li&gt;<\/code><\/pre><p>There are some solutions to this, which you can also see in an example Astro project at https:\/\/github.com\/opdavies\/reducing-utility-class-duplication.<\/p><h2 id=\"extracting-a-variable-of-class-names\">Extracting a variable of class names<\/h2><p>The simplest way to remove the duplication is to create a variable that holds the class names which can be reused. For example, Astro allows variables to be created within the frontmatter section and used within the template. Creating variables can be done in other templating engines too.<\/p><pre><code class=\"astro\">---const linkClasses = \"py-2 block border-b-2 border-transparent hover:border-blue-500 hover:text-blue-500 focus:outline-none focus:bg-yellow-400 focus:border-current\";---&lt;li&gt;&lt;a class={linkClasses} href=\"#0\"&gt;About&lt;\/a&gt;&lt;\/li&gt;&lt;li&gt;&lt;a class={linkClasses} href=\"#0\"&gt;Talks&lt;\/a&gt;&lt;\/li&gt;&lt;li&gt;&lt;a class={linkClasses} href=\"#0\"&gt;Blog&lt;\/a&gt;&lt;\/li&gt;<\/code><\/pre><h2 id=\"extracting-css-components\">Extracting CSS components<\/h2><p>Instead of extracting a variable, you could also extract a CSS component. With Tailwind, the <code>@apply<\/code> directive within a stylesheet will create a reusable CSS component:<\/p><pre><code class=\"astro\">&lt;Layout&gt; &lt;ul class=\"flex flex-col gap-4 justify-center sm:flex-row sm:flex-wrap sm:gap-6\" &gt; &lt;li&gt;&lt;a class=\"link\" href=\"#0\"&gt;About&lt;\/a&gt;&lt;\/li&gt; &lt;li&gt;&lt;a class=\"link\" href=\"#0\"&gt;Blog&lt;\/a&gt;&lt;\/li&gt; &lt;li&gt;&lt;a class=\"link\" href=\"#0\"&gt;Talks&lt;\/a&gt;&lt;\/li&gt; &lt;\/ul&gt;&lt;\/Layout&gt;&lt;style&gt; .link { @apply py-2 block border-b-2 border-transparent hover:border-blue-500 hover:text-blue-500 focus:outline-none focus:bg-yellow-400 focus:border-current; }&lt;\/style&gt;<\/code><\/pre><p>The <code>link<\/code> class can be added to any link items, and whilst the approach works, I prefer to use template-based solutions and keep the classes within the HTML markup.<\/p><h2 id=\"loops-and-maps\">Loops and maps<\/h2><p>Templating engines will have a way to loop over a list of items. This can be used to remove the duplication and only have a single list of classes whilst keeping the benefits of keeping them in the HTML code.<\/p><p>For example, in Astro:<\/p><pre><code class=\"astro\">---const links = [ { name: \"About\" }, { name: \"Blog\" }, { name: \"Talks\" }, { name: \"Daily list\" }, { name: \"Search\" },];---{links.map(link =&gt; ( &lt;li&gt; &lt;a class=\"block py-2 border-b-2 border-transparent hover:text-blue-500 hover:border-blue-500 focus:bg-yellow-400 focus:border-current focus:outline-none\" href=\"#0\"&gt; {link.name} &lt;\/a&gt; &lt;\/li&gt;))}<\/code><\/pre><h2 id=\"extracting-html-components\">Extracting HTML components<\/h2><p>Finally, if the component needs to be reused, it can be extracted into its own file and re-imported where needed.<\/p><p>This is the extracted component:<\/p><pre><code class=\"astro\">---const { name } = Astro.props;---&lt;a class=\"block py-2 border-b-2 border-transparent hover:text-blue-500 hover:border-blue-500 focus:bg-yellow-400 focus:border-current focus:outline-none\" href=\"#0\"&gt; {name}&lt;\/a&gt;<\/code><\/pre><p>And the original file:<\/p><pre><code class=\"astro\">---import Layout from \"~\/layouts\/Layout.astro\";import Link from \"~\/components\/Link.astro\";---&lt;Layout&gt; &lt;ul class=\"flex flex-col gap-4 justify-center sm:flex-row sm:flex-wrap sm:gap-6\"&gt; &lt;li&gt;&lt;Link name=\"About\" \/&gt;&lt;\/li&gt; &lt;li&gt;&lt;Link name=\"Blog\" \/&gt;&lt;\/li&gt; &lt;li&gt;&lt;Link name=\"Talks\" \/&gt;&lt;\/li&gt; &lt;li&gt;&lt;Link name=\"Daily list\" \/&gt;&lt;\/li&gt; &lt;li&gt;&lt;Link name=\"Search\" \/&gt;&lt;\/li&gt; &lt;\/ul&gt;&lt;\/Layout&gt;<\/code><\/pre><p>This can now be used anywhere within this project and could be combined with the loop approach, passing the appropriate value to the <code>name<\/code> prop.<\/p><h2 id=\"summary\">Summary<\/h2><p>All of these approaches remove duplication, either using features provided by Tailwind CSS or a templating engine, to make the code more maintainable.<\/p><p>I've shown <a href=\"https:\/\/astro.build\">Astro<\/a> in these examples but the same can be done with PHP, Twig, Blade, Vue, React, etc.<\/p><p>The examples are public on GitHub at https:\/\/github.com\/opdavies\/reducing-utility-class-duplication\/tree\/main\/src\/pages.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Utility-first or utility-last?",
"date": "1672963200",
"permalink": "/archive/2023/01/06/utility-first-or-utility-last",
"text": "<p>Tailwind CSS is based on the \"utility-first\" approach, where the majority of styling is done using utility CSS classes. You can still add additional custom styles if needed if there is something that can't be achieved with utilities or would be better placed in a custom CSS stylesheet.<\/p><p>Utility-last is the opposite approach, where a small number of utilities are used alongside other CSS styles or another framework. This is common when <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/05\/adding-tailwind-to-an-existing-project\">adding a utility-based framework like Tailwind CSS<\/a> to an existing project and you want to use it for a new page or component whilst keeping the existing styles.<\/p><p>This is what I did when I started learning Tachyons, and later Tailwind CSS. My project already had styling from another CSS framework, I started using utility classes and over time refactored until only utilities were used and the other styles could be removed.<\/p><p>You could do the opposite too, and refactor groups of utilities into a CSS component, either by using Tailwind's <code>@apply<\/code> directive or <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/03\/tailwind-css-extensibility-is-one-of-its-best-features\">writing a plugin<\/a>.<\/p><p>If you did want to use Tailwind for a small number of utilities, by default, it will only generate classes that are used within HTML or template files, but it can also be configured to only use the core modules that you specify - preventing Developers from using unwanted utility based on the rules for that project.<\/p><p>You could, of course, write your own utilities, or they're becoming common in other frameworks now too for things like padding, margin and colours.<\/p><p>Do you typically do styling utility-first or utility-last, or are you transitioning from one to the other?<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Adding Tailwind CSS to an existing project",
"date": "1672876800",
"permalink": "/archive/2023/01/05/adding-tailwind-to-an-existing-project",
"text": "<p>Tailwind's configuration file also makes it easy to add it to an existing codebase, whether it uses custom CSS or another CSS framework.<\/p><p>You can opt-out of Tailwind's CSS reset and normalisation by adding <code>corePlugins: { preflight: false }<\/code> to tailwind.config.js, and if you have duplicate classes with existing classes and Tailwind-generated ones, you can add <code>prefix: 'tw-'<\/code> to prefix all of Tailwind's class names and avoid the conflicts.<\/p><p>If you need to deal with specificity, you can mark Tailwind-generated classes as important by adding <code>important: true<\/code> so that they can override any existing styling. You can do the same in HTML code by prefixing a class name with an exclamation mark - e.g. <code>!flex<\/code>.<\/p><p>Or, if you know that your Tailwind styles will only be used within a certain element, like <code>#app<\/code>, instead of making all classes important, by adding <code>important: \"#app\"<\/code> to the configuration, Tailwind classes will be prefixed with that selector - making them more specific.<\/p><p>Once these options are set, you can start using Tailwind without affecting the existing styles.<\/p><p>Doing this, and starting small by using a small number of utilities can be a good step towards migrating an existing codebase to use Tailwind and removing the existing styles at a later date.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Testable Tailwind CSS plugins",
"date": "1672790400",
"permalink": "/archive/2023/01/04/testable-tailwind-css-plugins",
"text": "<p>A great thing about <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2023\/01\/03\/tailwind-css-extensibility-is-one-of-its-best-features\">Tailwind CSS plugins<\/a> being written in JavaScript is that they can be tested using tools like Jest.<\/p><p>Here's an example from https:\/\/github.com\/opdavies\/tailwindcss-plugin-jest-example (it may need updating to work with the latest Tailwind versions or to use the latest best practices):<\/p><pre><code class=\"javascript\">function run(options = {}) { return postcss( tailwindcss({ corePlugins: false, plugins: [plugin(options)] }) ) .process('@tailwind utilities;', { from: undefined })}expect.extend({ toMatchCss: cssMatcher})test('it generates the correct classes with no variants', () =&gt; { const output = ` .test { display: block } ` run().then(result =&gt; { expect(result.css).toMatchCss(output) })})test('it generates the correct classes with variants', () =&gt; { const output = ` .test { display: block } .hover\\\\:test:hover { display: block } .focus\\\\:test:focus { display: block } ` run({ variants: ['hover', 'focus'] }).then(result =&gt; { expect(result.css).toMatchCss(output) })});<\/code><\/pre><p>Within the test, Tailwind can be run using PostCSS and generates styles based on a provided configuration, which is then checked against some expected output. If the generated styles match what was expected, the tests pass and the plugin is working as expected.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Tailwind CSS&#039; extensibility is one of its best features",
"date": "1672704000",
"permalink": "/archive/2023/01/03/tailwind-css-extensibility-is-one-of-its-best-features",
"text": "<p>As well as the library of utility CSS classes that Tailwind provides, the ability to easily add your own has been one of my main advantages of using it.<\/p><p>You can add your own CSS to a stylesheet within a specific layer, customise the theme settings within a <code>tailwind.config.js<\/code> file, and write your own custom plugins that you can reuse and even release as separate open-source projects.<\/p><p>Here is a complete plugin that I've added to some projects recently:<\/p><pre><code class=\"js\">const plugin = require('tailwindcss\/plugin');plugin(function({ addVariant }) { addVariant('hocus', ['&amp;:hover', '&amp;:focus'])});<\/code><\/pre><p>By adding these lines of JavaScript, Tailwind will generate a new set of utility classes that apply styles to both hover and focus states for an element - reducing the number of classes that need to be added and making it more maintainable.<\/p><p>Other plugins that I've written recently include creating different variants of buttons, styling elements within an HTML table (similar to the Tailwind typography plugin), and adding multi-theme support to make components themable with different colours.<\/p><p>I've also released some <a href=\"https:\/\/github.com\/opdavies?tab=repositories&amp;q=tailwind-plugin\">as open-source projects on GitHub<\/a>.<\/p><p>The interesting thing is that the plugin API is how Tailwind itself generates its own classes, and I like the stability that provides.<\/p><p>However you extend Tailwind, the fact you can tweak and extend it for each project is great and something that you can't always do or do easily with other tools or frameworks.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Don&#039;t use arbitrary values in Tailwind CSS",
"date": "1672617600",
"permalink": "/archive/2023/01/02/dont-use-arbitrary-values-in-tailwind-css",
"text": "<p>It's been almost five years since I gave the first version of my \"<a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a>\" talk at the Drupal Bristol meetup in January 2018.<\/p><p>It's a talk that I've updated every time I've given it, showing new rebuilt example UIs and the new features in the framework, as well as tweaking content like installation steps for different audiences.<\/p><p>As I prepare for the Norfolk Developers Conference (nordevcon) next month, I'm updating the talk again.<\/p><p>One feature that wasn't in the last version of the talk is arbitrary values in class names. This, I think, is an antipattern and something that I avoid using.<\/p><p>Whilst you could always add arbitrary values in custom CSS, one of my original reasons for liking and adopting Tailwind CSS was that there was a predefined list of classes to choose from.<\/p><p>A set list of colours, text sizes, margins and padding, for example, meant that UIs looked more consistent and the generated CSS was smaller.<\/p><p>If you need an additional value or to replace the existing values, you can do so within your <code>tailwind.config.js<\/code> file, and Tailwind will generate classes accordingly.<\/p><p>Whilst writing custom CSS, inline styles, and arbitrary values are all possible, I'd suggest using the configuration file, generating the classes that you need, and sticking to them as much as you can and enjoying the consistency and benefits that brings.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Types and static analysis saved me today",
"date": "1672531200",
"permalink": "/archive/2023/01/01/types-and-static-analysis-saved-me-today",
"text": "<p>Today I was writing Pulumi code in Typescript, and I although I have autocompletion, I mistyped the name of a property.<\/p><p>But, because of the types that I'd declared and how I have Neovim configured, the error was immediately shown, and I was able to fix the typo and what would have been a compilation error if I'd tried to run it.<\/p><p>It only took a second or two for me to make and fix the mistake.<\/p><p>I didn't need to run the code or commit it and push it to a CI pipeline to find out that there was a bug.<\/p><p>I found out and fixed it immediately, and moved on as if I hadn't written the typo at all. This is why I like types and static analysis.<\/p>",
"cta": "",
"tags": ["static-analysis","types"]
}, {
"title": "Just start writing",
"date": "1672444800",
"permalink": "/archive/2022/12/31/just-start-writing",
"text": "<p>Whether it's writing code or a technical design document, diagnosing an issue, or working on a blog post or a presentation deck, sometimes, the hardest part for me is getting started.<\/p><p>When this happens, I try to find the smallest thing I can do to start the task and get the ball rolling.<\/p><p>This could be just opening Neovim or Notion and finding the smallest task I can do to get going.<\/p><p>In code, it could be making the smallest change to start on the task or committing a small refactoring on another part of the code to get into the flow.<\/p><p>With a technical design document, once I've written the first heading, \"What problem are we trying to solve?\" and started to describe the problem, it's easy to continue writing the rest of the document.<\/p><p>For a blog post or presentation, I've found that writing the headings first is a good starting point, adds structure and makes it easier to add the main content.<\/p><p>Things are great once the ball is rolling; the question sometimes is, \"what is the simplest thing I can do to start it?\".<\/p>",
"cta": "",
"tags": ["productivity"]
}, {
"title": "Tests are living documentation",
"date": "1672358400",
"permalink": "/archive/2022/12/30/tests-are-living-documentation",
"text": "<p>Today I was working on a project and made a one-line change that updated a single value within an API response.<\/p><p>Unexpectedly, it caused a test to fail. The API response returned a 500 status code instead of the expected 201 code.<\/p><p>I reverted the change locally and ensured that the test passed again, so I knew it was causing the failure.<\/p><h2 id=\"fixing-the-failure\">Fixing the failure<\/h2><p>The change was removing a hard-coded part of a URL to a dynamic one, using Drupal's <code>Settings<\/code> class.<\/p><p>I was retrieving a value from it, but as there was no value being set within the test, it was returning a null value and causing the 500 error code.<\/p><h2 id=\"how-does-the-settings-class-work%3F\">How does the Settings class work?<\/h2><p>To fix the test failure, I needed to learn how to set a Settings value within a test.<\/p><p>To do this, I looked for and found the test for the Settings class itself. I saw how it was being set there, did the same in my test, fixed the failure and got my test passing again.<\/p><h2 id=\"tests-are-living-documentation\">Tests are living documentation<\/h2><p>As well as verifying things work when they are written, tests also act as long-term documentation. They can be run at any point to ensure that they still pass and are a reference to other developers on how the code should work.<\/p><p>Rather than a Confluence page, a README file or code comments which can become out of date, if a test becomes outdated, it will fail and make developers aware, as well as break any CI pipeline that it runs in.<\/p><p>By writing tests, you're ensuring that your code works as expected and documenting it at the same time.<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "What is the cost of a bug?",
"date": "1672272000",
"permalink": "/archive/2022/12/29/what-is-the-cost-of-a-bug",
"text": "<p>All software has bugs, but each has a different cost depending on when and where it's found.<\/p><h2 id=\"in-production\">In production<\/h2><p>If a bug was found in production, it was probably found by a user, will time to replicate, diagnose and fix, and could have caused some reputational or financial damage.<\/p><p>You'd need to create a ticket and schedule the work, meaning you're not working on something else.<\/p><p>Cost: High<\/p><h2 id=\"in-a-pre-production-environment\">In a pre-production environment<\/h2><p>It's likely found by a test analyst or product owner but hidden from the end users and customers.<\/p><p>It will still take time to replicate, diagnose and fix, and you'd still need to create a ticket and schedule the work, as well as the bug potentially blocking releases to production until it's resolved.<\/p><p>Cost: High<\/p><h2 id=\"in-a-ci-pipeline\">In a CI pipeline<\/h2><p>This is likely to be a static analysis or a test failure. It should be quicker to fix though it will need to be done quickly or reverted if you're doing trunk-based development to unblock other Developers.<\/p><p>If you're doing code reviews, you'll need to ensure that the pipeline passes before the review and continues to pass after making any changes.<\/p><p>Cost: Medium<\/p><h2 id=\"locally\">Locally<\/h2><p>If an automated check fails in CI, why not run it locally before you commit and push the change?<\/p><p>If it's a coding standards issue or static analysis failure, you could configure your text editor or IDE to show you issues in real time. Then they can be fixed immediately and not even committed and pushed to a CI pipeline.<\/p><p>If you were working in a pair or mob, could someone else have spotted the issue and suggested a fix?<\/p><p>Cost: Low<\/p><p>The sooner you can find a bug, the less time and cheaper it is to fix, and we can use tools like automated tests and static analysis to help us write fewer bugs and to fix them sooner and faster.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Debugging gitignore rules",
"date": "1672185600",
"permalink": "/archive/2022/12/28/debugging-gitignore-rules",
"text": "<p>Have you wondered why a file or directory is being ignored in your Git repository and isn't appearing when you run <code>git status<\/code>?<\/p><p>Maybe you have multiple <code>.gitignore<\/code> files and you don't know which is causing the issue, or you ignore everything and explicitly unignore the files that you want to add.<\/p><h2 id=\"%60check-ignore%60-to-the-rescue\"><code>check-ignore<\/code> to the rescue<\/h2><p><code>git check-ignore<\/code> accepts a list of paths and checks if each is ignored.<\/p><p>There's also a <code>--verbose<\/code> option that will tell you which <code>.gitignore<\/code> file is causing it to be ignored as well as the line number and the pattern - great information for debugging, and no more force adding files.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Speaking at PHP Stoke and nor(DEV):con",
"date": "1671753600",
"permalink": "/archive/2022/12/23/speaking-at-php-stoke-and-nordevcon",
"text": "<p>I had some early presents this month and have been accepted to present talks at the new PHP Stoke meetup and the Norfolk Developers Conference.<\/p><h2 id=\"php-stoke\">PHP Stoke<\/h2><p>The first PHP Stoke meetup will be held at Genr8 Smithfield Works on the 12th of January. I'll be presenting \"<a href=\"https:\/\/www.oliverdavies.uk\/talks\/things-you-should-know-about-php\">Things you should know about PHP<\/a>\". It'll be great to be the first speaker at this new meetup.<\/p><h2 id=\"nordev%3Acon\">nor(DEV):con<\/h2><p>The Norfolk Developers conference is in Norwich on the 23rd and 24th of February.<\/p><p>I'll be presenting \"<a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight about Tailwind CSS<\/a>\". It's been a while since I last gave this talk so I'm looking forward to updating it with the latest changes and new features in Tailwind CSS.<\/p><p>It'll be great to be speaking at these events and hopefully others in 2023.<\/p>",
"cta": "",
"tags": ["public-speaking"]
}, {
"title": "The Boy Scout rule",
"date": "1671667200",
"permalink": "/archive/2022/12/22/the-boy-scout-rule",
"text": "<p>The Boy Scout rule is \"Always leave the campground cleaner than you found it\".<\/p><p>From a programming perspective, \"Always leave the code better than you find it\".<\/p><p>If you're working on some code and see some commented-out lines or unused variables, once you've finished with your changes, remove them too.<\/p><p>If there's a variable that could have a more descriptive name, change it.<\/p><p>If there are any other refactors you can do, do them and leave the code better than before and easier for the next Developer (whether it's you or someone else) to work with.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Duck typing",
"date": "1671580800",
"permalink": "/archive/2022/12/21/duck-typing",
"text": "<p>If it looks like a duck, walks like a duck, and quacks like a duck, it must be a duck.<\/p><p>If I pass a parameter into a function, as long as it works with the code within the function - it is of the correct type and has the expected properties and methods - it will work, although nothing is enforcing that the correct thing is passed in.<\/p><p>If not, you'd get an error that the method or property doesn't exist when trying to invoke or access it.<\/p><p>This is the opposite of strict typing, where you'd get a Type error if you passed the wrong thing.<\/p><p>Both are valid approaches, though I prefer to use types and get specific error messages and leverage tools like static analysis, which work better the more it understands your code.<\/p><p>In particular when writing and using open-source code that anyone can use however they like, I'd suggest leveraging types and type-checking, but it depends on what you, your team or your community prefer.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Automating all the things, including infrastructure",
"date": "1671494400",
"permalink": "/archive/2022/12/20/automating-all-the-things,-including-infrastructure",
"text": "<p>I'm a big advocate for automation, from having a reproducible Docker and Docker Compose environment, automated tests, static analysis, and code linting in my projects to running them automatically on every push to a remote repository using a CI pipeline.<\/p><p>I've written scripts to simplify common complex tasks and automated my local development environment setup before using tools like Ansible and, recently, the Nix package manager, NixOS and Home Manager.<\/p><p>Another main piece of automation I use is to create and manage the infrastructure my applications run in.<\/p><p>I've talked about it in my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\">Deploying PHP applications with Ansible and Ansistrano talk<\/a>, that before you can deploy an application, you need a server with the required packages installed to run it. You may also need a CDN endpoint, SSL certificate, DNS records, CORS policy, database server, container registry, object storage bucket or a number of various other things.<\/p><p>Using automation tools like Terraform, Pulumi or Ansible, you can run a single command to create, update or destroy resources or your entire stack.<\/p><p>The automation code acts as living documentation, can be version-controlled, stored alongside the code, and read by the Developers or anyone else involved with the project.<\/p><p>If you need to hand over the hosting requirements to a client or create their own version, you can do that with the same automation code.<\/p><p>And if a disaster scenario was to happen and you needed to recreate your infrastructure from scratch or move to a different cloud provider, you could do that quickly using automation tools, knowing that the new infrastructure would be consistent with the original, all of the pieces would be in place, and without needing to recreate everything manually from scratch.<\/p>",
"cta": "",
"tags": ["automation","devops"]
}, {
"title": "Happy Drupal 10 release day!",
"date": "1671062400",
"permalink": "/archive/2022/12/15/happy-drupal-10-release-day",
"text": "<p>Today, Drupal 10 was released alongside Drupal 9.5.<\/p><p>This means that, as of today, Drupal 9.3 is no longer supported, so people should update to 9.4, 9.5, or 10.<\/p><p>As things stand, Drupal 7 is still supported until November 2023.<\/p><p>I haven't tried upgrading any existing websites from Drupal 9 to 10 yet, but I have already started a new client project with Drupal 10.<\/p><p>It's a project for a new client that we've been discussing for a few months, and we wanted to wait until Drupal 10 was released before starting. My preparation work has been on the release candidate version of Drupal 10, so I can't foresee any issues updating to the stable 10.0.0 version.<\/p><p>As an open-source Drupal project maintainer, I'll soon release Drupal 10 compatible versions of my maintained modules and themes, such as Override Node Options and the Tailwind CSS starter kit theme.<\/p><p>If your company has a Drupal module that needs to be upgraded to be Drupal 10 compatible, or needs a module to integrate your service with Drupal 10, reply to this email and let's arrange a call and see if we can work together.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Managing databases with Neovim and Docker",
"date": "1670630400",
"permalink": "/archive/2022/12/10/managing-databases-with-neovim-and-docker",
"text": "<p>If you work on software projects that use a database, you need a convenient way to connect, inspect, and query them.<\/p><p>Some IDEs like PhpStorm have an integrated database client, which I've recently added to my Neovim setup and working with Docker and Docker Compose.<\/p><h2 id=\"configuring-docker-compose\">Configuring Docker Compose<\/h2><p>A local port needs to be exposed from the database container that Neovim can connect to.<\/p><p>I usually do this with a <code>docker-compose.override.yaml<\/code> file:<\/p><pre><code class=\"language-yaml\">services: database: ports: - 3307:3306<\/code><\/pre><p>Docker Compose recognises this by default, extends the normal <code>docker-compose.yaml<\/code> file and adds a port forwarding to the <code>database<\/code> service.<\/p><h2 id=\"configuring-neovim\">Configuring Neovim<\/h2><p>The two plugins I'm using are tpope\/vim-dadbod and kristijanhusak\/vim-dadbod-ui, and should work with Vim and Neovim. Thanks to both of these project maintainers.<\/p><p>Once installed, run <code>:DBUIAddconnection<\/code> to add a database connection.<\/p><p>Here is an example connection string:<\/p><pre><code>mysql:\/\/drupal:drupal@localhost:3307\/drupal?protocol=tcp<\/code><\/pre><p>Using the local port mapping, this connects to a MySQL database within the <code>database<\/code> service.<\/p><p>Then run <code>:DBUI<\/code> to toggle the UI and see a list of databases in the left-hand sidebar.<\/p><p>You can enter <code>&lt;leader&gt;R<\/code> to refresh databases or <code>r<\/code> to rename or update connection details for a specific database.<\/p><p>Once connected, you can enter and save queries, using table and column name completion, which are executed every time the query is saved.<\/p><p>I like not needing to switch contexts and leave my editor in order to query a database, and feel a lot more productive being able to write, execute and save queries within this UI.<\/p><p>If you're a Vim or Neovim user, I'd suggest trying this setup and seeing if it works for you.<\/p>",
"cta": "",
"tags": ["docker","neovim"]
}, {
"title": "How and why I started using PostCSS",
"date": "1670544000",
"permalink": "/archive/2022/12/09/how-and-why-i-started-using-postcss",
"text": "<p>I assume that, like many other Developers, when I started learning front-end development, I wrote normal, plain CSS and later discovered and adopted pre-processors like Less and Sass that added features such as variables and nesting to my stylesheets.<\/p><p>This was the case when I first saw what became Tailwind CSS, which were some stylesheets written in Less and ported manually between projects.<\/p><p>I remember watching one of those streams, and a fellow viewer suggested PostCSS, which Tailwind CSS would later be written in.<\/p><p>PostCSS, a CSS post-processor rather than a pre-processor, has become my preferred way of writing CSS because of Tailwind.<\/p><p>When I started using Tailwind in my projects, I was layering it on top of another CSS framework or styles that were written using Less or Sass, so I needed to pre-process them into CSS first and then run PostCSS - essentially running two build steps and adding to the build time.<\/p><p>I moved to use PostCSS by default - removing one of the build steps.<\/p><p>What I liked about it, as well as the quicker build times, was that I could start with plain CSS and add the extra features I needed. I didn't use all of Sass and Less' features, and now, if I needed nesting or real-time imports, I could add it via a PostCSS plugin or write my own.<\/p><p>It's also quick and easy to use, using the PostCSS CLI tool and without more complex tools like Webpack.<\/p><p>If you haven't tried PostCSS, I recommend taking a look.<\/p>",
"cta": "",
"tags": ["css","front-end"]
}, {
"title": "The Decorator design pattern",
"date": "1670457600",
"permalink": "/archive/2022/12/08/the-decorator-design-pattern",
"text": "<p>Decorator is a structural design pattern that allows you to add extra functionality, such as if you want to add caching or logging to a service, without changing the original class.<\/p><p>As long as a class implements an Interface, it can be decorated.<\/p><p>For example, if I have this PHP interface:<\/p><pre><code class=\"language-php\">interface DoesSomething{ public function doSomething(): void;}<\/code><\/pre><p>I could have this class that does something:<\/p><pre><code class=\"language-php\">final class FirstClass implements DoesSomething{ public function doSomething(): void { \/\/ Does something. }}<\/code><\/pre><p>If I need to do something else, like caching or logging the result, I can decorate it.<\/p><p>To do this, I need another class that implements the same interface and inject the original version.<\/p><pre><code class=\"language-php\">final class SecondClass implements DoesSomething{ public function __constuct( private DoesSomething $originalClass ) {} public function doSomething() { \/\/ Do something else before. $this-&gt;originalClass-&gt;doSomething(); \/\/ Do something else afterwards. }}<\/code><\/pre><p>Within the new class, the methods can be overridden, extra functionality can be added, and the original method can be run to execute the original functionality.<\/p><p>As the two classes implement the same interface, I can swap between different versions and decorate multiple times if needed.<\/p><p>This a pattern that I used recently to extend a service that retrieved some data from an API and saved it to a file, to change some arguments and do more work with it.<\/p><p>The original class was unchanged, the new class was minimal and easy to understand as it only had a single responsibility, and if I needed to switch back to the original version, I could easily do that.<\/p>",
"cta": "",
"tags": ["design-patterns"]
}, {
"title": "Separating releases from deployments with feature flags",
"date": "1670371200",
"permalink": "/archive/2022/12/07/separating-releases-from-deployments-with-feature-flags",
"text": "<p>In a typical feature release process, a feature is released when you merge the code and push it to production.<\/p><p>If a bug is found after the release, the code needs to be reverted (and any conflicts or issues dealt with) and deployed again.<\/p><p>Also, features can only be merged once they are complete, which may take hours, days or weeks, depending on the size of the feature.<\/p><p>These are some reasons I like to use feature flags (aka feature toggles) and separate the code deployment from releasing the feature. The code is deployed as before, but the feature isn't released, and the code isn't executed until a feature flag is enabled.<\/p><p>If there is a bug, the feature flag can be disabled, and the feature is turned off until a fix can be pushed - without needing another code deployment.<\/p><p>If my feature is incomplete, if it's feature flagged, I can commit and deploy it without users seeing it or affecting the running application, resulting in smaller and more manageable commits and deployments.<\/p><p>If you wanted, you could enable a feature flag for a subset or a certain subsection of your users - allowing them to test it before making it available to everyone.<\/p><p>Another way I use feature flags is within a <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/11\/13\/how-i-manage-multiple-drupal-websites-using-the-same-codebase\">multi-site Drupal application<\/a> to enable a different feature set per site and allow me to keep one version of the code for all sites to keep this easy to manage and maintain.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Should you comment your code?",
"date": "1670284800",
"permalink": "/archive/2022/12/06/should-you-comment-your-code",
"text": "<p>Something that I hear often is \"self-documenting code\", and that code should be easy to understand without comments.<\/p><p>If you need to write a comment explaining what something does, move the code into a new class or function and have its name describe what it does.<\/p><p>I agree with this, but I still think there is a place for comments within the code as long as they add value.<\/p><h2 id=\"what-comments-shouldn%27t-be\">What comments shouldn't be<\/h2><p>Comments shouldn't just repeat what the code says.<\/p><p>If the comment says \"Returns false\", and I can read that from the code, the comment isn't adding any value.<\/p><p>I use types a lot in PHP and TypeScript, and if docblocks are just repeating the native types, I'd rather not include them and keep the code minimal.<\/p><p>Comments like \"Constructor\" and \"This shouldn't happen\" add no context.<\/p><h2 id=\"what-comments-should-be\">What comments should be<\/h2><p>Comments need to add value by adding extra information or explaining why the code does what it does.<\/p><p>I will add comments like \"This class decorates ... so that ...\" and \"This returns ... if ...\". These comments add value and make the code easier to read and understand. The downside is that you then need to maintain the comments, make sure they remain correct, and if the functionality changes the comment is also changed.<\/p><p>If a static analysis tool requires me to provide more information in a docblock that describes some parameters or a return type, I'll do that. It makes the code quality better, reduces bugs, and makes the Developer experience better. As I'm improving the native types by providing more information, I'm not just repeating them so this is OK with me.<\/p><p>Comments should make the code easier to read, understand, and work with for yourself and other team members.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Outcomes or output",
"date": "1670198400",
"permalink": "/archive/2022/12/05/outcomes-or-output",
"text": "<p>I was reading a Twitter thread recently that <a href=\"https:\/\/twitter.com\/allenholub\/status\/1594786089994067969\">started with this tweet<\/a>.<\/p><p>TL;DR:<\/p><blockquote> <p>\"Measuring output (e.g. velocity) is a waste of time. It's outcomes you care about - customer happiness.\"<\/p><\/blockquote><p>This is definitely something that I agree with.<\/p><p>I can't remember the last time I looked at an output burndown chart or a velocity score.<\/p><p>I'd rather focus on what outcomes have been delivered and adding value to clients and customers.<\/p><p>What features did we release, what bugs did we fix, and what impact and value did that provide?<\/p><p>What increased revenue or improved a customer's experience?<\/p><p>I may have a sprint or cycle where I only deliver one or two large tasks, but those are major features that have been requested, a bug affecting a user's experience, or a task that unblocks future tasks.<\/p><p>In that situation, my velocity may not be good and could be improved by working on multiple smaller tasks, but which outcomes provide the most value?<\/p>",
"cta": "",
"tags": []
}, {
"title": "Writing &quot;Why first&quot; user stories",
"date": "1670112000",
"permalink": "/archive/2022/12/04/writing-why-first-user-stories",
"text": "<p>I've usually written user stories that follow this format:<\/p><p>As a...I want...So that...<\/p><p>You focus on the person who needs the task first, followed by what they want, and why they want it.<\/p><p>Lately, I've been re-ordering stories to follow this order:<\/p><p>So that...As a...I want...<\/p><p>What I like about this is that it focuses on capturing the \"why\" of the story first rather than at the end or maybe even forgetting it altogether.<\/p><p>What's needed and who needs it doesn't matter unless you also capture why it's needed.<\/p>",
"cta": "",
"tags": []
}, {
"title": "What to do with TODO comments",
"date": "1670025600",
"permalink": "/archive/2022/12/03/what-to-do-with-todo-comments",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/11\/20\/version-controlled-commented-out-code\">In a previous email<\/a>, I wrote about commented-out code and whether it should remain in a codebase - especially if it's version controlled and there's a commit log of all changes.<\/p><p>But what about TODO comments that remind you to do something?<\/p><p>When I think of TODO comments, I think of times when I've found them left in codebases from a long time ago by Developers who no longer work on it - never to be looked at again.<\/p><p>I recently removed a small number from a codebase I added while working on the first MVP.<\/p><p>They were comments like \"Move this to a repository\" or \"Remove this hard-coded value and make this configurable\".<\/p><p>These weren't things that would affect the functionality of the code - but nice-to-haves, things that could be done differently, or reminders of things where hard-coded values were fine but would need to be replaced in the future.<\/p><p>Instead of being code comments that only I was aware of, I moved them into the issue-tracking system I'm using. This allows the client to have visibility of them and that they can be scheduled and prioritised alongside other work, providing a truer reflection of the current tasks.<\/p><p>Some have since been addressed, but some will remain and be actioned in the future. If they were still code comments, they might not have been addressed at all, so the issue tracker seems like the better place for them to be.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Commit and push something every day",
"date": "1669939200",
"permalink": "/archive/2022/12/02/commit-and-push-something-every-day",
"text": "<p>One of the significant changes that I've found and that's benefitted me whilst developing is to commit and push something every day.<\/p><p>It doesn't need to be a whole feature. It could be a new class with its passing tests, but it isn't used anywhere yet, so it won't affect the existing functionality, or it could be a new test for some existing functionality that was missing previously.<\/p><p>It could be a small refactor - renaming a variable or class name that makes some code easier to read or removing some commented-out code that isn't doing anything other than adding visual clutter.<\/p><p>It could be updating some documentation or <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/23\/adrs-technical-design-documents\">writing a technical document<\/a>; if you keep those in your version control repository, that would help you implement the following change or to make the documentation clearer for the next reader - whether that's you or someone else.<\/p><p>Committing something at least once a day creates a different mindset to \"I'll write everything and push it when it's done\".<\/p><p>It makes you break up large tasks into multiple smaller ones and set mini-deadlines for yourself. I used to do the same when I commuted to work on a train and had a task for a freelance project to complete before I arrived. I used to think, \"What can I start, finish and commit before I get there?\" instead of leaving something incomplete.<\/p><p>You don't need to push your change to mainline. If you use the <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/11\/30\/ship-show-or-ask\">\"Ship, Show, Ask\" approach<\/a> then you could commit to a temporary branch that you either merge yourself once you know it passes the checks, or to show or get feedback from other team members.<\/p><p>Practicing this becomes a habit, and if you're doing test-driven development and committing after every passing test or refactor, you'll find yourself pushing numerous changes a day.<\/p><p>This became my normal approach instead of having long-lived feature branches or lots of unpushed local commits.<\/p><p>I much prefer making as small charges as possible and pushing them as often as I can.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Writing readable code",
"date": "1669852800",
"permalink": "/archive/2022/12/01/writing-readable-code",
"text": "<p>This week, I needed to investigate and fix a bug within some existing code.<\/p><p>It's code written some time ago and not by anyone working on the team.<\/p><p>The code wasn't very readable, so before I could fix the bug, I needed to figure out what the code was supposed to be doing.<\/p><p>I started to write a list of things that would make the code easier to read and understand - no single-letter variable names, reduced levels of indentation and splitting some nested ternary operators to use separate return statements.<\/p><p>I also watched a video of a conference talk titled \"Writing code you won't hate tomorrow\", which re-introduced me to Object Callisthenics.<\/p><p>They are from \"The ThoughtWorks Anthology\" book and are some steps that include some of the points that I had written:<\/p><ol><li>Use only one level of indentation per method.<\/li><li>Don\u2019t use the else keyword.<\/li><li>Wrap all primitives and strings.<\/li><li>Use only one dot per line.<\/li><li>Don\u2019t abbreviate.<\/li><li>Keep all entities small.<\/li><li>Don\u2019t use any classes with more than two instance variables.<\/li><li>Use first-class collections.<\/li><li>Don\u2019t use any getters\/setters\/properties<\/li><\/ol><p>As well as the original book, there are numerous blog posts and videos on this topic.<\/p><p>Why try some of them on the next code you write and see if it's easier to read and understand?<\/p>",
"cta": "",
"tags": []
}, {
"title": "Ship, Show or Ask",
"date": "1669766400",
"permalink": "/archive/2022/11/30/ship-show-or-ask",
"text": "<p>\"Ship \/ Show \/ Ask\" describes itself as a self-described modern branching strategy that combines the features of pull or merge requests with the ability to keep shipping changes.<\/p><p>Each change is either a \"Ship\", \"Show\", or \"Ask\".<\/p><h2 id=\"ship\">Ship<\/h2><p>\"Ship\" changes are what I most commonly do with continuous integration and trunk-based development projects. Changes are committed directly to the main branch and shipped - assuming that the CI pipeline and any other automated checks pass. There is no blocking code review or pull request for \"Ship\" changes.<\/p><h2 id=\"show\">Show<\/h2><p>\"Show\" changes are made on a temporary branch instead of the mainline. This branch is then used to create a pull request which is closed once the CI checks pass without any code review.<\/p><p>Once the pull request is merged, the change is deployed, but the pull request is still available as somewhere to have feedback and conversation about the change.<\/p><p>This is something that I did today after starting to write a new feature by implementing the Decorator design pattern, and wanted others to be aware of this approach and ask any questions.<\/p><p>Another reason for this approach is if someone wants to ensure that the CI checks will pass before merging to mainline. Some Developers worry about breaking the CI pipeline with a trunk-based approach and blocking others, so want to know that the pipeline will continue to work and they aren't disrupting other team members.<\/p><h2 id=\"ask\">Ask<\/h2><p>This is how I've worked on most projects before, and still with some clients where they want to review changes before merging, or maybe I want to have a discussion and review a change beforehand.<\/p><p>This is also common when new Developers join a project or need to change some code they haven't worked on before.<\/p><h2 id=\"conclusion\">Conclusion<\/h2><p>I like the flexibility and balance of this approach. I prefer to work on \"mostly ship\" projects, and most of the show and ask conversations happen during pair or mob programming sessions.<\/p><p>Some of my clients where I work with teams are \"mostly ask\" and work in a more Git Flow-type way and want to review any changes before they're merged and deployed.<\/p><p>But if you're working on a \"mostly ask\" project and want to move to \"mostly ship\", then aiming to move to \"mostly show\" is a good intermediate step and a way to reduce shipping time or develop and build confidence in the CI pipeline before moving to trunk-based development and removing the manual review step.<\/p><p>The full article with more information is at https:\/\/martinfowler.com\/articles\/ship-show-ask.html.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Plan, then code",
"date": "1669334400",
"permalink": "/archive/2022/11/25/plan-then-code",
"text": "<p>Recently I <a href=\"https:\/\/twitter.com\/OneJKMolina\/status\/1303047499238776832\">saw this tweet<\/a> in a screenshot on a LinkedIn post.<\/p><p>The post was about improving business writing, but the original tweet was about software engineering.<\/p><p>For me, the main sentence within the tweet is, \"Resist the urge to do something before having a plan.\" - or as the LinkedIn post said, \"Resist the urge to start typing before having a plan.\".<\/p><p>This is something that I've focused on a lot over the last few years, always asking, \"What problem are we trying to solve?\" and using flow charts and ADRs or technical design documents to come up with a plan before starting to write any code.<\/p><p>Doing this makes me think of and answer as much as possible upfront - what we need, how things should work, the required steps, and what edge cases and pitfalls there might be. I'll usually have two or three solutions I'll consider and document, as well as which I decided to use and why.<\/p><p>Once I've planned the solution, coding is usually very fast and straightforward, as most or all questions should already have been answered. I don't need to stop and answer questions whilst writing the code, and the code should be cleaner as I'm coding to the plan rather than figuring it out as I go.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Doing the simplest possible thing",
"date": "1669248000",
"permalink": "/archive/2022/11/24/doing-the-simplest-possible-thing",
"text": "<p>I spent most of today working on some code I wrote for the first phase of a client project a few months ago.<\/p><p>The previous version used hard-coded data within a Vue.js application, which was sufficient for the previous criteria and in line with the lean approach we decided to take.<\/p><p>It was the simplest thing that worked.<\/p><p>A new requirement means that the hard-coded data no longer works, so I need to refactor and enhance the code to work with different configurations. I have a proof of concept of this working using JSON from an API endpoint, but I would also like to use a static JSON file when needed for local development.<\/p><p>I experimented with a few different ways to approach this before asking myself, \"What's the simplest possible thing I can do to get this working?\".<\/p><p>I already knew that I needed to make a change to the structure of the data, which I was able to do quickly with the hard-coded data that I already had, and whilst a static JSON file would be a nice-to-have, I could quickly move the hard-coded data into the API endpoint that I'd already created and continue building on my proof of concept.<\/p><p>The idea of \"What's the simplest thing?\" is something that I use regularly.<\/p><p>When teaching or coaching test-driven development, I want to write the smallest failing test and then find the quickest and simplest way to get it to pass - even if it means returning a hard-coded value for now.<\/p><p>When working on development tasks, I like to break things down as much as possible and find the smallest thing I can do, commit, and push. This gets the ball rolling, and then I repeat the process.<\/p><p>Even when writing an email or blog post, once I start writing, it's much easier to continue once I'm in the flow.<\/p><p>Taking the simplest approach and not making assumptions about future requirements or scope means less and more maintainable code, as well as being a productivity hack.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Do you need to branch if you&#039;re the only one working on a project?",
"date": "1669161600",
"permalink": "/archive/2022/11/23/do-you-need-to-branch",
"text": "<p>Yesterday, I <a href=\"https:\/\/twitter.com\/scottkeckwarren\/status\/1594752744165847040\">saw a tweet<\/a> where the writer said they were \u201cfalling into the branch, pull request, and merge after actions pass I use at work even though I'm the only one working on it\u201d.<\/p><p>After reading this, my question is, \"Should you, or do you need to, create branches if you're the only person working on a project?\".<\/p><p>These days, I use trunk-based development as much as possible, so I hardly ever create new branches, whether working on a project myself or with a team.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/talks\/git-flow\">I used to use Git Flow<\/a> and create branches for every new feature and bug fix, but I remember, whilst demonstrating two work-in-progress features to a client, switching between the different branches caused my local site to break. Whilst it wasn\u2019t a major issue, it wouldn't have seemed professional.<\/p><p>In a team environment, feature branches are intended to keep different changes and different people's work separate.<\/p><p>But is this needed if you\u2019re the only in the team?<\/p><p>Assumingly, you're only working on one change at a time, so what's the benefit of creating a separate branch?<\/p><p>If you need to switch to a different task, another approach could be to revert your work-in-progress commits, move them onto another local branch temporarily, or wrap them within a feature flag so that the changes are committed but not active.<\/p><p>The other part of the tweet said, \u201cI like the little integrations to make sure the tests pass\u201d.<\/p><p>I\u2019m comfortable working on a single branch and committing and pushing small changes often.<\/p><p>My CI pipelines run for every change that I push, and if one fails, I\u2019ll either push a small fix to get it passing again or revert the failing change and investigate further.<\/p><p>For me, working on a single branch keeps my workflow simple and lean, allowing me to focus on the changes and the tasks that I need to work on and not worry about which branch I\u2019m working on.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "tldr",
"date": "1669075200",
"permalink": "/archive/2022/11/22/tldr",
"text": "<p><code>tldr<\/code> is a command-line tool that I've been using a lot recently.<\/p><p>Usually, on the command line, you'd use the <code>man<\/code> command to show a manual page for a certain command - like <code>man ls<\/code>.<\/p><p><code>tldr<\/code> is \"a collection of simplified and community-driven man pages\".<\/p><p>After installing it, run <code>man tldr<\/code> or even <code>tldr tldr<\/code> to learn more about it.<\/p><p>Then, run a command like <code>tldr ls<\/code> to get output for a specific command.<\/p><p>I like that it shows a short description of what the command does, followed by a link to find out more information and then several valuable examples demonstrating the various options, flags, and arguments the command takes.<\/p><p>For <code>ls<\/code>, it shows how to list one file per line, list hidden files, use a long format list, show human-readable size units, long format sorted by size or modification date, and only show directories.<\/p><p>For commands like <code>tar<\/code>, <code>rsync<\/code>, and <code>scp<\/code> that I don't use that often or can't remember all of the different options, I like being able to see these examples and figure out what I need at that time.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Git tricks to avoid committing commented-out and other unneeded code",
"date": "1668988800",
"permalink": "/archive/2022/11/21/git-tricks-to-avoid-committing-commented-out-and-other-unneeded-code",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/11\/20\/version-controlled-commented-out-code\">Yesterday's email<\/a> talked about whether commented-out code should be present if your code is version-controlled, but how do you avoid committing it in the first place?<\/p><p>You could make sure that you remove everything manually before you stage and commit your changes, or I like to use <code>git add --patch<\/code> (or <code>git add -p<\/code>) to interactively stage my changes, allowing me to select which parts of files I want to include in my commit and ignore anything else. The <code>--patch<\/code> option also works for other commands, including <code>checkout<\/code> and <code>reset<\/code>.<\/p><p>If you've already committed something like some debug code, you can use <code>git commit --amend<\/code> to amend the previous commit before pushing it, or if you have a separate clean-up commit, you can use <code>git rebase --interactive<\/code> and either the squash or fixup options to amend the original commit.<\/p><p>If some old code has been removed and you want to find it, you can use <code>git log -S<\/code> with a string to search for, and Git will show a list of commits where the specified string was changed.<\/p><p>If instead, you wanted to search for text within the commit message, you can use <code>git log --grep<\/code> with a string like an issue number to see a list of commits with that text in the commit message subject line or body.<\/p><p>I hope these tips help keep unwanted code out of your version-control repository.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Version-controlled commented-out code",
"date": "1668902400",
"permalink": "/archive/2022/11/20/version-controlled-commented-out-code",
"text": "<p>Today, whilst debugging some legacy code within an application, I found several blocks of commented-out code.<\/p><p>Some were previous debugging code which had been commented out, and some were old components or previous implementations - but instead of being removed when they were no longer needed, they remained in the codebase as commented-out lines - inactive but adding noise and complexity around the code that I was trying to understand and debug.<\/p><p>To make it easier for me to figure out this code, I'd like it to be as clean to read and as simple to understand as possible.<\/p><p>The codebase is version-controlled, so why would there be a need to comment out and keep the lines?<\/p><p>Version control systems have a log of each change, so if you need to see previous changes, you can view the log and see what changed, when, and by who.<\/p><p>You can also see any other files that were changed in the same commit, and usually, there will be a reference to the issue or ticket that required that change.<\/p><p>If you need to re-add a change that had been removed, you can either do this manually or by reverting the commit.<\/p><p>Should there be commented-out code within a codebase if it's version controlled? I'd say no unless there's a good reason for it to be there and it's providing some additional context or for a specific purpose. If it's an outdated implementation, some old debugging code, or a component that's no longer needed, I think that it should be removed, and people can use version control tools to find or re-introduce those changes if needed.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Are missing tests a blocker to refactoring?",
"date": "1668816000",
"permalink": "/archive/2022/11/19/are-missing-tests-a-blocker-to-refactoring",
"text": "<p>Is having automated tests a prerequisite for refactoring a piece of code?<\/p><p>Without passing tests for that code, any changes made could introduce a regression, and bugs can be accidentally introduced.<\/p><p>When refactoring with tests, you run them before making any changes to ensure they pass. The tests are rerun after every change to ensure that they still pass and that the change didn't introduce a regression that caused the test to fail. If a test fails, the change is reverted and re-attempted.<\/p><p>If I need to refactor some code without tests, the first thing that I'll do is add some initial tests before the main work.<\/p><p>Whilst nothing is stopping me from refactoring without the tests, the risk isn't something that I'd want to take on, and I'd much prefer to have some tests in place - just in case!<\/p>",
"cta": "",
"tags": []
}, {
"title": "One test a day keeps bugs away",
"date": "1668729600",
"permalink": "/archive/2022/11/18/one-test-a-day-keeps-bugs-away",
"text": "<p>This is a quote from a presentation by Diego Aguiar at SymfonyCon that I saw from <a href=\"https:\/\/twitter.com\/SymfonyCasts\/status\/1593551105471938560?t=A8wnRUa0tLbb2q5qLhcQnA\">a tweet from SymfonyCasts<\/a>.<\/p><p>I haven't seen the rest of the presentation, but I liked this quote and the idea of continuously improving a codebase using automated tests.<\/p><p>The talk was titled \"Advanced Test Driven Development\" so I assume that it was focused on ensuring that new functionality also has accompanying tests but it could also apply to existing code.<\/p><p>A lot of existing code that I've worked on wasn't covered by tests, so going back and writing tests for that code would be beneficial too - even if it's only one test a day. It would help to prevent and uncover existing bugs, enable the code to be refactored and changed without introducing regressions, and make the codebase more maintainable.<\/p><p>Small changes over time add up.<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "Agnostic CI pipelines with run files",
"date": "1668643200",
"permalink": "/archive/2022/11/17/agnostic-ci-pipelines-with-run-files",
"text": "<p>As I work on various projects, I use several different CI tools, such as GitHub Actions, Bitbucket Pipelines, and GitLab CI, as well as hosting providers that have build and deploy steps.<\/p><p>Some only run continuous integration checks, like automated tests and static analysis, some build and push Docker images, and some use Ansible and Ansistrano to deploy the changes to production.<\/p><p>Each tool has its configuration file with different settings and formats.<\/p><p>Rather than being too tightly coupled to a particular tool, I like to keep things as agnostic as possible and <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/15\/using-run-file-simplify-project-tasks\">use a run file<\/a> with separate <code>ci:build<\/code> and <code>ci:deploy<\/code> tasks.<\/p><p>This means that all the logic is within the run file rather than the CI tool-specific configuration file, so the file is shorter and cleaner; I can make changes to the CI tasks locally and quickly test changes and iterate, and also, as the logic is within the run file, I can easily switch to a different CI tool if needed without making changes to the tasks themselves.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why don&#039;t you write automated tests?",
"date": "1668556800",
"permalink": "/archive/2022/11/16/why-don&#039;t-you-write-automated-tests",
"text": "<p>Many projects I\u2019ve worked on in the past haven\u2019t had an automated test suite.<\/p><p>If you don't or can't write tests for your project for some reason, I'd love it if you could reply to this email or <a href=\"https:\/\/twitter.com\/opdavies\">let me know on Twitter<\/a> and let me know why.<\/p><p>I know some of the classic reasons, like \"I don't have time\" and \"My clients won't pay for me to write them\", but I'd like to get some more real-world examples.<\/p><p>Then I'll do some follow-up posts to look into and address them.<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "Writing good automated test names",
"date": "1668470400",
"permalink": "/archive/2022/11/15/writing-good-automated-test-names",
"text": "<p>Something that I often see in code examples or tutorials are test methods like <code>testGet<\/code> or <code>testAdd<\/code>, or <code>testSubtract<\/code>. Short method names that don't describe the scenario that they're testing in much detail.<\/p><p>What if a <code>get<\/code> method returns different types of value based on the input or a string is passed into a calculator method like <code>add<\/code> or <code>subtract<\/code>?<\/p><p>I'd assume that the result of the calculation returns the total, but the test method doesn't say this.<\/p><p>I'd rather be overly descriptive and write methods like <code>should_add_two_or_more_numbers_and_return_the_total()<\/code> rather than <code>testAdd<\/code>. It's a lot more readable and easier to see what the intention of the test is, and it's much better to use longer descriptive names when using options like <code>--testdox<\/code> with PHPUnit, which converts the method name into a sentence, which is what I do when running tests in CI pipelines.<\/p><p>Something that I've picked up and recommend is to start each test case with the word \"It\" or \"Should\". This gives it a more behavioural feel and puts you in the mindset of what you're testing and not the methods that you're executing.<\/p><p>A method like 'testAdd' might make sense within a unit test focusing on a single class and method, but as I usually do outside-in testing - which mostly uses functional and integration tests - this approach works well for me.<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "Camel-case or snake-case for test methods?",
"date": "1668384000",
"permalink": "/archive/2022/11/14/camel-case-or-snake-case-for-test-methods",
"text": "<p>When writing object-orientated code, particularly in PHP, you usually write method names using camel-case letters - such as:<\/p><pre><code class=\"language-php\">public function doSomething(): void { \/\/ ...}<\/code><\/pre><p>This is also true when writing methods within a test class - only that the method name is prefixed with the word <code>test<\/code>:<\/p><pre><code class=\"language-php\">public function testSomething(): void {}<\/code><\/pre><p>This is probably expected and complies with the PSR code style standards like PSR-12.<\/p><p>Something that I've seen some PHP developers and some frameworks prefer is to write their test methods using snake-case letters and commonly removing the <code>test<\/code> prefix in favour of using an annotation:<\/p><pre><code class=\"language-php\">\/** @test *\/public function the_api_should_return_a_200_response_code_if_everything_is_ok(): void { \/\/ ...}<\/code><\/pre><p>This is something that I've done myself for a while, but now I'm starting to reconsider both options.<\/p><p>Whilst it's more readable, especially for longer test names (which I like to write), it's not consistent with method names in non-test files or non-test methods in test files; it looks odd if I need to add another annotation (do I keep a single annotation on one line, or just those with multiple annotations on the separate lines), and to do this, I need to disable some code sniffer rules for code to pass the PHPCS checks.<\/p><p>If I used camel-cased names, I wouldn't need the PHPCS overrides, the annotations would be simpler, and the code would be more consistent - so I think I'll try that way again in the next tests that I write and see how it feels.<\/p><p>Which do you prefer, and which would you expect to see in your project?<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "How I manage multiple Drupal websites using the same codebase",
"date": "1668297600",
"permalink": "/archive/2022/11/13/how-i-manage-multiple-drupal-websites-using-the-same-codebase",
"text": "<p>In my last email, I mentioned that I maintain several Drupal websites for a client using the same codebase, but how do I do that?<\/p><p>The sites use Drupal's multisite functionality to have a separate directory for each site, each with its own settings file and files, and potentially modules and themes. Whilst there are some downsides to this approach, and we did evaluate alternatives, this approach allows us to keep one hosting account and save the client money compared to hosting each site separately.<\/p><p>Each site has a separate database and configuration files, so out of the box, I can customise what functionality is needed on each site by turning modules on and off. Whilst this is fine for larger pieces of functionality, for smaller pieces I like to use feature flags.<\/p><p>I use feature flags on single-site projects to separate deploying code from releasing a change, but I can also use them here to toggle something per-site. This could be using a module like <a href=\"https:\/\/www.drupal.org\/project\/feature_toggle\">Feature toggle<\/a> or another way like a checkbox on a settings form. Anything that I can use to say \"Do this if that is enabled\".<\/p><p>Settings such as setting an endpoint URL or storing some API credentials would be set in an admin form and stored as configuration per site.<\/p><p>I've tried various iterations of this - initially duplicating the custom code and having several near-identical versions of the same modules (this wasn't good for maintenance). We also used environment variables. However, this didn't scale as I added more sites and needed to create a new set of environment variables every time.<\/p><p>This approach has worked well for the last few years on their original websites and should continue to work well as I upgrade and migrate them to their next versions.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Building a minimum viable product and managing technical debt",
"date": "1668211200",
"permalink": "/archive/2022/11/12/building-a-minimum-viable-product-and-managing-technical-debt",
"text": "<p>Yesterday's email was about a proof-of-concept application that I\u2019d quickly built to validate an idea and explore some initial approaches.<\/p><p>Today, I\u2019ve been working on a client project that I\u2019ve improved and maintained for a few years.<\/p><p>When I started working with this client, they had one website, built with Drupal 7 and Drupal Commerce. Now, there are x websites using the same codebase due to Drupal\u2019s multi-site functionality.<\/p><p>My main task for the last few months has been to get one of their sites onto Drupal 9 (which I did, it went live in October).<\/p><p>This first site was the \"minimum viable product\" (MVP) - the least amount of functionality required to make it releasable to customers. This is different to a proof of concept which is to validate the idea and start a conversation about requirements and scope - where we define the MVP.<\/p><p>For example, there is the ability to create products and product variations from a CSV file. It loads the file from disk and creates the products, but it doesn't update a product variation if a row with an existing SKU is changed, or disable the variation if a row is removed from the file. There is no admin UI for the client to upload a file - the only file that it'll use is the one that's path is hard-coded within the module.<\/p><p>There are user stories for this, but we decided that we didn't need it for the initial launch and that we were happy to take on some technical debt, knowing that we can address it later when the original solutions are no longer sufficient.<\/p><p>Now the minimum viable solution has been released, we can continue to iterate and enhance it based on customers' feedback, add more functionality, and address the technical debt as needed and as requirements require us to do so.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Creating a small proof-of-concept application in an afternoon",
"date": "1668124800",
"permalink": "/archive/2022/11/12/creating-small-proof-of-concept-application-afternoon",
"text": "<p>This morning, I was asked a \u201cCould you build\u2026\u201d question.<\/p><p>It was an idea mentioned a short while ago and involves a simple, interactive form on the front end that sends requests to a public API, filters the results from the response and displays them to the user.<\/p><p>I\u2019d probably want to hide the API request behind a service responsible for interacting with the API and filtering the results - ensuring that the API could be switched with something else later if needed.<\/p><p>This afternoon, I built a small proof-of-concept application with Vue.js and TypeScript.<\/p><p>There\u2019s no API, or service retrieving real-time results. All of the data is hard-coded within the App component, as well as the code that filters, sorts and returns the results.<\/p><p>The results are shown by adding a <code>&lt;pre&gt;&lt;\/pre&gt;<\/code> to the page, with a <code>&lt;pre&gt;&lt;\/pre&gt;<\/code> to show the input data.<\/p><p>There isn\u2019t even any styling, with just some basic horizontal rules to split the page - similar to <a href=\"https:\/\/twitter.com\/taylorotwell\/status\/1203356860818087944\">these screenshots from Taylor Otwell<\/a> of some work-in-progress versions of Vapor and Nova.<\/p><p>A working proof of concept, or a \"spike\", answers the initial \"Can we build...\" question. It can be shown to a client or other stakeholders, act as a starting point for discussions and requirements gathering and then be turned into user stories. It also allows the Developers to validate their initial thoughts and experiment with different approaches.<\/p><p>If the spike is successful, the idea can then be moved forward and implemented in a full way, otherwise, it can be stopped with a minimal amount of effort and time.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Your conference talk has been accepted",
"date": "1667952000",
"permalink": "/archive/2022/11/09/your-conference-talk-has-been-accepted",
"text": "<p>I\u2019m happy to have had a conference talk proposal accepted for what will be my first in-person conference since DrupalCamp London in February 2020.<\/p><p>I\u2019ll be giving my \"<a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS<\/a>\" talk for the first time since February 2021, and in front of an in-person audience since June 2019.<\/p><p>The talk itself will need some updating. The last time I gave it, Tailwind CSS was on version 2.0.3. It\u2019s now on version 3.2.2 and includes features like the just-in-time engine, arbitrary values and variants, container queries, and a load of new utility classes.<\/p><p>I gave a lot of talks at online events in 2020, so after taking a bit of a break last year, it will be nice to speak in front of an in-person conference audience again.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Are sprints incompatible with Continuous Deployment?",
"date": "1667865600",
"permalink": "/archive/2022/11/08/are-sprints-incompatible-with-continuous-deployment",
"text": "<p>It's been common for me whilst working on software projects to have work organised into sprints or cycles - a period, usually between 1 and 3 weeks, where the team is working on stories and tasks for that project.<\/p><p>In my experience, those changes are usually released at the end of that cycle. But it seems that's not always the case; see <a href=\"https:\/\/scrumdictionary.com\/term\/release-sprint\">release sprints<\/a>:<\/p><blockquote> <p>A specialised sprint whose purpose is to release deliverable results; it contains stories specific to release activities and finishing undone work. A release sprint usually contains no additional development.<\/p><\/blockquote><p>If we worked in two-week cycles and released at the end of each one, it would be at least two weeks before a change could be deployed to production. But what if we wanted to follow continuous deployment and release more frequently? Maybe daily or hourly?<\/p><p>Instead of waiting for a release sprint, if we released multiple times within a single sprint, how would this fit into or affect the process?<\/p><p>Does the release cycle need to be tightly coupled to the sprint cycle or can they be separate and independent of each other?<\/p><p>I've worked on projects - including a current one - where I've done multiple releases in a sprint, so of course, it can be done from a technical perspective, but how do we get the best from both processes - whether they work together or separately?<\/p><p>This is something that I'm going to continue to experiment with, iterate on, and learn more about going forward.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Refactoring one large test into multiple smaller tests",
"date": "1667088000",
"permalink": "/archive/2022/10/30/refactoring-one-large-test-into-multiple-smaller-tests",
"text": "<p>Today I spent some time refactoring a large test within a client project, splitting it into several smaller tests. The commit removed 169 lines but added 233 lines.<\/p><p>So, why did I do this?<\/p><p>This test is responsible for testing the creation of products and product variants within Drupal Commerce from a custom CSV file and originally had a very generic name - \"Should create a product and product variations from an array of data\".<\/p><p>But it did much more than that:<\/p><ol><li>It asserted that there are no initial existing products or product variations.<\/li><li>It ran a product import using some stub data.<\/li><li>It asserted that there are two products, each with two variations.<\/li><li>It asserted that each product has the correct title.<\/li><li>It asserted that each product variation has the correct title.<\/li><li>It asserted that each variation has the correct SKU.<\/li><li>It asserted that each variation has the correct price.<\/li><li>It asserted that each variation has the correct value for 10 product attributes.<\/li><\/ol><p>All of this was hidden within a single test.<\/p><p>Whilst it was great as the original test name (I usually start with a vague name whilst I'm spiking the first test and until it's clearer to me what it's testing and what the correct name is), what I actually want this test to do is to check that the correct number of products and variations are created.<\/p><p>This refactoring task was to split the remaining assertions into their own named tests, after which I had six different tests.<\/p><p>This means that each piece of functionality and related assertions are now contained within their own named tests. I can read the test file and see the expected functionality within the test names rather than everything being grouped and hidden within a single vaguely-named test.<\/p><p>If an assertion fails, I can easily see in which test the failure occurred.<\/p><p>Each test is very simple and only a few lines long - it runs the product import, loads the created variation, and runs the appropriate assertions.<\/p><p>It'll be much easier to add new functionality to the importer by adding a new separate test rather than continuously adding to the large original one.<\/p><p>Even though there are more lines in the file after the refactoring, most of those are just because of adding the additional test functions. There are only 72 lines of actual test methods, and the reusable steps, such as running the product import as well as custom assertions, are defined as private methods to avoid duplication.<\/p><p>In my opinion, this was a good refactor to do, and now was a good time to do it before we get started on the next phase of the project.<\/p>",
"cta": "",
"tags": ["php","phpunit"]
}, {
"title": "The open-source-first development workflow",
"date": "1667001600",
"permalink": "/archive/2022/10/29/the-open-source-first-development-workflow",
"text": "<p>Yesterday's email talked about <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/10\/28\/why-write-framework-agnostic-packages\">writing reusable, framework-agnostic packages<\/a> but didn't mention where those packages could be located.<\/p><p>They could be kept within a private repository and still have the same benefits, such as re-usability for internal projects, but I like to open-source code as often as I can and make it available publicly to see and use.<\/p><p>My preference is to follow an open-source-first workflow, identify which parts of a solution can be open-sourced and create them as open-source libraries or modules from the beginning rather than planning to extract them later. They can then be included within the main project using a dependency manager tool like Composer, npm or Yarn.<\/p><p>The eBook integration project that I mentioned was an example of this. I identified which pieces could be open-sourced, set up a public repository and put together an MVP based on that project's requirements. Issues were created for nice-to-have additions that could be added later, and the working version was installed with Composer.<\/p><p>There was no need to extract the code from the main project, no need to \"clean it up\" or check that it contained no client information, and I had the full Git history for the project - not just a new history from the point when the code was extracted and open-sourced.<\/p><p>I've worked on projects that contained a number of potential open-source components that would be released after project completion, but this didn't always happen - I assume due to time pressures to move on to the next project, a focus on adding new features or avoiding the risk of introducing breakages into the code. If the code had been open-sourced from the beginning, these things wouldn't have been an issue.<\/p><p>I've also worked on projects where I've followed an open-source-first approach and released a number of PHP libraries and Drupal modules, including <a href=\"https:\/\/www.drupal.org\/project\/private_message_queue\">Private Message Queue<\/a>, <a href=\"https:\/\/www.drupal.org\/project\/system_user\">System User<\/a>, and <a href=\"https:\/\/www.drupal.org\/project\/null_user\">Null User<\/a> modules. I've also been working on some legacy code recently and started to replace it with a library that I've already open-sourced, even though I'm in the early stages of developing it.<\/p><p>As someone who enjoys creating and working on open-source software, I would encourage you to open-source your code if you can and to do so sooner rather than later and not wait until the end of your project.<\/p>",
"cta": "",
"tags": ["open-source"]
}, {
"title": "Why write framework agnostic packages?",
"date": "1666915200",
"permalink": "/archive/2022/10/28/why-write-framework-agnostic-packages",
"text": "<p>A couple of years ago, I wrote an integration for a client's Drupal Commerce website with an online eBook service as they wanted to sell eBook variations of their products.<\/p><p>They provided me with some example code for different PHP frameworks, each were separate and tightly-coupled to each framework, so there was no code shared between them. Because of this, and because there was no Drupal Commerce example, I wrote my own version.<\/p><p>However, I decided to make my version as reusable and loosely-coupled as possible. This meant that I'd be able to potentially reuse it for other clients and the same code could be used for different implementations.<\/p><p>Reusable code such as the configuration, different types of Requests, value objects for Customers, Orders and OrderItems, were all written within a separate, reusable PHP library. It contains it's own tests, has it's own CI pipeline, and it's own static analysis - ensuring that things work as expected.<\/p><p>With this code separated, the Drupal module was much smaller and responsible only for bridging the library's code with Drupal Commerce and adding any other Drupal-specific code.<\/p><p>The client is currently considering an upgrade from Drupal 7 to Drupal 9, which would also mean upgrading this module. But, with this approach, there's a lot less to upgrade. The library code can still be used, and I can focus on any Drupal-specific changes within the Drupal module.<\/p><p>I recently had an enquiry from someone who needs an integration with the same service. Whilst their requirements may be different, I could still re-use the reusable library code, and write any client-specific code within a custom module.<\/p><p>Finally, if I wanted to reuse this code within a different PHP eCommerce framework then I could by installing the library with Composer. This means that I'd get the same code without needing to manually copy it, keeping a single source that can be maintained separately upstream. I'd get the same code that I'm already familiar with, so I could focus only on how to integrate the library with that framework - again meaning less framework-specific code and a much lower development effort.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Getting back into live streaming",
"date": "1666828800",
"permalink": "/archive/2022/10/27/getting-back-into-live-streaming",
"text": "<p>Surprisingly, it's been two and a half years since I last did a live coding stream.<\/p><p>As well as talk recordings and demos, I did a few live streams back then, working on the \"Test-Driven Drupal\" project and submitting a merge request to Drupal core.<\/p><p>It's been something that I'd like to get back into and pick up again, and I plan on doing that within the next few weeks.<\/p><p>I have a new freelance project due to start in December but getting back into streaming seems like a good way to make sure that I put aside time for open-source and side projects, as well as for writing longer form blog posts and hopefully starting to prepare more meetup and conference talks again.<\/p><p>I'll be streaming again on my YouTube channel, so if you'd like to be notified when I do, <a href=\"https:\/\/www.youtube.com\/channel\/UCkeK0qF9HHUPQH_fvn4ghqQ?sub_confirmation=1\">please subscribe<\/a>.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Neovim as a Personalised Development Environment",
"date": "1666742400",
"permalink": "/archive/2022/10/26/neovim-as-a-personalised-development-environment",
"text": "<p>A few months ago, TJ DeVries (a Neovim core team member) coined the phrase \"Personalised Development Environment\" or PDE.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/blog\/going-full-vim\">I've been using Neovim full-time<\/a> since July 2021 - starting with no configuration to configuring it with Vimscript and later with Lua - setting options like line numbers and relative numbers, tabs and spaces, and indent and fold levels.<\/p><p>I evaluated and installed some initial plugins to add functionality that I needed. Some of them I still use, and some I've replaced with alternative plugins or built-in solutions that have been included in newer versions of Neovim.<\/p><p>I added my own keymaps that made sense to me that either, in my opinion, improved on default keymaps or created new ones that made sense to me or configured a plugin that I'd added.<\/p><p>Recently, I found and added plugins that added a <a href=\"https:\/\/github.com\/rest-nvim\/rest.nvim\">HTTP client<\/a> and a <a href=\"https:\/\/github.com\/kristijanhusak\/vim-dadbod-ui\">database connection manager<\/a> to Neovim - two pieces of functionality that I'd used in other IDEs or separate applications.<\/p><p>I also <a href=\"https:\/\/github.com\/opdavies\/toggle-checkbox.nvim\">wrote my own Neovim plugin<\/a> for toggling checkboxes within Markdown lists.<\/p><p>Like Drupal and other open-source solutions that I use, I love being able to add or edit functionality as needed.<\/p><p>In the last year or so, I've definitely been able to personalise my Neovim setup to meet my needs, and have it work as a fully-fledged solution for PHP and JavaScript development, DevOps work, and technical writing (including this email).<\/p>",
"cta": "",
"tags": ["neovim"]
}, {
"title": "What are Drupal distributions?",
"date": "1666656000",
"permalink": "/archive/2022/10/25/what-are-drupal-distributions",
"text": "<p>Yesterday's email was about the LocalGov Drupal distribution that I've been looking at, but I glossed over what a Drupal distribution is.<\/p><p>It's an interesting topic for me, having <a href=\"https:\/\/www.linuxjournal.com\/content\/speed-your-drupal-development-using-installations-and-distributions\">written an article for Linux Journal<\/a> about it in 2012.<\/p><p>Distributions are pre-configured versions of Drupal that include additional modules, themes, or configuration than you'd get if you installed a standard version of Drupal core.<\/p><p>By default, LocalGov includes content types for service pages, service landing pages and sub-pages, and additional menus and taxonomies, a different administration theme and a base theme to use for custom themes, and multiple additional modules that add alert banners, events, content reviews, search, media types, and sub-sites. This is all in addition to what Drupal core itself provides, and can be extended further with additional contrib or custom modules.<\/p><p>Commerce Kickstart was a distribution for Drupal 7 that added eCommerce functionality such as product and order types, shipping and payment methods, stock levels and discounts. Again, this could be extended further by adding more contrib or custom modules.<\/p><p>A few months ago, I started developing a distribution for managing meetup group websites, like PHP South Wales.<\/p><p>If you're starting a new Drupal website, there could be a distribution that exists that could provide some or all of the functionality that you need, and if new features or fixes are added, then they benefit everyone who uses it.<\/p><p>There are 1,430 distributions listed on https:\/\/www.drupal.org\/project\/project_distribution so take a look there and see if anything matches your needs.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Looking at LocalGov Drupal",
"date": "1666569600",
"permalink": "/archive/2022/10/24/looking-at-localgov-drupal",
"text": "<p>Today, I've been looking at <a href=\"https:\/\/localgovdrupal.org\">LocalGov<\/a> - a Drupal distribution for building council websites, with a focus on code reuse and collaboration.<\/p><p>After a few small changes, I was able to get it running based on my <a href=\"https:\/\/github.com\/opdavies\/docker-examples\">Docker Examples<\/a> repository.<\/p><p>As someone who has worked with one of the Councils who are now using the platform, and was involved in early similar discussions around code reuse and collaboration between Councils, this has been something that I've been keen to try for a while.<\/p><p>I was able to get a basic site running after a fresh installation, and was interested to explore how some of the functionality was built. I've recently been looking at implementing similar functionality to LocalGov's alert banners onto a project and will be able to gain some inspiration from that or will look into the LocalGov version could be used.<\/p><p>I was happy to find some initial ways to contribute back. I had an error during the installation which I was able to fix and assist with in the <a href=\"https:\/\/www.drupal.org\/project\/localgov\/issues\/3307516#comment-14759989\">LocalGov issue queue on Drupal.org<\/a> by answering a support request, and after spotting a potential issue within the alert banner styling, <a href=\"https:\/\/github.com\/localgovdrupal\/localgov_alert_banner\/pull\/225\">submitted a pull request with a fix<\/a>.<\/p><p>I like what the project is doing and agree with its goals, so hopefully I'll get an opportunity to use and contribute more in the future.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Automated testing and test-driven development are not the same",
"date": "1666310400",
"permalink": "/archive/2022/10/21/automated-testing-and-test-driven-development-are-not-the-same",
"text": "<p>Automated testing is where you write tests to ensure that your code works as expected, which can be re-run as needed and executed automatically without user input.<\/p><p>Test-driven development (TDD) is when you write the tests before the production code. You see the tests fail and write code until they pass, and then repeat the process. However, TDD is not just about the tests - it's about the design of the code.<\/p><p>By writing the tests first, you guarantee that the code that you write will be testable, which isn't something that you can't do if the production code is written first.<\/p><p>You may need to refactor your initial working implementation before it can be tested - which means that you could also break it during that time and need to spend time debugging and fixing any regressions. Ideally, you want the tests in place first before any refactoring, so if something breaks, you'll know because of the failing test.<\/p><p>TDD keeps your code cleaner and simpler, as you only write enough code to make the tests pass. Once a test is passing, you stop writing code, so you'll end up with less, simpler code as it's easy to know when to stop.<\/p><p>If you don't write the tests first, you may be tempted to skip writing them completely, leaving untested code or adding <code>TODO: add test<\/code> comments that may never get reviewed.<\/p><p>Also, where's the fun in writing tests for code that you've already written, that you know are going to pass?<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "Cherry picking commits is an anti-pattern",
"date": "1666224000",
"permalink": "/archive/2022/10/20/cherry-picking-commits-is-an-anti-pattern",
"text": "<p><code>git cherry-pick<\/code> is a command that allows you to re-apply changes from existing commits - typically moving commits from one branch to another. Whilst it's good for some use-cases, I believe that it's generally an anti-pattern.<\/p><p>As I mostly do trunk-based development so only have a single branch, it's not a command that I'd run often - but I have seen it used in a Git Flow-type scenario where there are multiple long-lived branches and various other short-lived ones. Commits can be cherry-picked between a long-term branch like <code>develop<\/code> onto a feature branch rather than merging or rebasing, or to re-apply a hotfix from the <code>main<\/code> branch.<\/p><p>The main issue that I've seen with <code>cherry-pick<\/code> is where a number of changes have been merged into a branch which is being used for user acceptance testing by a client or product owner. They decide to approve some of the changes but not all, and the approved commits are cherry-picked onto a production branch and deployed.<\/p><p>In my opinion, this is very risky as there's no guarantee that the cherry-picked changes will work without the others, and as the artifact that's pushed to production is different to what was tested against, it arguably affects the value of doing the testing at all. Ideally, once the release has been tested and approved, the same artifact will be deployed - ensuring consistency and reducing the risk of any errors.<\/p><p>Potentially, the cherry-picked changes could be moved onto a release branch and tested again together without the other changes, but this would increase the testing overhead and the time for the changes to release production.<\/p><p>A good automated test suite would help, ensuring that the tests still pass once the cherry picking is done.<\/p><p>In this situation, I'd rather use feature flags (also known as \"feature toggles\"). This would mean that the code between the two environments would be the same, and allow for functionality to be enabled or disabled as needed. If a feature wasn't selected to be released, then it's feature flag would be disabled until it's approved.<\/p><p>A feature flag would also allow a feature to be switched off if it was causing errors without the need for a code deployment. If a change did need a code change, if you're following continuous integration and delivery, it would be easy to apply and push a fix.<\/p><p>These are the use-cases that I can think of or have seen for <code>git cherry-pick<\/code>. If you know of any others or use <code>cherry-pick<\/code> in your workflow in another way, reply to the email and let me know.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "run file vs task runners",
"date": "1666137600",
"permalink": "/daily/2022/10/19/run-vs-task-runners",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/15\/using-run-file-simplify-project-tasks\">I've written a few earlier emails<\/a> about <code>run<\/code> files - a simple bash file that I add to my projects to simplify or combine common commands that I need to run often.<\/p><p>Recently, I've looked at a couple of alternatives to see how they compare.<\/p><p>One is very YAML based where all commands are written within a YAML file, and one is very Makefile-like and it does fix some of the confusion and issues that I've made with Makefiles in the past - such as passing arguments to commands, and dealing with <code>.PHONY<\/code>.<\/p><p>Whilst I like both of these approaches and that they offer small additional features like auto-completion of task names, after using one of them in a project for a short while, I think that I'm going to stick with the <code>run<\/code> file.<\/p><p>The main reason for this is that I like the simplicity of the <code>run<\/code> file, and that it's just a Bash file that contains functions.<\/p><p>There were a couple of things that I couldn't quite get to work in one of the other tools, such as setting the TTY value in a Docker Command - which is something that I was able to do with bash within the <code>run<\/code> file. The fact that I can write regular bash and reuse existing knowledge is a big plus rather than having to try to learn another syntax or DSL for another tool.<\/p><p>The main reason though is because bash is already installed everywhere. There's no additional tool for Developers to download and install so it keeps the barrier to entry low, and there's no additional dependencies to add to my CI pipeline for it to work.<\/p><p>I was able to use one of these other tools in GitHub Actions as someone had already written a workflow for it, and although I could possibly install it via a package manager, just being able to run a bash file in any CI tool was probably the deciding factor to stick with <code>run<\/code> files.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Pair and mob programming",
"date": "1666051200",
"permalink": "/archive/2022/10/18/pair-mob-programming",
"text": "<p>As well as my recent session at PHP South Wales, I've also been involved with a lot more mob programming recently with members of my team.<\/p><p>We recently added a new feature to our codebase that we completed over a couple of mob sessions - starting by describing the problem and some potential solutions within a <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/23\/adrs-technical-design-documents\">technical design document<\/a> before moving on to the implementation.<\/p><p>I was already familiar with the existing code that we needed to extend, so had some ideas of how to approach parts of the solution which we discussed - but there were other parts that I hadn't thought of.<\/p><p>What was very interesting was that an approach was suggested that I probably wouldn't have thought of myself, which become part of the final solution. This is an advantage of pair programming and is multiplied when working in groups - that you get to include everyone's thoughts, experience and perspective, and collectively decide on the best approach to take in real-time.<\/p><p>As a side effect, we had continuous code review from members of the group, and if we need to work on this code again in the future, everyone will already be familiar with it.<\/p><p>As it was already reviewed, we didn't need to wait before pushing the feature to production so it was delivered quickly and providing value by fixing an issue that someone was experiencing.<\/p><p>We're already working on the next feature as a group, and if you haven't tried pair or mob programming before, I'd recommend that you give it a try.<\/p>",
"cta": "",
"tags": []
}, {
"title": "14 years on Drupal.org and working with PHP and Drupal",
"date": "1665964800",
"permalink": "/archive/2022/10/17/14-years-drupalorg",
"text": "<p>Today I saw that my Drupal.org profile is showing that I\u2019ve been on that website for 14 years.<\/p><p><img src=\"https:\/\/www.oliverdavies.uk\/assets\/images\/14-drupalorg.jpg\" alt=\"A screenshot of my Drupal.org profile showing &quot;On Drupal.org for 14 years 1 hour&quot;.\" \/><\/p><p>Drupal.org is the online home of the open-source Drupal CMS project, and where I registered to ask questions on the forums as I started to learn Drupal. More recently, it\u2019s been where I\u2019ve uploaded and maintain my own contributed projects and contribute patches to others, including Drupal core.<\/p><p>I even spent time working for the Drupal Association on Drupal.org itself.<\/p><p>I've talked about T-shaped Developers in a previous email, and whilst I've added complementary skills to my toolkit over the years, Drupal has been my main specialism and what I focused on when I started freelancing and later switched careers into software development.<\/p><p>With Drupal 10 just around the corner, I'm looking forward to seeing how Drupal continues to evolve and develop.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Overcoming deployment anxiety",
"date": "1665532800",
"permalink": "/archive/2022/10/12/overcoming-deployment-anxiety",
"text": "<p>As a Developer with 15 years of experience, I still sometimes get \"deployment anxiety\" - when I've backed up the database and tagged a release, but even though the CI pipelines are passing and the staging site is working, I'm holding off on pushing the latest code to be released to production - trying to think of any potential issues that could arise from this deployment and avoid any downtime.<\/p><p>When I thought about this further, the releases that I've felt anxious or nervous about have usually been in at one or both of the following categories:<\/p><ul><li>The release includes a lot of changes, and maybe a combination of different types of changes such as framework or CMS updates, bug fixes, or new features.<\/li><li>It's been a long time, maybe weeks or months, since the last production release.<\/li><\/ul><p>The best way to resolve both of these issues, I think, is to break down the large releases into smaller ones, and to deploy them more frequently.<\/p><p>In the opposite scenario, the releases where the changes are small and it's been a short time since the previous release - ideally minutes or hours - have been the ones where I've been the least nervous.<\/p><p>If a single commit is being released, then I can be confident that if there is a failure, I can either revert it and put things back the way they were or quickly identify the issue and push a fix. This isn't the case for large changes as the potential source of the failure is larger and it will take longer to find and fix.<\/p><p>If a bug fix or a feature needs to be reverted, I'm happy knowing that I can do that easily without also reverting the CMS update that was deployed separately - rather than them all being released together.<\/p><p>There are other advantages too - clients or product owners are generally happier if the new feature or fix that they requested is on production within hours or days rather than weeks or months, and having your latest code deployed to production rather than on a staging branch makes it a lot easier if you need to deploy an urgent fix or security update.<\/p><p>If you're familiar with the DevOps Research and Assessment (DORA) team, three of their key metrics are deployment frequency, lead time for changes, and time to restore service. All of these are improved by small and frequent releases.<\/p><p>In my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\">Deployments with Ansible and Ansistrano talk<\/a>, I mention that there is a separate rollback role, but I don't think that I've ever used it.<\/p><p>Because I'm deploying small changes often, it's usually much easier to fix forward than it is to rollback, and knowing this makes me a lot less anxious when deploying changes.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Not long until Drupal 10",
"date": "1665446400",
"permalink": "/daily/2022/10/11/not-long-until-drupal-10",
"text": "<p>I was surprised to see this week that it\u2019s only two months until Drupal 10 is released (14th December 2022).<\/p><p>I\u2019m starting a new Drupal development project in December so will be looking to get that on Drupal 10 as soon as possible.<\/p><p>From the client\u2019s perspective, getting their new project on Drupal 10 and them not needing to upgrade from D9 in the future is a big plus, even if the code differences between D9 and D10 are not that big - similar to Drupal 8 and 9.<\/p><p>As a module maintainer, it\u2019s been great to again see issues being created with automated Drupal 10 compatibility patches - thanks to Rector.<\/p><p>It\u2019s great to see these regular updates and new versions of Drupal, but also for the PHP language, with PHP 7 being end-of-life next month.<\/p><p>It\u2019s a big difference compared to the long-term releases that we had for Drupal 6 and 7, and PHP 5, but one that I definitely prefer.<\/p>",
"cta": "",
"tags": ["drupal","php"]
}, {
"title": "Contributing to open-source software, one small change at a time",
"date": "1665360000",
"permalink": "/daily/2022/10/10/contributing-open-source-software-one-small-change-time",
"text": "<p>Since looking more into Astro, I was looking through the GitHub repository - specifically within the examples - and spotted a typo within the title of one of the examples.<\/p><p>Rather than leaving it, I decided to follow the \"boy-scout rule\" and submit a fix and leave the code in a better state than I found it.<\/p><p>The Astro repository is hosted on GitHub so I was able to fork the repository, fix the typo and create a pull request with a few clicks in the GitHub UI.<\/p><p>Contributing to open-source software - particularly if you're new to it - doesn't mean that you need to always add large and complex changes. Small changes such as fixing a typo, updating documentation, fixing a small bug, or adding additional tests are all valid contributions that improve open-source projects.<\/p>",
"cta": "",
"tags": ["open-source"]
}, {
"title": "Coding defensively, and Implicit vs explicit coding",
"date": "1665273600",
"permalink": "/daily/2022/10/09/coding-defensively-implicit-explicit",
"text": "<p>As well as <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/10\/08\/first-impressions-astro\">being introduced to Astro<\/a> in Simon's most recent Pro Tailwind workshop, something else that we discussed was implicit vs explicit coding, and coding defensively.<\/p><p>For example, if you had this code:<\/p><pre><code class=\"javascript\">const sizeClasses = { small: 'px-3 py-1 text-sm', medium: 'px-5 py-2', large: 'px-7 py-2.5 text-lg',}const shapeClasses = { square: '', rounded: 'rounded', pill: 'rounded-full',}<\/code><\/pre><p>Both the <code>medium<\/code> size and <code>square<\/code> shape have an implicit value.<\/p><p>The <code>small<\/code> size has a text size class of <code>text-sm<\/code> and the <code>large<\/code> size has <code>text-lg<\/code>. As there isn't a text size added for <code>medium<\/code>, it is implicitly <code>text-base<\/code> - the default text size.<\/p><p>Likewise, the <code>rounded<\/code> shape has a class of <code>rounded<\/code> and the <code>pill<\/code> shape has <code>rounded-full<\/code>. As a square button doesn't have any rounding, it has an empty string but it is implicitly <code>rounded-none<\/code> - the default border radius value.<\/p><p>If we were to code this explicitly, <code>text-base<\/code> and <code>rounded-none<\/code> would be added to their respective size and shape classes.<\/p><p>It's mostly personal preference, but explicitly adding the additional classes could potentially future-proof the components if there was a situation where the text size or border radius was being overridden.<\/p><p>It also makes it more obvious to anyone reading the code that these values are being set, rather than them needing to make that assumption - assuming that they're aware of the default values at all.<\/p><p>It's similar to having this example PHP code:<\/p><pre><code class=\"language-php\">function __invoke(string $type, int $limit): void {};<\/code><\/pre><p>Whilst I'm using type hints for the parameters to ensure that the values are a string and an integer respectively, it's also safe to assume that the type shouldn't be an empty string, so do we check for that?<\/p><p>I'd also suggest that the limit shouldn't be a negative integer, so we'd want to check that the value is not less than zero, or if zero isn't being used as an \"all\" value, then we'd want to check that the limit is greater than one.<\/p><p>In this case, the type hints add some explicitness to the parameters, but checking for these additional conditions adds another defensive layer to the code - forcing it to return earlier with an explicit error message rather than causing a vaguer error and elsewhere in the application.<\/p><p>Personally, I like to be explicit and code defensively, making sure that I try and cover as many edge cases as possible and writing test cases for them.<\/p><p>Coming back to the Tailwind example, the majority of us decided to add in extra classes after the exercise and it was an interesting discussion and part of the workshop.<\/p>",
"cta": "",
"tags": ["tailwindcss","php"]
}, {
"title": "First impressions of Astro",
"date": "1665187200",
"permalink": "/daily/2022/10/08/first-impressions-astro",
"text": "<p>This week I attended another of Simon Vrachliotis' Pro Tailwind workshops.<\/p><p>The workshop again was great, teaching us about multi-style Tailwind components, such as a button that has props for variants like size, shape and impact, and how to create them in a flexible and maintainable way as well as making use of Headless UI.<\/p><p>For this workshop though, the examples and challenges used a tool that I wasn't familiar with - the Astro web framework.<\/p><p>I've seen a lot of blog posts and streams mentioning it but I hadn't tried it out for myself until the workshop.<\/p><p>What I find interesting is that it comes with a number of available integrations - from Tailwind CSS, to Vue, React, and Alpine.js, and you can use the all within the same project, or even on the same page. Installing an integration is as simple as <code>yarn astro add tailwindcss<\/code>.<\/p><p>The templates feel familiar and make use of front matter within Astro components, and regular YAML front matter works within Markdown files - which are supported out of the box.<\/p><p>I've been thinking of redoing my personal website and evaluating options, but I think that Astro might be a new one to add to the list.<\/p>",
"cta": "",
"tags": ["astro"]
}, {
"title": "Refactoring to value objects",
"date": "1664755200",
"permalink": "/daily/2022/10/03/refactoring-value-objects",
"text": "<p>Here's a snippet of some Drupal code that I wrote last week. It's responsible for converting an array of nodes into a Collection of one of it's field values.<\/p><pre><code class=\"language-php\">return Collection::make($stationNodes) -&gt;map(fn (NodeInterface $station): string =&gt; $station-&gt;get('field_station_code')-&gt;getString()) -&gt;values();<\/code><\/pre><p>There are two issues with this code.<\/p><p>First, whilst I'm implicitly saying that it accepts a certain type of node, because of the <code>NodeInterface<\/code> typehint this could accept any type of node. If that node doesn't have the required field, the code will error - but I'd like to know sooner if an incorrect type of node is passed and make it explicit that only a certain type of node can be used.<\/p><p>Second, the code for getting the field values is quite verbose and is potentially repeated in other places within the codebase. I'd like to have a simple way to access these field values that I can reuse anywhere else. If the logic for getting these particular field values changes, then I'd only need to change it in one place.<\/p><h2 id=\"introducing-a-value-object\">Introducing a value object<\/h2><p>This is the value object that I created.<\/p><p>It accepts the original node but checks to ensure that the node is the correct type. If not, an Exception is thrown.<\/p><p>I've added a helper method to get the field value, encapsulating that logic in a reusable function whilst making the code easier to read and its intent clearer.<\/p><pre><code class=\"language-php\">namespace Drupal\\mymodule\\ValueObject;use Drupal\\node\\NodeInterface;final class Station implements StationInterface { private NodeInterface $node; private function __construct(NodeInterface $node) { if ($node-&gt;bundle() != 'station') { throw new \\InvalidArgumentException(); } $this-&gt;node = $node; } public function getStationCode(): string { return $this-&gt;node-&gt;get('field_station_code')-&gt;getString(); } public static function fromNode(NodeInterface $node): self { return new self($node); }}<\/code><\/pre><h2 id=\"refactoring-to-use-the-value-object\">Refactoring to use the value object<\/h2><p>This is what my code now looks like:<\/p><pre><code class=\"language-php\">return Collection::make($stationNodes) -&gt;map(fn (NodeInterface $node): StationInterface =&gt; Station::fromNode($node)) -&gt;map(fn (StationInterface $station): string =&gt; $station-&gt;getStationCode()) -&gt;values();<\/code><\/pre><h1>&lt;&lt;&lt;&lt;&lt;&lt;&lt; HEAD:website\/source\/_daily_emails\/2022-10-03.md<\/h1><blockquote> <blockquote> <blockquote> <blockquote> <blockquote> <blockquote> <blockquote> <p>b9cea6d (chore: replace Sculpin with Astro):website\/src\/pages\/daily-emails\/2022-10-03.md I've added an additional <code>map<\/code> to convert the nodes to the value object, but the second map can now use the new typehint - ensuring better type safety and also giving us auto-completion in IDEs and text editors. If an incorrect node type is passed in, then the Exception will be thrown and a much clearer error message will be shown.<\/p> <\/blockquote> <\/blockquote> <\/blockquote> <\/blockquote> <\/blockquote> <\/blockquote><\/blockquote><p>Finally, I can use the helper method to get the field value, encapsulating the logic within the value object and making it intention clearer and easier to read.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Minimum viable CI pipelines",
"date": "1664668800",
"permalink": "/daily/2022/10/02/minimum-viable-pipelines",
"text": "<p>When I start a new project, and sometimes when I join an existing project, there are no CI (continuous integration) pipelines, no automated tests, and sometimes no local environment configuration.<\/p><p>In that case, where should you start when adding a CI pipeline?<\/p><p>I like to start with the simplest solution to get a passing build and to prove the concept - even if it's a \"Hello, world\" message. I know that the pipeline is configured correctly and runs when expected, and gives the output that I expect.<\/p><p>I like to use Docker for my development environments, partly because it's very easy to reuse the same set up within a CI pipeline just by running <code>docker image build<\/code> or <code>docker compose build<\/code>.<\/p><p>Having a task that ensures the project builds correctly is a great next step.<\/p><p>Within a Dockerfile, I run commands to validate my lock files, download and install dependencies from public and private repositories, and often apply patch files to third-party code. If a lock file is no longer in sync with its composer.json or package.json file, or a patch no longer applies, this would cause Docker and the CI pipeline to fail and the error can be caught and fixed within the pipeline.<\/p><p>Next, I'd look to run the automated tests. If there aren't any tests, I'd create an example test that will pass to prove the concept, and expect to see the number of tests grow as new features are added and as bugs are fixed.<\/p><p>The big reason to have automated tests running in a pipeline is that all the tests are run every time, ensuring that the test suite is always passing and preventing regressions across the codebase. If any test fails, the pipeline fails. This is knows as continuous delivery - ensuring that code is always in a releasable state.<\/p><p>From there, I'd look to add additional tasks such as static analysis and code linting, as well as anything else to validate, build or deploy the code and grow confidence that a passing CI pipeline means that the code is releasable.<\/p><p>As more tasks are added to the pipeline, and the more of the code the tasks cover (e.g. test coverage) the more it can be replied upon.<\/p><p>If there is a failure that wasn't caught in the CI pipeline, then the pipeline itself should be iterated on and improved.<\/p><p>Having a CI pipeline allows you to identify issues sooner and fix them quicker, encourages best practices like automated testing and test-driven development, and enables continuous deployment where code is automatically deployed after a passing build.<\/p><p>If you have a project without a CI pipeline, I'd encourage you to add one, to start small, and continuously iterate on it over time - adding tasks that are useful and valuable, and that build confidence that you can safely release when you need to.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why do code katas?",
"date": "1664582400",
"permalink": "/daily/2022/10/01/code-katas",
"text": "<h2 id=\"what-are-code-katas%3F\">What are code katas?<\/h2><p>Code katas are programming exercises which, like katas in martial arts, use practice and repetition to improve your skills.<\/p><p>Common katas are Fizzbuzz, the Bowling score calculator, and the Gilded Rose.<\/p><p>Each gives you the criteria of what the kata should do before it can be considered complete along with any specific information, and some websites will also give you a suite of failing tests to make pass - though I prefer to write my own and follow a test-driven development approach.<\/p><p>Once you have completed the solution and the criteria is satisfied, the kata is complete.<\/p><h2 id=\"why-i-do-code-katas\">Why I do code katas<\/h2><p>As I said, doing code katas improves your skills by solving problems and identifying patterns that you may see when working in your project code.<\/p><p>Different katas focus on different patterns. For example, the Fibonacci Number kata focuses on recursion, whereas the Gilded Rose kata is all about refactoring complex legacy code.<\/p><p>Doing code katas keeps your skills sharp and gives you a different perspectives as you work through different katas. You can then use and apply these within your main projects.<\/p><p>If you want to learn a new programming language then working on a kata that you've already solved in a language that you're familiar with allows you to focus on the syntax and features of the new language. I've been working on some code katas in TypeScript as I've been working with that recently, and would like to do some in Go.<\/p><p>If you work as part of a team or a part of a meetup, code katas can be worked on as a group and can introduce new skills like automated testing and test-driven development as well as providing some opportunities for team-building and socialising. If you're trying to introduce pair or mob programming, then working on code katas could be a good first step.<\/p><p>If you're just getting started with programming, working on code katas will help you learn the fundamentals and problem solving, but I'd also encourage you to put the code on GitHub and blog about each kata that you complete. Doing so will help and encourage others and also look good when applying for roles.<\/p><p>P.S. There are lists of code katas at https:\/\/github.com\/gamontal\/awesome-katas and https:\/\/codingdojo.org\/kata, and online versions at https:\/\/www.codewars.com\/join and https:\/\/exercism.org\/tracks. There are many others - if you have a favourite, reply to this email and let me know.<\/p><p>I have <a href=\"https:\/\/github.com\/opdavies?tab=repositories&amp;q=katas\">some GitHub repositories for my code kata solutions<\/a> and will continue to build these as I do more.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Store Wars: different state management in Vue.js",
"date": "1664496000",
"permalink": "/archive/2022/09/30/store-wars-vuejs",
"text": "<p>I'm currently working on a Vue.js application that I started building in Vue 2 before starting to use the Composition API, and then moved it to Vue 3.<\/p><p>In the original version, I was using Vuex for state management within the application, and interacting with Vuex directly within my Vue components - calling <code>getters<\/code> and <code>dispatch<\/code> to retrieve and update data.<\/p><p>As part of moving to Vue 3, I wanted to evaluate any new options, like Pinia which is now the default state management library for Vue.<\/p><p>But because I was integrating with Vuex directly, switching to an alternative would mean changing code within my components.<\/p><h2 id=\"defining-a-store-interface\">Defining a Store interface<\/h2><p>This is a situation that often occurs in back-end development - where you may need to switch to a different type of database or a different payment provider in an eCommerce application.<\/p><p>In that situation, you need a generic interface that can be used by different implementations. Because they have consistent methods, one implementation can be replaced with another or multiple can be added at the same time. This is called the Strategy design pattern, and related to the open-closed principle in SOLID.<\/p><p>This is what I did by adding a <code>Store<\/code> interface:<\/p><pre><code class=\"javascript\">export default interface Store { actions: { addRow(): void; init(): void; removeRow(index: Number): void; }; state: { isLoading: boolean; selection: { items: []; }; };}<\/code><\/pre><p>Any store that I want to work with needs to have these defined actions and state values, so I can use them within my components knowing that they will always be available.<\/p><h2 id=\"creating-a-native-vue-store\">Creating a native Vue store<\/h2><p>This is one implementation of the <code>Store<\/code> interface, using just Vue's <code>reactive<\/code> function from the Composition API:<\/p><pre><code class=\"javascript\">let state = reactive({ isLoading: false, selection: { items: [], },});let actions = { addRow(): void { state.selection.items.push({ \/\/ ... }); }, init(): void { state.isLoading = true; \/\/ ... }, removeRow(index: number): void { state.selection.items.splice(index, 1); },};const vueStore: Store = { actions, state: readonly(state),};export default vueStore;<\/code><\/pre><p>If I needed to add a Pinia version or another library, I can create another implementation that complies with same interface.<\/p><p>Each implementation being responsible for any specifics for that library - extracting that logic from the component code making it more flexible and reusable.<\/p>",
"cta": "",
"tags": ["vue"]
}, {
"title": "Mob programming at PHP South Wales",
"date": "1664323200",
"permalink": "/archive/2022/09/28/mob-programming-php-south-wales",
"text": "<p>Tonight was our September meetup for the PHP South Wales user group, where I ran a hands-on session on mob programming.<\/p><p>I created <a href=\"https:\/\/speakerdeck.com\/opdavies\/an-introduction-to-mob-programming\">a small slide deck<\/a> before we started a mob session with the group.<\/p><p>We worked on the FizzBuzz kata in PHP, using Pest for our automated tests.<\/p><p>We followed the Driver and Navigator model, with one person responsible for the typing and interpreting the instructions from the Navigators, and switched roles every ten minutes.<\/p><p>You can <a href=\"https:\/\/github.com\/opdavies\/code-katas\/blob\/1da5dd5a79bc7ca083c0c4216fc3b4b0854f623d\/php\/tests\/FizzBuzzTest.php\">see the code that we wrote<\/a> on my code katas GitHub repository.<\/p><p>It was a fun experience and nice to code with some people who I hadn't coded with before.<\/p><p>We did some code kata sessions during our online meetups which also seemed to go well, so coding nights on katas or personal or open-source projects might be something that we do more of in the future.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Mentoring with Drupal Career Online",
"date": "1664236800",
"permalink": "/archive/2022/09/27/mentoring-with-drupal-career-online",
"text": "<p>Today, I met my new mentee from the Drupal Career Online program.<\/p><p><a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/21\/being-drupal-contribution-mentor\">As well as mentoring at events like DrupalCamps and DrupalCons<\/a>, I enjoy mentoring and working with new Developers going through bootcamps and training programmes like Drupal Career Online, some who are experienced Developers who are learning a new skill, and some who are learning how to code and are taking their first steps into programming.<\/p><p>I've talked about <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022-08-28\/how-started-programming\">how I got started programming<\/a>, but as self-taught Developer, it would have been great to have had a mentor to ask questions of, to help me get me started, and to make sure that I was going down the right track and learning the correct things.<\/p><p>Maybe this is more applicable these days with more people learning and working from home since COVID-19?<\/p><p>Similar to helping mentees at a contribution sprint work towards their first commits to Drupal, it's great to be able to introduce new Developers to a open-source project and community such as Drupal, help develop their skills, and hopefully enable them to get the new job and career that they want.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Experimenting with the Nix package manager",
"date": "1664150400",
"permalink": "/archive/2022/09/26/experimenting-with-the-nix-package-manager",
"text": "<p>After seeing it on some recent live streams and YouTube videos, I've recently been trying out the Nix package manager and looking into how I might use it for my local environment setup - potentially replacing some of my current Ansible configuration.<\/p><p>Separate from the NixOS operating system, Nix is a cross-platform package manager, so instead of using <code>apt<\/code> on Ubuntu and <code>brew<\/code> on macOS, you could run Nix on both and install from the 80,000 packages listed on https:\/\/search.nixos.org\/packages.<\/p><p>There is a community project called Home Manager which can be installed alongside Nix which, similar to Stow or what I'm doing with Ansible, can manage your dotfiles or even create them from your Home Manager configuration, and can manage plugins for other tools such as ZSH and tmux.<\/p><p>There's also a Nix feature called \"Flakes\" which allow you to separate configuration for different operating systems. I currently have a flake for Pop!&#95;OS which installs all of my packages and a minimal flake for my WSL2 environment as some of the packages are installed in Windows instead of Linux.<\/p><p>I can see Ansible still being used to set up my post-setup tasks such as cloning my initial projects, but the majority of my current Ansible setup where I'm installing and configuring packages I think could be moved to Nix.<\/p><p>I have a work-in-progress Nix-based version <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/tree\/7c3436c553f8b81f99031e6bcddf385d47b7e785\">in my dotfiles repository<\/a> where you can also see <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/blob\/7c3436c553f8b81f99031e6bcddf385d47b7e785\/home-manager\/modules\/git.nix\">how I've configured Git with Home Manager<\/a>.<\/p><p>I may install NixOS on an old laptop to test that out too.<\/p>",
"cta": "",
"tags": ["nix"]
}, {
"title": "Using a component library for front-end development",
"date": "1664064000",
"permalink": "/archive/2022/09/25/using-component-library-for-front-end-development",
"text": "<p>On a current project, I've decided to use a component library as the first place to do front-end development.<\/p><p>I'm using <a href=\"https:\/\/fractal.build\">Fractal<\/a> as I can use Twig for templates. As Drupal also uses Twig templates, I have more reusabilty between the components in Fractal and Drupal compared to converting them from a different templating language like Handlebars or Nunjucks.<\/p><p>Rather than developing directly within the custom Drupal theme, I've been creating new components and pages initially within Fractal.<\/p><p>I have been able to create new components quickly and easily with the views uing Twig templates and inject data to it using a context file - a YAML file for each component that contains data that is injected automatically into the view.<\/p><p>This meant that I've been able to develop new components from scratch without needing to set up content types or paragraphs within Drupal, validate and confirm my data model, and present the templates to the client for review in Fractal. If a change is needed, it's quick to do.<\/p><p>I've also moved my asset generation step into Fractal. No CSS or JavaScript is being compiled within the Drupal theme, it is created within Fractal and copied over with the Twig templates.<\/p><p>In most cases, I've been able to copy the Twig templates into Drupal and replace the static context data with dynamic data from Drupal without needing to make any further changes.<\/p><p>In a couple of situations, I've needed to change my implementation slightly when moving a template into Drupal, so in this workflow, I've made the changes in Fractal and re-exported them to keep things in sync between the two systems.<\/p><p>In situations where there is existing markup and\/or styles from the Drupal side, I've copied those into Fractal so that they match before adding the additional styling and any markup changes.<\/p><p>In general, I like the approach as it gives me more flexibility upfront to make changes before needing to configure Drupal. I can see how things could get out of sync between the two systems, but hopefully having the assets compiled in Fractal and needing to copy them into Drupal will keep things synced up.<\/p><p>I don't think that I'd use this approach for all projects, but for this one, where I'm working with multiple themes and will need to later add different variants of pages and components, it's worked well so far.<\/p>",
"cta": "",
"tags": []
}, {
"title": "ADRs and Technical Design Documents",
"date": "1663891200",
"permalink": "/archive/2022/09/23/adrs-technical-design-documents",
"text": "<h2 id=\"architectural-decision-records\">Architectural Decision Records<\/h2><p>Architectural Decision Records (ADRs) are documents to record software design choices. They could be saved in your code repository as plain-text or Markdown files, or stored in Confluence or a wiki - wherever your team stores its documentation.<\/p><p>They usually consist of the sections:<\/p><ul><li>Status - is it proposed, accepted, rejected, deprecated, superseded, etc.?<\/li><li>Context - what is the issue that is causing the decision or change?<\/li><li>Decision - what is the change that's being done or proposed?<\/li><li>Consequences - what becomes easier or more difficult to do?<\/li><\/ul><p>Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned.<\/p><p>These will remain in place to form a decision log, with specific ADRs being marked as superseded if a newer ADR replaces it.<\/p><h2 id=\"technical-design-documents\">Technical Design Documents<\/h2><p>A similar type of document are Technical Design Documents (TDDs), that I first saw on TheAltF4Stream. I like to think of these as lightweight ADRs.<\/p><p>The first heading is always \"What problem are we trying to solve?\", or sometimes just \"The problem\".<\/p><p>Similar to the Context heading in an ADR, this should include a short paragraph describing the issue.<\/p><p>Unlike ADRs, there are no other set headings but these are some suggested ones:<\/p><ul><li>What is the current process?<\/li><li>What are any requirements?<\/li><li>How do we solve this problem?<\/li><li>Alternative approaches<\/li><\/ul><p>I like after describing the problem, being able to move straight into describing what's appropriate and relevant for this task and ignore sections that aren't needed.<\/p><p>When I started writing ADRs, they all had the 'Accepted' status as I was either writing them for myself or in a pair or mob. As wasn't adding any value, I've removed it since switching to writing TDDs.<\/p><p>Whether you use ADRs, TDDs or another approach, it's very useful to have a log of all of your architectural design decisions, both looking back in the future to remember why something was done in a certain way, or before you start implementing a solution to review the problem, evaluate the requirements and all potential solutions and document the selected one any why it was selected.<\/p><p><a href=\"https:\/\/adr.github.io\">Find our more about ADRs<\/a> or <a href=\"https:\/\/altf4.wiki\/t\/how-do-i-write-a-tdd\/21\">find out more about TDDs<\/a>.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Releasing a Drupal module template",
"date": "1663804800",
"permalink": "/archive/2022/09/22/releasing-drupal-module-template",
"text": "<p>Today, I an the idea to create a reusable template for new Drupal modules, based on how I like to build modules and how I've shown others to do so in my Drupal testing workshop.<\/p><p>So I did, and released it for free <a href=\"https:\/\/github.com\/opdavies\/drupal-module-template\">on my GitHub account<\/a>.<\/p><p>Like my Tailwind CSS starter theme on Drupal.org, it's not intended to be added as a module directly, but something that can be cloned and used as a base for people's own modules.<\/p><p>It includes an example route and Controller that load a basic page, and has a test to ensure that the page exists and loads correctly.<\/p><p>The Controller is defined as a service and uses autowiring to automatically inject the its dependencies, the same as in my workshop example code.<\/p><p>It's the initial release so it's rough around the edges still. I'll use it tomorrow to create a new module and document the steps to add to the README as well as other pieces of documentation.<\/p><p>If you're creating a new Drupal module and try it out, start a discussion on the GitHub repository or <a href=\"https:\/\/twitter.com\/opdavies\">let me know on Twitter<\/a>. If you have questions, create a discussion or just reply to this email and I'll get back to you.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Being a Drupal contribution mentor",
"date": "1663718400",
"permalink": "/archive/2022/09/21/being-drupal-contribution-mentor",
"text": "<p>This week is DrupalCon Prague, and although I'm not at this event, I'd like to write about some my experiences at DrupalCon - in particular about being a contribution mentor.<\/p><h2 id=\"my-first-drupalcon\">My first DrupalCon<\/h2><p>The first DrupalCon that I attended was in 2013, also in Prague.<\/p><p>I was enjoying the session days when I stopped at the mentoring table to find out more about the contribution sprints that were happening on the Friday.<\/p><p>I didn't have any commits in Drupal core but had already worked on and released some of my own contributed modules, so I was familiar with the tools and the Drupal.org contribution workflow. In short, I was signed up to be a mentor during the sprints.<\/p><p>I remember being involved in the preparation too, sitting in a hotel lobby, identifying potential issues for new contributors to work on, alongside people who I'd previously interacted with in the issue queues on Drupal.org.<\/p><p>On the day, I helped new contributors get their local environments up and running, select issues to work on, and perform tasks like creating and re-rolling patch files and submitting them for review.<\/p><p>One of my highlights at the end of the day was the live commit, when a patch that a new contributor had worked on that day was committed to Drupal core live on stage!<\/p><p>Whenever I've attended DrupalCon events since, I've always volunteered to be a contribution mentor, as well as mentoring and organising sprints at other Drupal events.<\/p><h2 id=\"the-five-year-issue\">The Five Year Issue<\/h2><p>One of the most memorable times mentoring was whilst working with a group of contributors at DrupalCon in May 2015.<\/p><p>Someone was working on a Drupal core issue that was very similar to <a href=\"https:\/\/www.drupal.org\/project\/drupal\/issues\/753898\">one that I'd looked at<\/a> a few years before.<\/p><p>We focused on the original issue that I'd commented on, reviewed, tested, and re-rolled the patch, fixed a failing test, and marked it as \"reviewed and tested by the community\".<\/p><p>A few days after the conference, and just over five years after my original comment, the patch was committed - giving my contributors their first commits to Drupal 8 core, and also <a href=\"https:\/\/git.drupalcode.org\/project\/drupal\/-\/commits\/9.5.x?search=opdavies\">one of mine<\/a>.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Why I like trunk-based development",
"date": "1663632000",
"permalink": "/archive/2022/09/20/why-like-trunk-based-development",
"text": "<p>For the majority of my software development career, I've worked with version control in a very similar way.<\/p><p>There are one or two long-lived branches, usually a combination of <code>develop<\/code>, <code>master<\/code> or <code>main<\/code>, that contain the production version of the code. When starting work on a new feature or bug fix, a new branch is created where the changes are made in isolation, and is submitted for review once complete. This is typically referred to as \"Git Flow\" or \"GitHub Flow\".<\/p><p>Whilst those changes are awaiting review, a new task is started and the process is repeated.<\/p><h2 id=\"trunk-based-development\">Trunk-based development<\/h2><p>Something that I've been practicing and advocating for lately is trunk-based development, where there's only one branch that everyone works on, and commits and pushes to instead of creating separate per-task branches.<\/p><p>Even on a client project where I was the only Developer, I was used to creating per-task branches and I can recall when trying to demo two features to a client and the application broke when switching between branches.<\/p><p>The vast majority of the time, whether working individually or on a team, I've found that the per-task branches weren't needed and working on a single branch was easier and simpler.<\/p><p>There are still occassions when a temporary branch is needed, but in general, all changes are made to the single branch.<\/p><p>Trunk-based development ties in nicely with the continuous integration approach, where everyone commits and pushes their work at least once a day - ideally, multiple times a day. This eliminates long-running feature or bug fix branches that get out of sync with the main branch as well as conflicting with each other.<\/p><p>It seemed scary to begin with, having been used to per-task branches and asynchronous peer reviews via pull or merge requests, but trunk-based development has made things simpler and encourages other best practices such as pair and mob programming. having a good CI pipeline to identify regressions, using feature flags to separate code deployments from feature releases, and frequent code integration and deployment via continuous commits and pushes.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Useful Git configuration",
"date": "1663545600",
"permalink": "/archive/2022/09/19/useful-git-configuration",
"text": "<p>Here are some snippets from my Git configuration file.<\/p><p>These days, I use a much simpler workflow and configuration since doing more trunk-based development, but in general, I rebase instead of merging by default, and prefer to use fast-forward merges that doesn't create a merge commit.<\/p><p><code>branch.autosetuprebase = always<\/code> and <code>pull.rebase = true<\/code> configure Git to always rebase instead of pull. It does this for all branches, though I might override this for <code>main<\/code> branches.<\/p><p><code>pull.ff = only<\/code> and <code>merge.ff = only<\/code> prevents creating a merge commit and will prevent the merge if it would create one. If I needed to override this, I could by using the <code>--no-ff<\/code> option on the command line.<\/p><p>I use <code>checkout.defaultRemote = origin<\/code> to ensure that the <code>origin<\/code> remote is used if I have multiple remotes configured, and <code>push.default = upstream<\/code> to set the default remote to push to.<\/p><p><code>merge.autoStash<\/code> allows for running merges on a dirty worktree by automatically creating and re-applying a stash of the changes, and <code>fetch.prune<\/code> will automatically prune branches on fetch - keeping things tidy.<\/p><p>I also have and use a number of aliases.<\/p><p>Some like <code>pl = pull<\/code> and <code>ps = push<\/code> are shorter versions of existing commands, and some like <code>aa = add --all<\/code>, <code>fixup = commit --fixup<\/code> and some additional arguments to commands.<\/p><p>I also have some like <code>current-branch = rev-parse --abbrev-ref HEAD<\/code> and <code>worktrees = worktree list<\/code> which add simple additional commands, and some like <code>repush = !git pull --rebase &amp;&amp; git push<\/code> which use execute shell commands to execute more complex commands or combine multiple commands.<\/p><p>This is a snapshot of my Git configuration. The <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/blob\/7e935b12c09358adad480a566988b9cbfaf5999e\/roles\/git\/files\/.gitconfig\">full version is on GitHub<\/a>.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Thoughts on automated code formatting",
"date": "1663372800",
"permalink": "/archive/2022/09/17/thoughts-automated-code-formatting",
"text": "<p>For a long time, I've been focused on writing code that complies with defined coding standards, either to pass an automated check from a tool like PHP Code Sniffer (PHPCS) or eslint, or a code review from a team member.<\/p><p>Complying with the standards though is something that I've done manually.<\/p><p>As well as automated tools for linting the code, there are tools like PHP Code Beautifier and Fixer, and Prettier for formatting the code based on the same standards, which I've started to use more recently.<\/p><p>These tools can be run on the command line, VS Code has a \"Format on save\" option, and I can do the same in Neovim using an auto-command that runs after writing a file if an LSP is attached. I typically use a key mapping for this though so I can run it when I need, rather than it running automatically every time a file is saved.<\/p><p>One of my concerns with automated code formatting is what to do when working with existing code that doesn't already follow the standards. If I need to make a change to a file, with automated formatting, the rest of the file can change due to formatting being applied when I save my change.<\/p><p>I recently introduced a PHPCS step to a CI pipeline for an existing project. I knew that it was going to fail initially, but I was able to see the list of errors. I ran the code formatter on each of the files to fix the errors, committed and pushed the changes, and watched the pipeline run successfully.<\/p><p>This meant that I had a commit reformatting all of the affected files, but it was good to combine these together rather than having them separate, and not mixed with any other changes like a new feature or a bug fix.<\/p><p>Since doing this, it's been nice when working in this codebase to not have to worry about code style violations, and I can focus on writing the code that I need to, knowing that I can rely on the automated formatting to fix any issues before I commit them.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why I mostly write functional and integration tests",
"date": "1663286400",
"permalink": "/archive/2022/09/16/why-mostly-write-functional-and-integration-tests",
"text": "<p>In <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/14\/simpletest-drupal-test\">Wednesday's email<\/a>, I showed how quick it is to get started writing automated tests for a new Drupal module, starting with a functional test.<\/p><p>I prefer the outside-in style (or London approach) of test-driven development, where I start with a the highest-level test that I can for a task. If the task needs me to make a HTTP request, then I\u2019ll use a functional test. If not, I\u2019ll use a kernel (or integration) test.<\/p><p>I find that these higher-level types of tests are easier and quicker to set up compared to starting with lower-level unit tests, cover more functionality, and make it easier to refactor.<\/p><h2 id=\"an-example\">An example<\/h2><p>For example, this <code>Device<\/code> class which is a data transfer object around Drupal's <code>NodeInterface<\/code>. It ensures that the correct type of node is provided, and includes a named constructor and a helper method to retrieve a device's asset ID from a field:<\/p><pre><code class=\"language-php\">final class Device { private NodeInterface $node; public function __construct(NodeInterface $node) { if ($node-&gt;bundle() != 'device') { throw new \\InvalidArgumentException(); } $this-&gt;node = $node; } public function getAssetId(): string { return $this-&gt;node-&gt;get('field_asset_id')-&gt;getString(); } public static function fromNode(NodeInterface $node): self { return new self($node); }}<\/code><\/pre><h2 id=\"testing-getting-the-asset-id-using-a-unit-test\">Testing getting the asset ID using a unit test<\/h2><p>As the <code>Node::create()<\/code> method (what I'd normally use to create a node) interacts with the database, I need to create a mock node to wrap with my DTO.<\/p><p>I need to specify what value is returned from the <code>bundle()<\/code> method as well as getting the asset ID field value.<\/p><p>I need to mock the <code>get()<\/code> method and specify the field name that I'm getting the value for, which also returns it's own mock for <code>FieldItemListInterface<\/code> with a value set for the <code>getString()<\/code> method.<\/p><pre><code class=\"language-php\">\/** @test *\/public function should_return_an_asset_id(): void { \/\/ Arrange. $fieldItemList = $this-&gt;createMock(FieldItemListInterface::class); $fieldItemList -&gt;method('getString') -&gt;willReturn('ABC'); $deviceNode = $this-&gt;createMock(NodeInterface::class); $deviceNode -&gt;method('bundle') -&gt;willReturn('device'); $deviceNode -&gt;method('get') -&gt;with('field_asset_id') -&gt;willReturn($fieldItemList); \/\/ Act. $device = Device::fromNode($deviceNode); \/\/ Assert. self::assertSame('ABC', $device-&gt;getAssetId());}<\/code><\/pre><p>This is quite a long 'arrange' section for this test, and just be confusing for those new to automated testing.<\/p><p>If I was to refactor from using the <code>get()<\/code> and <code>getString()<\/code> methods to a different implementation, it's likely that the test would fail.<\/p><h2 id=\"refactoring-to-a-kernel-test\">Refactoring to a kernel test<\/h2><p>This is how I could write the same test using a kernel (integration) test:<\/p><pre><code class=\"language-php\">\/** @test *\/public function should_return_an_asset_id(): void { \/\/ Arrange. $node = Node::create([ 'field_asset_id' =&gt; 'ABC', 'type' =&gt; 'device' ]); \/\/ Assert. self::assertSame('ABC', Device::fromNode($node)-&gt;getAssetId());}<\/code><\/pre><p>I can create a real <code>Node<\/code> object, pass that to the <code>Device<\/code> DTO, and call the <code>getAssetId()<\/code> method.<\/p><p>As I can interact with the database, there's no need to create mocks or define return values.<\/p><p>The 'arrange' step is much smaller, and I think that this is easier to read and understand.<\/p><h3 id=\"trade-offs\">Trade-offs<\/h3><p>Even though the test is cleaner, because there are no mocks there's other setup to do, including having the required configuration available, enabling modules, and installing schemas and configuration as part of the test - and having test-specific modules to store the needed configuration files.<\/p><p>Because of this, functional and kernel tests will take more time to run than unit tests, but an outside-in approach could be worth considering, depending on your project and team.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "The simplest Drupal test",
"date": "1663113600",
"permalink": "/archive/2022/09/14/simpletest-drupal-test",
"text": "<p>Most of my work uses the Drupal framework, and I've given talks and workshops on automated testing and building custom Drupal modules with test-driven development. Today, I wanted to see how quickly I could get a working test suite on a new Drupal project.<\/p><p>I cloned a fresh version of my <a href=\"https:\/\/github.com\/opdavies\/docker-examples\">Docker Examples repository<\/a> and started the Drupal example.<\/p><p>I ran <code>mkdir -p web\/modules\/custom\/example\/tests\/src\/Functional<\/code> to create the directory structure that I needed, and then <code>touch web\/modules\/custom\/example\/tests\/src\/Functional\/ExampleTest.php<\/code> to create a new test file and populated it with some initial code:<\/p><pre><code class=\"language-php\">&lt;?phpnamespace Drupal\\Tests\\example\\Functional;use Drupal\\Tests\\BrowserTestBase;use Symfony\\Component\\HttpFoundation\\Response;class ExampleTest extends BrowserTestBase { protected $defaultTheme = 'stark';}<\/code><\/pre><p>For the simplest test, I decided to test some existing Drupal core functionality - that an anonymous user can view the front page:<\/p><pre><code class=\"language-php\">\/** @test *\/public function the_front_page_loads_for_anonymous_users() { $this-&gt;drupalGet('&lt;front&gt;'); $this-&gt;assertSession()-&gt;statusCodeEquals(Response::HTTP_OK);}<\/code><\/pre><p>To execute the test, I ran <code>SIMPLETEST_DB=sqlite:\/\/localhost\/\/dev\/shm\/test.sqlite SIMPLETEST_BASE_URL=http:\/\/web phpunit -c web\/core web\/modules\/custom<\/code>. The environment variables could be added to a <code>phpunit.xml.dist<\/code> file but I decided to add them to the command and use Drupal core's PHPUnit configuration file.<\/p><p>As this is existing functionalty, the test passes. I can change either the path or the response code to ensure it also fails when expected.<\/p><p>With the first test working, it's easy to add more for other functionality, such as whether different users should be able to access administration pages:<\/p><pre><code class=\"language-php\">\/** @test *\/public function the_admin_page_is_not_accessible_to_anonymous_users() { $this-&gt;drupalGet('admin'); $this-&gt;assertSession()-&gt;statusCodeEquals(Response::HTTP_FORBIDDEN);}\/** @test *\/public function the_admin_page_is_accessible_by_admin_users() { $adminUser = $this-&gt;createUser([ 'access administration pages', ]); $this-&gt;drupalLogin($adminUser); $this-&gt;drupalGet('admin'); $this-&gt;assertSession()-&gt;statusCodeEquals(Response::HTTP_OK);}<\/code><\/pre><p>Hopefully, this shows how quickly you can get tests running for a Drupal module. If you'd like to see more, the slides and video recording of my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">Test-Driven Drupal talk<\/a> are online.<\/p>",
"cta": "",
"tags": []
}, {
"title": "A month of daily emails",
"date": "1662940800",
"permalink": "/archive/2022/09/12/month-daily-emails",
"text": "<p>It\u2019s already been a month since I started my email list and writing daily emails.<\/p><p>Since then, I\u2019ve written emails on various development and workflow-based topics, including Drupal, Git, Docker, Neovim, Ansible and Tailwind CSS.<\/p><p>The first email was written on Thursday the 12th of August and after initially wondering whether I should start on the upcoming Monday, or how often to post, I decided to jump in with both feet and wrote the first daily post that day. The first few weren't actually emailed as I waited to see if I could sustain writing a daily post (I was just posting them to my website), but after a few days, I set up the email list and started sending the posts.<\/p><p>I can confirm what <a href=\"https:\/\/jonathanstark.com\">Jonathan Stark<\/a> and <a href=\"https:\/\/jhall.io\">Jonathan Hall<\/a> have said - that it's easier to write daily and that you start to see topic ideas everywhere. I started with a list of between 20 and 25 ideas and still have most of them as I've pivoted on a day's topic based on an article or tweet that I saw, some code that I'd written, or some approach that I took.<\/p><p>If you're considering starting a daily email list, I'd recommend it.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Custom styles in Tailwind CSS: `@apply`, `theme` or custom plugins",
"date": "1662854400",
"permalink": "/archive/2022/09/11/custom-styles-tailwind-css-apply-theme-custom-plugins",
"text": "<p>There are three ways to add custom styles to a Tailwind CSS project. As there have been <a href=\"https:\/\/twitter.com\/adamwathan\/status\/1559250403547652097\">some recent tweets<\/a> around one of them - the <code>@apply<\/code> directive - I'd like to look at and give examples for each.<\/p><h2 id=\"what-is-%60%40apply%60%3F\">What is <code>@apply<\/code>?<\/h2><p><code>@apply<\/code> is a PostCSS directive, provided by Tailwind, to allow re-using it's classes - either when extracting components or overriding third-party styles.<\/p><p>The CSS file is the same as if you were writing traditional CSS, but rather than adding declarations to a ruleset, you use the <code>@apply<\/code> directive and specify the Tailwind CSS class names that you want to apply.<\/p><p>For example:<\/p><pre><code class=\"css\">fieldset { @apply bg-primary-dark;}<\/code><\/pre><p>This is a simple example but it's easy to see how this could be used in ways that weren't intended and how edge-cases can be found.<\/p><p>Adam said in a another tweet:<\/p><blockquote> <p>I estimate that we spend at least $10,000\/month trying to debug extremely edge-case issues people run into by using <code>@apply<\/code> in weird ways.<\/p><\/blockquote><h2 id=\"using-the-%60theme%60-function\">Using the <code>theme<\/code> function<\/h2><p>As well as <code>@apply<\/code>, Tailwind also provides a <code>theme<\/code> function that you can use in your CSS file. This removes the abstraction of using the class names and adds the ability to retrieve values from the <code>theme<\/code> section of your tailwind.config.js file.<\/p><pre><code class=\"css\">fieldset { backgroundColor: theme('colors.primary.dark');}<\/code><\/pre><p>This seems to be the preferred approach over using <code>@apply<\/code>.<\/p><h2 id=\"creating-a-custom-plugin\">Creating a custom plugin<\/h2><p>The <code>theme<\/code> function is also available if you write a custom Tailwind CSS plugin:<\/p><pre><code class=\"javascript\">const plugin = require('tailwindcss\/plugin')plugin(({ addBase, theme }) =&gt; { addBase({ fieldset: { backgroundColor: theme('colors.primary.dark'), } })})<\/code><\/pre><p>This is an approach that I've used for <a href=\"https:\/\/github.com\/opdavies?tab=repositories&amp;q=%23tailwindcss-plugin\">generic, open-source plugins<\/a> but for project-specific styling, I've mostly used <code>@apply<\/code> or the <code>theme<\/code> function.<\/p><p>That said, I like the modular architecture of having different custom plugins - especially if they're separated into their own files - and being able to easily toggle plugins by simply adding to or removing from the <code>plugins<\/code> array.<\/p><p>I usually don't write many custom styles in a Tailwind project but I think that I'll focus on using the <code>theme<\/code> function going forward, either in a stylesheet or a custom plugin.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Automating Ansible deployments in CI",
"date": "1662768000",
"permalink": "/archive/2022/09/10/automating-ansible-deployments-ci",
"text": "<p>Once you have a deployment that's run using Ansible, rather than running it manually, it's easy to automate it as part of a continuous integration pipeline and have your changes pushed automatically by tools like GitHub Actions and GitLab CI.<\/p><p>You'll need to configure SSH by adding a known hosts file and a private key so the tool can connect to your server, but after that, it's just running the same Ansible commands.<\/p><p>If you're using Ansistrano or other roles, you can install dependencies by using <code>ansible-galaxy<\/code>, and <code>ansible-vault<\/code> to decrypt and use any encrypted variables - securely storing the Vault password and any other secrets as environment variables within your pipeline.<\/p><p>Here's an example using GitHub Actions:<\/p><pre><code>- name: Download Ansible roles run: ansible-galaxy install -r requirements.yml- name: Export the Ansible Vault password run: echo $ANSIBLE_VAULT_PASS &gt; .vault-pass.txt env: ANSIBLE_VAULT_PASS: $- name: Deploy the code run: &gt; ansible-playbook deploy.yml -i inventories\/$INVENTORY_FILE.ini -e \"project_git_branch=$GITHUB_SHA\" --vault-password-file=.vault-pass.txt- name: Remove the Ansible Vault password file run: rm .vault-pass.txt<\/code><\/pre><p>Before these steps, I've added the SSH key and determined which inventory file to use by the updated branch. The Vault password is exported and then removed once it has been used.<\/p><p>Automated tests and other code quality checks can be run in prior job, ensuring that the deployment only happens if those checks pass, but assuming that all is good, the playbook will be run and the changes will be deployed automatically.<\/p>",
"cta": "",
"tags": ["ansible"]
}, {
"title": "Refactoring a Tailwind CSS component",
"date": "1662681600",
"permalink": "/archive/2022/09/09/refactoring-tailwind-component",
"text": "<p>After last night's Pro Tailwind theming workshop, I decided to revisit and refactor some similar code that I'd worked on before.<\/p><p>It was a demo for a presentation on utility-first CSS and Tailwind whilst I was at Inviqa.<\/p><p>I'd taken one of the components from the website that we'd lauched and rebuilt it - in particular to show how Tailwind could be used for responsive and themeable components.<\/p><p><a href=\"https:\/\/play.tailwindcss.com\/Yfmw8O5UNN\">The original version<\/a> was written in Tailwind 1 and used custom CSS with <code>@apply<\/code> rules to include text or background colours to elements based on the theme being used on that page or component.<\/p><p>As well as moving it into a Next.js application, <a href=\"https:\/\/github.com\/opdavies\/inviqa-tailwindcss-example\">the new version<\/a> uses techniques covered in Simon's workshop - using CSS custom properties (aka variables) to override the colours, and writing custom plugins to generate the required styles. It doesn't include everything from the workshop, but enough for this refactor.<\/p><p>I also moved the <code>flex-basis<\/code> classes into their own standalone plugin and might release that as it's own open-source plugin.<\/p><p>I'm working on a client project at the moment which will need switchable themes so I'm looking forward to putting these techniques to use again in the near future.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Keeping secrets with Ansible Vault",
"date": "1662595200",
"permalink": "/archive/2022/09/08/keeping-secrets-with-ansible-vault",
"text": "<p>In the last few posts, I've talked about using Ansible for configuring servers and local environments, during both of which, you're likely to have some sensitive or secret values. These could be database credentials within your application and on your server, and your SSH private keys within your local environment.<\/p><p>Rather than committing these to a code repository in plain text, Ansible includes the <code>ansible-vault<\/code> command to encrypt values.<\/p><p>To see this working, run <code>ansible-vault encrypt_string my-secret-password<\/code>, enter a password, and then you should see something like this:<\/p><pre><code>!vault | $ANSIBLE_VAULT;1.1;AES256 33353031663366313132333831343930643830346531666564363562666136383838343235646661 6336326637333230396133393936646636346230623932650a333035303265383437633032326566 38616262653933353033376161633961323666366132633033633933653763373539613434333039 6132623630643261300a346438636332613963623231623161626133393464643634663735303664 66306433633363643561316362663464646139626533323363663337363361633333<\/code><\/pre><p>This is the encrypted version of that password, and this could be committed and pushed to a code repository.<\/p><p>You can use it within a playbook, and you'll be prompted to re-enter the password so that Ansible can decrypt and use it.<\/p><p>Rather than a single string, you could have a file of variables that you want to encrypt. You can do this by running <code>ansible-vault encrypt vault.yml<\/code> and include it as before. Again, you'll be prompted by Ansible so that it can decrypt and use the values.<\/p><p>For an example of how I'm using Ansible Vault, see <a href=\"https:\/\/github.com\/opdavies\/dransible\/tree\/986ba5097d62ff4cd0e637d40181bab2c4417f2e\/tools\/ansible\">the Dransible repository<\/a> on GitHub or my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\"> Deploying PHP applications with Ansible, Ansible Vault and Ansistrano<\/a> talk.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": ["ansible"]
}, {
"title": "My Tailwind CSS origin story",
"date": "1662508800",
"permalink": "/archive/2022/09/07/my-tailwind-css-origin-story",
"text": "<p>Tomorrow night, I'm attending one of Simon Vrachliotis (simonswiss)'s Pro Tailwind workshops, so I thought that it would be a good time, as Simon has done himself recently on the Navbar podcast, to describe how I started using Tailwind CSS.<\/p><p>I remember watching a lot of Adam Wathan's live streams on YouTube before Tailwind CSS, and I remember when he started a new project - a SaaS product called KiteTail.<\/p><p>It was a Laravel and Vue.js project, and although I'm not a Laravel Developer primarily, I got a lot of other information from Adam's streams about automated testing, test-driven development, and Vue.js as I was learning Vue at the time.<\/p><p>One of the episodes was about styling a card component using some styles that Adam was copying between projects - which would eventually be the starting point for Tailwind CSS.<\/p><p>In fact, I think I watched some of the episode and stopped as I was happy with the Sass and BEM or SMACSS approach that I was using at the time, and didn't initially see the value of the utility CSS approach that I was seeing for the first time (everyone has a similar reaction initially).<\/p><p>After a while, I did re-visit it but because Tailwind CSS wasn't released as it's own project yet, I (like Simon) started to experiment with Tachyons - another utility CSS library.<\/p><p>I rebuilt a particularly tricky component that I'd just finished working on and had caused me some issues, and managed to re-do it in only a few minutes.<\/p><p>I started to use Tachyons on some personal and client projects as a layer on other frameworks like Bootstrap and Bulma, and later moved on to Tailwind CSS once it has been released.<\/p><p>I was working in this way on a project when I released that I could use Tailwind for all of the styling instead of just adding small sprinklings of utilities here and there. I refactored everything and removed the other framework that I'd been using - leaving just Tailwind CSS.<\/p><p>With the exception of some legacy projects, now I use Tailwind CSS exclusively and have used it for a number of projects. I've given lunch and learn sessions to teams that I've worked on, <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-tailwind-css\">presented a Tailwind CSS talk<\/a> at a number of PHP, Drupal, WordPress, and JavaScript events, and maintain <a href=\"https:\/\/www.drupal.org\/project\/tailwindcss\">a starter-kit theme<\/a> for using Tailwind in custom Drupal themes.<\/p><p>I've also rebuilt a <a href=\"https:\/\/www.oliverdavies.uk\/blog\/uis-ive-rebuilt-tailwind-css\">number of existing sites<\/a> as examples and written some <a href=\"https:\/\/www.oliverdavies.uk\/blog\/tags\/tailwind-css\">Tailwind CSS related blog posts<\/a>.<\/p><p>I'm looking forward to attending Simon's workshop tomorrow and quickly putting that knowledge to use in the next phase of a project that I'm currently working on.<\/p>",
"cta": "",
"tags": ["tailwind-css"]
}, {
"title": "Deploying applications with Ansible",
"date": "1662422400",
"permalink": "/archive/2022/09/06/deploying-applications-with-ansible",
"text": "<p>The last few days' emails have been about using Ansible to create and configure infrastructure, but it can also be used to deploy application code.<\/p><p>The simplest way being that an artifact is built locally - e.g. a directory of static HTML pages from a static site generator - and uploaded onto the server, and for this you could use Ansible's <code>synchronize<\/code> module.<\/p><p>It's a wrapper around the <code>rsync<\/code> command and makes it as simple as specifying <code>src<\/code> and <code>dest<\/code> values for the local and remote paths.<\/p><p>For more complicated deployments, I like to use a tool called Ansistrano - an Ansible port of a deployment tool called Capistrano.<\/p><p>It creates a new directory for each release and updates a <code>current<\/code> symlink to identify and serve the current release, and can share files and directories between releases.<\/p><p>As well as being able to configure settings such as the deployment strategy, how many old releases to keep, and even the directory and symlink names, there are a number of hooks that you can listen for an add your own steps as playbooks so you can install dependencies, generate assets, run migrations, or rebuild a cache as part of each deployment.<\/p><p>If you're running your applications in Docker, you could use Ansible to pull the latest images and restart your applications.<\/p><p>For more information and examples, I've given a talk on Ansible at various PHP events, which covers some Ansible basics before moving on to <a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\">deploying applications with Ansistrano<\/a>.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Using Ansible for local environment configuration",
"date": "1662336000",
"permalink": "/archive/2022/09/05/using-ansible-for-local-configuration",
"text": "<p>As well as <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/09\/04\/using-ansible-for-server-configuration\">configuring servers<\/a>, you can use Ansible to configure your own local machine and development environment.<\/p><p>The change that you need to make is within the <code>hosts.ini<\/code> file:<\/p><pre><code>127.0.0.1 ansible_connection=local<\/code><\/pre><p>Instead of the server's IP address or hostname, use the localhost IP address and set <code>ansible_connection<\/code> to <code>local<\/code> to tell Ansible to run locally instead of using an SSH connection.<\/p><p>Another way to do this is to set <code>hosts: 127.0.0.1<\/code> and <code>connection: true<\/code> in your playbook.<\/p><p>Once this is done, you can run tasks, roles, and collections to automate tasks such as installing software, adding your SSH keys, configuring your project directories, and anything else that you need to do.<\/p><p>For an example of this, you can see <a href=\"https:\/\/github.com\/opdavies\/dotfiles\">my dotfiles repository on GitHub<\/a>.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Using Ansible for server configuration",
"date": "1662249600",
"permalink": "/archive/2022/09/04/using-ansible-for-server-configuration",
"text": "<p><a href=\"https:\/\/www.oliverdavies.uk\/archives\/2022\/09\/03\/creating-infrastructure-with-ansible\">In yesterday's email<\/a>, I described how to set up a blank server with Ansible.<\/p><p>Now that we've done that, it needs to be configured.<\/p><p>Once the server\u2019s IP address or hostname has been added to a <code>hosts.ini<\/code> file, you can run ad-hoc commands against it - such as <code>ansible all -i hosts.ini -m ping<\/code> to run Ansible's <code>ping<\/code> module on all of the hosts in your inventory and check that you can connect to them.<\/p><p>Another useful one that you can use is the <code>shell<\/code> module, that runs ad-hoc run commands on each host. If you need to check the uptime of each of your servers, run <code>ansible all -i hosts.ini -m shell -a uptime<\/code>. You can replace the last argument with any other shell command that you need to run, like <code>df<\/code> or <code>free<\/code>.<\/p><p>Running commands in this way is great for getting started, for routine maintenance, or an emergency free disk space check, but for more complex tasks like configuration management, using playbooks is the better option. They are YAML files that contain lists of tasks that Ansible will run through and execute in order.<\/p><p>If you have a group of related tasks, such as for installing a piece of software, then you can combine them into roles. In fact, Ansible Galaxy has thousands of pre-built collections and roles that you can download, include in your playbooks, configure, and run.<\/p><p>Very quickly, you can get a full stack installed and configured - ready to serve your application.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Creating infrastructure with Ansible",
"date": "1662163200",
"permalink": "/dailys/2022/09/03/creating-infrastructure-with-ansible",
"text": "<p>Let's start at the beginning.<\/p><p>If we want to automate our infrastructure then we first need to create it. This could be done manually or we can automate it.<\/p><p>Popular tools for this include Terraform and Pulumi, but Ansible also includes modules to interface with hosting providers such as Amazon Web Services, Microsoft Azure, DigitalOcean, and Linode.<\/p><p>By using one of these tools, you can programatically provision a new, blank server that is ready for you to be configered.<\/p><p>For example, to <a href=\"https:\/\/docs.ansible.com\/ansible\/latest\/collections\/community\/digitalocean\/digital_ocean_module.htm\">create a DigitalOcean droplet<\/a>:<\/p><pre><code class=\"language-yaml\">---- community.digitalocean.digital_ocean_droplet: image: ubuntu-20-04-x64 name: mydroplet oauth_token: \"...\" region: sfo3 size: s-1vcpu-1gb ssh_keys: [ .... ] state: present wait_timeout: 500 register: my_droplet<\/code><\/pre><p>Running this playbook will create a new Droplet with the specified name, size, and operating system, and within the specified region.<\/p><p>If you needed to create a separate database server or another server for a new environment, then the file can be updated and re-run.<\/p><p><a href=\"https:\/\/docs.ansible.com\/ansible\/latest\/collections\/amazon\/aws\/ec2_instance_module.html#ansible-collections-amazon-aws-ec2-instance-module\">Creating an Amazon EC2 instance<\/a> looks very similar:<\/p><pre><code class=\"language-yaml\">---- amazon.aws.ec2_instance: image_id: ami-123456 instance_type: c5.large key_name: \"prod-ssh-key\" name: \"public-compute-instance\" network: assign_public_ip: true security_group: default vpc_subnet_id: subnet-5ca1ab1e<\/code><\/pre><p>This doesn't apply just to servers - you can also use Ansible to create security groups and S3 buckets, manage SSH keys, firewalls, and load balancers.<\/p><p>Once we have our infrastructure in place, we can start using Ansible to set and manage its configuration, which we'll do in tomorrow's email.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": ["ansible"]
}, {
"title": "Automating all the things with Ansible",
"date": "1662076800",
"permalink": "/archive/2022/09/02/automating-all-the-things-with-ansible",
"text": "<p>Ansible is a tool for automating IT tasks. It's one of my preferred tools to use, and one that I've written about and <a href=\"https:\/\/www.oliverdavies.uk\/talks\/deploying-php-ansible-ansistrano\">presented talks on<\/a> previously.<\/p><p>It's typically thought of as a tool for managing configuration on servers. For example. you have a new VPS that you want to use as a web server, so it needs Nginx, MySQL, PHP, etc to be installed - or whatever your application uses. You define the desired state and run Ansible, which will perform whatever tasks are needed to get to that state.<\/p><p>Ansible though does include modules for interacting with services like Amazon AWS and DigitalOcean to create the servers and resources, and not just configure them.<\/p><p>It also doesn't just work on servers. I use Ansible to configure my local development environment, to ensure that dependencies and tools are installed, and requirements like my SSH keys and configuration are present and correct.<\/p><p>Lastly, I use Ansible to deploy application code onto servers and automatically run any required steps, ensuring that deployments are simple, robust and repeatable.<\/p><p>In the next few emails, I'll explain how I've been able to utilise Ansible for each of these situations.<\/p><hr \/><p>Want to learn more about how I use Ansible? <a href=\"https:\/\/www.oliverdavies.uk\/ansible-course\">Register for my upcoming free email course<\/a>.<\/p>",
"cta": "",
"tags": ["ansible"]
}, {
"title": "Conventional commits and CHANGELOGs",
"date": "1661990400",
"permalink": "/archive/2022/09/01/conventional-commits-changelogs",
"text": "<p>One of the things that I've done since joining my current team is to implement a standard approach for our commit messages.<\/p><p>We're using the <a href=\"https:\/\/www.conventionalcommits.org\">Conventional Commits specification<\/a>, which gives some additional rules to follow when writing commit messages.<\/p><p>For example:<\/p><pre><code>build(deps): update Drupal to 9.4.5Updated Drupal's `drupal\/core-*` packages to 9.4.5.See https:\/\/www.drupal.org\/project\/drupal\/releases\/9.4.5.Refs: #123<\/code><\/pre><p>We can see that this is a <code>build<\/code> task that relates to our project dependencies, in this example, we're updating Drupal core. We can also see this in the subject line.<\/p><p>In the commit body, I add as much information as possible to do with the change and include any relevant links, just in case I need to refer to them again, and the list the names of anyone else who worked with me. I also typically include any ticket numbers or links in the commit footer.<\/p><p>So far, I've mostly used the <code>build<\/code>, <code>chore<\/code>, <code>ci<\/code>, <code>docs<\/code> and <code>refactor<\/code> commit types, which are types that are recommended and used by <a href=\"https:\/\/github.com\/angular\/angular\/blob\/22b96b9\/CONTRIBUTING.md#-commit-message-guidelines\">the Angular convention<\/a>.<\/p><p>Following this standard means that it's very easy to look at the Git log and see what type of changes are going to be included within a release and, if you're using scopes, which part of the application are affected.<\/p><p>Conventional commits also works nicely with something else that we've introduced, which is a CHANGELOG file.<\/p><p>There are tools that can generate and update CHANGELOGs automatically from conventional commits, but so far, we've been following the <a href=\"https:\/\/keepachangelog.com\">Keep a Changelog<\/a> format.<\/p><p>It's easy to match the commits to the <code>Added<\/code>, <code>Changed<\/code> or <code>Fixed<\/code> types, and although it needs to be updated manually, it's easy to add to the <code>Unreleased<\/code> section of the file and re-organise everything within the appropriate headings as needed as part of a release.<\/p><p>What I like about this format is that it's more human-friendly and gives a higher level overview of the changes rather than a reformatted Git log.<\/p><p>As we do trunk-based development and continuous integration on our projects, there can be numerous commits related to the same change, so I'd rather only see a single line in the CHANGELOG for each change. This also makes it easier to share the CHANGELOG file with others, and we can still view and grep the Git log to see the individual commits if we need to.<\/p>",
"cta": "",
"tags": []
}, {
"title": "To monorepo, or not to monorepo?",
"date": "1661904000",
"permalink": "/archive/2022/08/31/monorepo-or-not",
"text": "<p>I listened to a podcast episode recently which talked about monorepos - i.e. code repositories that contain multiple project codebases rather than a single repository for each codebase - and this got me thinking about whether I should be using these more.<\/p><p>It's something that I've been trialling recently in my <a href=\"https:\/\/github.com\/opdavies\/docker-examples\">Docker examples<\/a> and <a href=\"https:\/\/github.com\/OliverDaviesLtd\/docker-images\">Docker images<\/a> repositories, where one repository contains and builds multiple Docker images.<\/p><p>I'm not suggesting that I put all of my client projects into one repository, but at least combining the different parts of the same project into the same repository.<\/p><p>For example, I'm working for one client on their current Drupal 7 websites whilst developing the new Drupal 9 versions, which are currently in two separate repositories. I'm also developing an embeddable Vue.js application as part of the Drupal 9 website, and using Fractal as a component library. These are also in their own repositories.<\/p><p>Using a monorepo approach, all of these projects would be in the same repository.<\/p><p>I can see advantages to being able to see cross-project changes in the same place - such as an API change in Drupal that needs a update to be made in Vue.js, or vice-versa - rather than needing to look at separate repositories. This could also make versioning easier as everything will be stored and tagged inside the same repository.<\/p><p>Each project has it's own CI pipeline, so it would require some changes where I set a specific pipeline to run only when a directory is changed.<\/p><p>I see how deployments may be tricker if I need to push an update within a directory to another Git repository, which makes me wonder if I'll need to look into using subtree splits to create separate deployment repositories - similar to how the Symfony project has one main repository and then each component split into its own repository.<\/p><p>I'll keep trialling it in my open-source projects and maybe test it with some client projects, but if you have experience with monorepos that you'd like to share, then please reply to this email - I'd love to hear about it.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Why I don&#039;t only use Drupal",
"date": "1661817600",
"permalink": "/archive/2022/08/30/why-dont-only-use-drupal",
"text": "<p>Yesterday, <a href=\"https:\/\/www.oliverdavies.uk\/archive\/2022\/08\/29\/why-like-drupal\">I shared some of the reasons<\/a> why I like Drupal and why I use it for the majority of my projects. But, as I said, I don't use it exclusively and for some projects I used various different tools.<\/p><p>Essentially, I always try to recommend and use the best tool for the job.<\/p><p>I previously interviewed for a job and was asked to complete a coding test. The role was mostly Drupal-focussed, but as the test asked for a command-line application, I completed it using Symfony and Symfony Console, and was able to discuss why I'd made that decision. In my opinion, it was the best choice based on the requirements.<\/p><p>This is the same approach that I use when making recommendations for a new project.<\/p><p>I've delivered projects using other tools like the Symfony framework or a static site generator, as long as it fitted the requirements.<\/p><p>If there's a SaaS solution that can be used instead, or an off-the-shelf tool that can be integrated instead of writing a custom solution, then that should be evaluated.<\/p><p>There may be other constraints like budgets or deadlines to consider - maybe something can be delivered faster or cheaper using a particular technology, even if it's not the final solution.<\/p><p>There are situations though where a tool may be the best choice even though it's not the ideal fit based purely on the technical requirements. Maybe the client is already familiar with publishing content in Drupal, or an in-house development team is used to working with a certain tool or language. In that case, those things should be considered too.<\/p><p>Also, for me, having a chance to evaluate other technologies and explore what's happening outside of the Drupal ecosystem is a good opportunity. A lot of what I've learned about automated testing, for example, is from the wider PHP and JavaScript communities, as well as tools like <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Tailwind CSS<\/a> and <a href=\"https:\/\/www.oliverdavies.uk\/\/talks\/using-illuminate-collections-outside-laravel\">Illuminate Collections<\/a> that I've been able to bring back into my other Drupal projects.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "Why I like Drupal",
"date": "1661731200",
"permalink": "/archive/2022/08/29/why-like-drupal",
"text": "<p>As I said in yesterday's email, I developed my first website project on Drupal. It allowed me to take a static HTML and CSS website and convert it into something that was much easier and quicker for me to update, and allowed me to create more users with permissions to do those tasks too.<\/p><p>I worked on various Drupal projects, and my first full-time job was on an in-house team where we maintained and enhanced a Drupal 6 website.<\/p><p>I've since used Drupal for projects of all shapes and sizes with different levels of complexity. Everything from a simple brochure website to large and complex, multilingual, API-driven projects.<\/p><p>I've been able to build eCommerce websites with Drupal using Ubercart and Drupal Commerce. I've built traditional stores where customers purchase physical products, a photography competition website with custom judging functionality, a site for purchasing commercial and residential property and land searches, and a fully-fledged events booking and management platform.<\/p><p>Whatever the size and complexity of the project, Drupal is flexible enough to fit it.<\/p><p>I've loved some of the ecosystem improvements within the last few years. Moving to object-orientated code by default, integrating code from other projects like Symfony, shipping new features every six months as part of the new release cycle, and embracing tools like Composer, PHPStan and Rector.<\/p><p>I also love being part of the Drupal community. Collaborating on tasks, speaking on Slack, and attending events like DrupalCon where I've been lucky enough to attend, speak and mentor.<\/p><p>Although Drupal is my specialty and the tool that I've used the most, I don't use it exclusively. I'll talk more about this in tomorrow's email.<\/p>",
"cta": "",
"tags": ["drupal"]
}, {
"title": "How I started programming",
"date": "1661644800",
"permalink": "/archive/2022-08-28/how-started-programming",
"text": "<p>In 2007, I was working in the IT sector in a Desktop Support role but hadn't done any coding professionally.<\/p><p>In my spare time, I was a black belt in Tae Kwon-Do and enjoyed training at a few different schools. Because of my IT experience, I was asked if I could create a website for one of the schools - somewhere that we could post information and class times for new starters, as well as news articles and competition results.<\/p><p>This would be my introduction to programming.<\/p><p>I started learning what I needed to know, starting with HTML and CSS - experimenting with a template that I found online and was able to tweak to match the school's colours.<\/p><p>I was able to complete the first version of the website with static HTML pages and CSS but had to manually create a new HTML page for every new news article and edit existing pages manually.<\/p><p>I wanted to make it more dynamic, and started to learn about PHP and MySQL from video courses and online forums.<\/p><p>After posting a question about some PHP code that I'd written, someone suggested that I look at content management systems - namely Drupal, which was used for that forum (I have <a href=\"https:\/\/twitter.com\/opdavies\/status\/1185456825103241216\">a screenshot of the reply<\/a>). This was a new concept to me as until that point, I'd written everything so far myself whilst learning it.<\/p><p>I remember evaluating Drupal alongside some others - rebuilding the same website a few different times, but stuck with Drupal and relaunched it on Drupal 6 and a custom theme that I'd created from the original templates.<\/p><p>I signed up for a Drupal.org account, started to do some freelance work for a local web design agency, and built a new website for a local cattery.<\/p><p>I started blogging, attending meetups, and when an opportunity to switch careers to software development came along, I applied for and got the job.<\/p><p>That job was also using Drupal and, in another email, I'll write more about why I still like and use Drupal years later.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Giving back",
"date": "1661558400",
"permalink": "/archive/2022/08/27/giving-back",
"text": "<p>Today, I've been at an event run by a local animal rescue charity. It's one that we attend often as my children like to enter the dog show, but this year, I've also sponsored one of the categories.<\/p><p>As well as organising the PHP South Wales user group, I'm also now a sponsor - donating books and elePHPant plushies for raffle prizes and paying the group's Meetup.com subscription costs.<\/p><p>Giving back and supporting open-source maintainers and content creators is a big priority of mine. If I use some open-source software or find that someone's Twitch or YouTube channel is useful, if that person or organisation is on GitHub or Patron, then I'll sponsor them, or I'll subscribe to their channel.<\/p><p>If I find a useful blog post or video, I'll add a comment or link to it on Twitter, thanking them and letting them know that it helped me.<\/p><p>Especially if it's something that I've used within my projects, it makes sense to support it and it's maintainers, so that they keep working on and improving the software, continue streaming, and keep writing blog posts and recording videos for me to learn from.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Always be learning",
"date": "1661472000",
"permalink": "/archive/2022/08/26/always-be-learning",
"text": "<p>I've been a Developer for 15 years and one thing that I've always focussed on is to always keep learning.<\/p><p>From starting as a self-taught Developer, initially learning HTML and CSS, to later learning PHP and Drupal as well as other languages, frameworks and tools.<\/p><p>For the last couple of days, I've been experimenting with Next.js - a React-based web framework. I hadn't used React before and have typically reached for Vue.js or sometimes Alpine.js based on what I needed to do. However, I'm always looking for opportunities to learn and implement new things, and see how I can use them in any of my projects.<\/p><p>This afternoon, I started a new Next.js and TypeScript project, and refactored a small codebase that used a static site generator to create a small number of landing pages from Markdown files.<\/p><p>It took me a short time to set up a Docker environment for it based on some of my Vue.js projects, ported across the application to recreate the pages, and finally, updated the CI pipeline that generated the static pages and uploaded them to an S3 bucket.<\/p><p>The end result is the same - the same HTML pages are generated and uploaded - but, for me, trying and experimenting with new things keeps my work interesting and my knowledge fresh, which benefits me as well as my colleagues and clients.<\/p><p>As I said in a previous email, one of the great things about software development is that there's always something new to learn.<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why I work in Neovim",
"date": "1661385600",
"permalink": "/archive/2022/08/25/why-i-work-in-neovim",
"text": "<p>Over a year ago, I posted that I was <a href=\"https:\/\/www.oliverdavies.uk\/blog\/going-full-vim\">switching to using Neovim full-time<\/a> for my development work.<\/p><p>I'd used Vim one file at a time on remote servers, and added Vim plugins in other IDEs and editors, so I was already familiar with a lot of the key bindings and motions before I decided to use it full-time.<\/p><p>Still, it was tough to begin with, but once I'd learned how to configure Neovim, I also learned that being able to customise and extend it as much as you need to is one of its main advantages compared to other IDEs and code editors.<\/p><p>TJ DeVries - a Neovim core team member - has recently coined the term \"PDE\" (a personalised development environment) which, for me, describes Neovim perfectly.<\/p><p>Currently, I have a fuzzy-finder to quickly open files (as well as many other things), an LSP client to add code intelesense, auto-completion, refactoring tools, custom snippets, and very recently, a database client and a HTTP client.<\/p><p>Just as important to me, I've found a growing community of other Neovim users who stream on Twitch, post YouTube videos, write blog posts, or publish their dotfiles for others to see and reference.<\/p><p>I've learned Lua. Not just for my own Neovim configuration, but I recently wrote and open-sourced my own simple plugin.<\/p><p>Like Git, I enjoy and prefer using tools that I can configure and adapt to my workflow.<\/p><p>Given Neovim's flexibility and configurability, its expanding feature set both in core and community plugins, and the growing community, I think that Neovim is going to be something that I continue to use and adapt for a long time.<\/p>",
"cta": "",
"tags": ["vim","neovim"]
}, {
"title": "How I&#039;ve configured Git",
"date": "1661299200",
"permalink": "/daily/2022/08/24/2022-08-24",
"text": "<p>After yesterday's post on why I prefer using Git on the command line rather than using a GUI tool, today I thought that I'd post about how I've configured Git.<\/p><p>First, I rarely ever run the <code>git<\/code> command - I usually run a <code>g<\/code> function that I've created within my zsh configuration.<\/p><p>Rather than being an simple alias, it's a shell function that will run <code>git status -sb<\/code> to show the current status of the repository if there are no additional arguments. If there are, such as when running <code>g add<\/code>, then this is executed as a normal Git command. (This is something that I first saw from Thoughtbot, if I remember correctly).<\/p><h2 id=\"using-.gitconfig\">Using .gitconfig<\/h2><p>The main part of my configuration is within Git's <code>~\/.gitconfig<\/code> file, where I can configure Git to work how I want.<\/p><p>For example, I like to avoid merge conflicts, so I always want to use fast-forward merges whilst pulling and also to rebase by default. I can do this by adding <code>ff = only<\/code> and <code>rebase = true<\/code> to the <code>[pull]<\/code> section of my <code>~\/.gitconfig<\/code> file.<\/p><p>I can do this manually, or running <code>git config --global pull.rebase true<\/code> will set the option but also update the file automatically.<\/p><p>Some of the tweaks that I've made are to only allow fast-forward merges by adding <code>merge.ff = only<\/code>, automatically squash commits when rebasing by setting <code>rebase.autosquash = true<\/code>, and automatically pruning branches by adding <code>fetch.prune = true<\/code>.<\/p><h3 id=\"simple-aliases\">Simple aliases<\/h3><p>Another way that I configure Git is using aliases, which are also within the <code>~\/.gitconfig<\/code> file.<\/p><p>For example, if I ran <code>git config --global alias.b \"branch\"<\/code>, then running <code>git b<\/code> would just run <code>git branch<\/code> which shortens the command and saves some time and keystrokes.<\/p><p>I have similar one- or two letter \"short\" aliases for pushing and pulling code, and some that also set some additional arguments such as <code>aa<\/code> for <code>add --all<\/code> and <code>worktrees<\/code> for <code>worktree list<\/code>.<\/p><h3 id=\"more-complicated-aliases\">More complicated aliases<\/h3><p>Aliases can be more complex if needed by prefixing it with a <code>!<\/code>, meaning that it executes it as a shell command.<\/p><p>This means that I can have <code>repush = !git pull --rebase &amp;&amp; git push<\/code> to chain two separate Git commands and combine them into one, and <code>ureset = !git reset --hard $(git upstream)<\/code> which executes the full command, including another alias as part of it.<\/p><p>I also have <code>issues = !gh issue list --web<\/code> and <code>pulls = !gh pr list --web<\/code> to open the current repository's GitHub issues or pull requests respectively, which can be done as it's not limited to just running <code>git<\/code> commands.<\/p><h3 id=\"custom-functions\">Custom functions<\/h3><p>Finally, if an alias is getting too long or complex, then it can extracted to it's own file.<\/p><p>Any executable file within your <code>$PATH<\/code> that starts with <code>git-<\/code> will automatically become a Git command.<\/p><p>One example that I have is <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/blob\/2b20cd1e59ae3b1fa81074077e855cbdfa02f146\/bin\/bin\/git-cm\">git-cm<\/a> which, similar to the <code>g<\/code> function`, is a bash script that checks for any arguments passed to it and runs a slightly different command. It achieves the same thing as if it were an alias, but it does make it easier to write and maintain as it's in a separate file.<\/p><p>These are just some examples. If you want to see my entire configuration, then check out <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/tree\/2b20cd1e59ae3b1fa81074077e855cbdfa02f146\/roles\/git\/files\">my dotfiles repository on GitHub<\/a>.<\/p><p>How have you configured Git for your workflow? Reply to this email and let me know.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Git: GUI or command-line?",
"date": "1661212800",
"permalink": "/archive/2022/08/23/git-gui-command-line",
"text": "<p>I\u2019ve been using Git for a long time. My first full-time Developer role in 2010 was working on an in-house team and that project used Git as it\u2019s version control system.<\/p><p>I remember typing commands into an Ubuntu terminal and trying to wrap my head around the process of adding and staging files, (sometimes) pulling, and then pushing to a remote. I think the remote was a simple bare repository on a server, so there was no UI like there is in GitHub and similar tools today.<\/p><p>In fact, GitHub only started two years earlier in 2008, and GitLab wasn\u2019t around until 2014.<\/p><p>Looking back, my introduction to Git as a Junior Developer wasn't easy and I remember starting to get frustrated until it eventually \"clicked\" and made sense.<\/p><p>I don't remember if there were GUIs at that time (I remember using gitk but I can't think when), but having a tool like GitHub where I could see the code, branches and commits, would probably have been helpful with my initial learning.<\/p><p>Whilst working locally, I've tried some of the desktop GUI tools like Sourcetree, gitkraken and Tower, but I always come back to using Git on the command line.<\/p><p>While a Git GUI tool may make it easier to learn Git initially as a Junior Developer, I'd recommend trying to learn the command line too.<\/p><p>In my opinion, understanding what\u2019s happening \"under the hood\" when is important working with a GUI - just in case you find yourself unexpectedly having to use the command line. I\u2019ve seen an error in a Git GUI that suggests running commands in the terminal to debug or fix the issue. If you aren't familiar with the terminal commands or what they do, then I'd expect this to be intimidating and confusing.<\/p><p>If you're working as part of a team or contributing to an open-source project then the consistency that the command line provides will make it easier when working with colleagues or getting help from project maintainers. You're also learning Git itself rather than a tool that may add it's own terminology or change how Git itself works, also causing confusion.<\/p><p>There's a lot of Git functionality and concepts that I wouldn't have explored if I wasn't using the command line and relying on a GUI, such as adding and removing code in chunks using patch mode, using bisect to find when a bug was introduced, worktrees for local code organisation, and understanding merging vs rebasing, interactive and non-interactive rebases, and merge commits and fast-forward merges.<\/p><p>Of course, if you prefer to use a GUI and it works for you, then that's fine. Personally, I like to dig deep when learning tools, to know them inside-out and understand how to use them well, and I think that the time that I've spent learning Git and optimising my workflow paid for itself a long time ago.<\/p><p>How do you like to use Git? Do you prefer to use the command line or a GUI tool? Reply to this email and let me know.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Being a T-shaped Developer",
"date": "1661126400",
"permalink": "/daily/2022/08/22/2022-08-22",
"text": "<p>A blog post appeared on my feed this morning, titled <a href=\"https:\/\/www.nomensa.com\/blog\/how-to-be-t-shaped\">How to be T-Shaped<\/a>.<\/p><p>\"T-shaped Developers\" is a term that I've also used before. Being T-shaped means that you have a deep knowledge in one particular area and a breadth of knowledge in other areas.<\/p><p>I would say that I'm T-shaped.<\/p><p>My main area of knowledge is PHP and Drupal software development - they're the programming language and content management system that I've used throughout most of my career so far, since I started in 2007.<\/p><p>As I worked on my own personal and client projects, I needed to learn more complementary skills.<\/p><p>I needed to learn how to style websites and build themes so I started to learn front-end development with CSS and frameworks like Bootstrap, Bulma and Tailwind CSS, and JavaScript frameworks like Angular, Vue.js and Alpine, as well as TypeScript.<\/p><p>I also needed to host these projects somewhere, which introduced me to Linux servers, virtual hosts, (S)FTP and SSL, web servers like Apache, Nginx and Caddy, MySQL and MariaDB databases, and as projects got more complicated, I started using tools like Vagrant and Puppet, Ansible, and Docker for configuring environments to work in.<\/p><p>I don't use Drupal for every project. I've used static site generators and frameworks like Symfony based on the project's requirements, and have projects that use several different technologies at the same time.<\/p><p>The main benefits are that I can either deliver entire projects or projects with more complicated architectures, or work across different teams - mentoring a team of Front-End Developers in Drupal theming, or working with System Administrators to start hosting PHP applications. Having these additional skills is definitely valuable to employers and clients.<\/p><p>I've said that one of the best and worst things about software development is that there's always something new to learn!<\/p>",
"cta": "",
"tags": []
}, {
"title": "Why I use Docker and Docker Compose for my projects",
"date": "1661040000",
"permalink": "/daily/2022/08/21/2022-08-21",
"text": "<p>For the last few years, I've used Docker and Docker Compose exclusively on all of my projects. When I start a new project or onboard a new client, usually one of the first things that I need to do is get an application running in Docker so that I can work on it.<\/p><!-- Since I started programming, I've used a number of different local environments. Starting with WAMP and XAMPP on Windows, MAMP on macOS, Laravel Valet, the Symfony local server, and various open-source Docker-based solutions. --><p>I've inherited projects with no environment configuration or documentation at all and I need to start from scratch to get it running. Ideally, each project would have it's local environment configuration in the same Git repository as the application code.<\/p><p>For my own projects, these days I prefer to use Docker and Docker Compose - creating my own Dockerfiles for each project so that the correct dependencies are present and the required build steps are executed, as well as acting as documentation.<\/p><p>It's lean as the environment is built specifically for each project, and easy to configure using Docker and Docker Compose directly using native patterns such as override files, environment variables and interpolation, and multi-stage builds.<\/p><p>The configuration can be as simple or complicated as it needs to be for each project rather than using \"a one size fits all\" approach. If I'm working with Drupal, Fractal, Vue.js, a PHP library, a Go command line tool, or something else entirely, I can use the most appropriate starting point.<\/p><p>As well as local developments, it's easy to use Docker and Docker Compose in CI environments with tools like GitHub Actions and Bitbucket Pipelines. They will either be present by default or will be easy to install, and it's simple to run a <code>docker-compose build<\/code> or <code>docker-compose run<\/code> command within a pipeline to check that the project builds correctly and to execute tasks such as automated tests or static analysis.<\/p><p>As well as using it for projects, Docker has been useful for me in other situations where I need to run small tools such as rst2pdf for generating presentation slides, and ADR Tools for working with architectural decision records.<\/p><p>For some situations like an open-source contribution day, using an off-the-shelf solution would probably be a better option, and some teams will have their own preferences, but I prefer to use Docker and Docker Compose when I can.<\/p><p>Personally, I like to invest time into learning tools that provide reusable knowledge, such as Docker and Docker Compose. I'd prefer to spend time learning something, even if it may take longer compared to other tools, if it's going to give me a return on that investment in the medium- to long-term.<\/p><p>For some examples of how I work with Docker and Docker Compose, you can <a href=\"https:\/\/github.com\/opdavies?tab=repositories&amp;q=docker\">see my public GitHub repositories<\/a> and how things are put together there.<\/p>",
"cta": "",
"tags": ["docker"]
}, {
"title": "A return to offline meetups and conferences",
"date": "1660953600",
"permalink": "/archive/2022/08/20/return-to-offline-meetups-conferences",
"text": "<p>Yesterday, I dusted off our Meetup page and posted our next <a href=\"https:\/\/www.meetup.com\/php-south-wales\">PHP South Wales meetup<\/a> event.<\/p><p>We've had online meetups and code practice sessions throughout the pandemic and during lockdowns, but this will be our first offline\/in person\/IRL meetup since February 2020.<\/p><p>As well as organising our online meetups during COVID, I attended a lot of other online events, <a href=\"https:\/\/www.oliverdavies.uk\/blog\/speaking-remotely-during-covid-19\">usually giving various talks or workshops<\/a>, and whilst they were good for a while, I eventually started to get burned out by them.<\/p><p>I've been an organiser of various meetups and conferences for a long time, and attending events has been a very large part of my career so far - providing opportunities to learn, to network and socialise with other attendees, and pass knowledge on through talks, workshops and mentoring.<\/p><p>It's been great to see some offline events returning, from local user groups to conferences such as DevOpsDays, DrupalCon and SymfonyLive.<\/p><p>I've given one talk this year - a lot less than this time last year - but it was in front of an audience instead of a screen, and whilst it seemed strange, I'm sure that it's something that will feel normal again in time.<\/p><p>I'm thinking of attending a conference next month, I've submitted some talk suggestions to some other conferences which I'm waiting to hear from, and am considering travelling to some of the other UK user groups as they restart - some of which I joined or spoke at online but it would be great to meet them in person.<\/p><p>For next week, I'll be glad to have PHP South Wales events running again and to see our community back together in person, and then do it again and start getting ready for next month's event.<\/p>",
"cta": "",
"tags": ["community"]
}, {
"title": "Pair programming or code reviews?",
"date": "1660867200",
"permalink": "/daily/2022/08/19/pair-programming-or-code-reviews",
"text": "<p>It's been almost a year and a half since I last pushed a feature branch, created a pull request, and waited for it to be reviewed and (hopefully) merged and deployed.<\/p><p>On the majority of teams and projects that I've worked on, this was how things were done.<\/p><p>Tasks would be worked on in separate branches which would need to be reviewed by one or more other Developers before being merged.<\/p><p>I'm an advocate for continuous integration and trunk-based development (both I plan on writing about in more depth) in which there is no formal code review step, but instead, I encourage people to pair program as much as possible.<\/p><p>Pair or mob (group) programming, for me, is like a real-time code review where you can discuss and make changes instantly, rather than waiting until the work is complete and someone reviewing it after the fact. If a bug is spotted as you're typing it or something could be named better, you can update it there and then.<\/p><p>But there are other benefits too.<\/p><p>Instead of one person writing some code, and others reviewing it after the fact, multiple people have written it together and the knowledge is shared amongst those people.<\/p><p>As you've worked together, you don't need to ask or wait for someone to set time aside to review your changes, so it's quicker for them to be merged and deployed. It's already been reviewed, so as long as any automated checks pass, the code can be merged.<\/p><p>I've worked in pairs where I've taught someone how to write automated tests and do test-driven development, which I suspect wouldn't have been quite the same if they'd just read the finished code afterwards.<\/p><p>Of course, some Developers and teams will prefer the typical code review process - it's worked well for me and projects that I've worked on in the past - but personally, I like the speed, agility, mentoring and learning, and social benefits that I can get more easily from pair programming.<\/p>",
"cta": "",
"tags": []
}, {
"title": "&#039;Talking Drupal&#039; and Tailwind CSS",
"date": "1660780800",
"permalink": "/daily/2022/08/18/talking-drupal-tailwind-css",
"text": "<p>In March, I was a guest again on the Talking Drupal podcast. This time I was talking about utility CSS and, in particular, the Tailwind CSS framework.<\/p><p>I've become a big fan of this approach to styling websites and was an early adopter of Tailwind, and have released <a href=\"https:\/\/www.drupal.org\/project\/tailwindcss\">a starter-kit theme<\/a> for building custom Drupal themes with Tailwind CSS based on what I was using for my own client projects.<\/p><h2 id=\"rebuilding-talking-drupal-with-tailwind\">Rebuilding Talking Drupal with Tailwind<\/h2><p>Usually when I give a Tailwind CSS talk at a conference or user group, I rebuild something familiar - maybe a page of their website - as an example and to explain some of the concepts and anything that was particularly interesting during the build. (I have <a href=\"https:\/\/www.oliverdavies.uk\/blog\/uis-ive-rebuilt-tailwind-css\">a blog post<\/a> that lists the ones that I've done before).<\/p><p>After this podcast episode, I built a <a href=\"https:\/\/talking-drupal-tailwindcss.oliverdavies.uk\">Tailwind version of the Talking Drupal homepage<\/a>.<\/p><p>But, given that Drupal uses Twig and that we'd talked about best practices around using a templating engine to use loops and extract components to organise code and reduce duplication, I definitely wanted to build this example using Twig templates.<\/p><p>Drupal seemed like too much for a single page example, and Symfony or Sculpin could distract from the main focus of the demo, so I decided to start from scratch with an empty PHP file and add Twig and any other dependencies myself.<\/p><p><a href=\"https:\/\/github.com\/opdavies\/talking-drupal-tailwindcss\">The code repository<\/a> is publicly viewable on my GitHub profile so people can look at the code and see some of the things that I talked about during the episode in practice and not just the resulting HTML a browser.<\/p><p>You can <a href=\"https:\/\/talkingdrupal.com\/338\">listen to the episode<\/a>, and if you want any more information, the slides and video from my <a href=\"https:\/\/www.oliverdavies.uk\/talks\/taking-flight-with-tailwind-css\">Taking Flight with Tailwind CSS talk<\/a> are on my website.<\/p>",
"cta": "",
"tags": ["css","tailwind-css","twig"]
}, {
"title": "One more &quot;run&quot; command, for Git worktrees",
"date": "1660694400",
"permalink": "/daily/2022/08/17/one-more-run-command-git-worktrees",
"text": "<p>Here's another <code>run<\/code> file example, this time relating to Git worktrees...<\/p><p>One project that I work on is a multilingual Drupal application that needs to work in both English and Welsh. As I'm cloning a fresh version today, I'm doing it as a bare repository so I can use worktrees.<\/p><p>To work on it locally, just like in production, I need to use a different URL for each language so that Drupal can identify it and load the correct content and configuration.<\/p><p>For fixed environments like production or staging, the URLs are set in configuration files, but for ad-hoc environments such as local worktrees, I thought that the best approach was to override them as needed per worktree using Drush (a Drupal CLI tool).<\/p><p>I could do this manually each time or I could automate it in a <code>run<\/code> command. :)<\/p><p>Here's the function that I came up with:<\/p><pre><code class=\"bash\">function drupal:set-urls-for-worktree { # Set the site URLs based on the current Git worktree name. local worktree_name=\"$(basename $PWD)\" local cy_url=\"cy-projectname-${worktree_name}.docker.localhost\" local en_url=\"projectname-${worktree_name}.docker.localhost\" # Update the URLs. drush config:set language.negotiation url.domains.cy -y $cy_url drush config:set language.negotiation url.domains.en -y $en_url # Display the domains configuration to ensure that they were set correctly. drush config:get language.negotiation url.domains}<\/code><\/pre><p>It builds the worktree URL for each language based on the directory name, executes the configuration change, and finally displays the updated configuration so I can confirm that it's been set correctly.<\/p><p>This is a good example of why I like using <code>run<\/code> files and how I use them to automate and simplify parts of my workflow.<\/p>",
"cta": "",
"tags": ["drupal","git"]
}, {
"title": "What are Git hooks and why are they useful?",
"date": "1660608000",
"permalink": "/daily/2022/08/16/what-are-git-hooks-why-are-they-useful",
"text": "<p>In yesterday's email, I mentioned Git hooks but didn't go into any detail. So, what are they?<\/p><p>Git hooks are Bash scripts that you add to your repository that are executed when certain events happen, such as before a commit is made or before a push to a remote.<\/p><p>By default, the script files need to be within the <code>.git\/hooks<\/code> directory, have executable permissions, and be named to exactly match the name of the hook - e.g. <code>pre-push<\/code> - with no file extension.<\/p><p>If it returns an error exit code then the process is stopped and the action doesn't complete.<\/p><p>This is useful if, for example, you or your team use a specified format for commit messages and you want to prevent the commit if the message doesn't match the requirements.<\/p><p>But, the main benefit that I get from Git hooks if from the <code>pre-push<\/code> hook.<\/p><p>I use it to run a subset of the checks that are run within project's CI pipeline to limit failures in the CI tool and fix simple errors before I push the code.<\/p><p>Typically, these are the quicker tasks such as ensuring the Docker image builds, running linting and static analysis, validating lock files, and some of the automated tests if they don't take too long to run.<\/p><p>If a build is going to fail because of something simply like a linting error, then I'd rather find that out and fix it locally rather than waiting for a CI tool to fail.<\/p><p>Also, if you're utilising trunk-based development and continuous integration where team members are pushing changes regularly, then you want to keep the pipeline in a passing, deployable state as much as possible and prevent disruption.<\/p><p>But what have Git hooks got to do with the \"run\" file?<\/p><p>Firstly, I like to keep the scripts as minimal as possible and move the majority of the code into functions within the <code>run<\/code> file. This means that the scripts are only responsible for running functions like <code>.\/run test:commit<\/code> and returning the appropriate exit code, but also means that it's easy to iterate and test them locally without making fake commits or trying to push them to your actual remote repository (and hoping that they don't get pushed).<\/p><p>Secondly, I like to simplify the setup of Git hooks with their own functions.<\/p><p>For security reasons, the <code>.git\/hooks<\/code> directory cannot be committed and pushed to your remote so they need to be enabled per user within their own clone of the repository.<\/p><p>A common workaround is to put the scripts in a directory like <code>.githooks<\/code> and either symlink them to where Git expects them to be, or to use the <code>core.hooksPath<\/code> configuration option and change where Git is going to look.<\/p><p>I like to lower the barrier for any team members by creating <code>git-hooks:on<\/code> and <code>git-hooks:off<\/code> functions which either set or unset the <code>core.hooksPath<\/code>. If someone wants to enable the Git hooks then they only need to run one of those commands rather than having to remember the name of the configuration option or manually creating or removing symlinks.<\/p><p>There are other Git hooks that can be used but just using <code>pre-commit<\/code> and <code>pre-push<\/code> has saved me and teams that I've worked on both Developer time and build minutes, provides quicker feedback and fewer disruptions in our build pipelines, and I like how simple it can be by creating custom functions in a <code>run<\/code> file.<\/p><p>Lastly, I've created <a href=\"https:\/\/github.com\/opdavies\/git-hooks-scratch\">https:\/\/github.com\/opdavies\/git-hooks-scratch<\/a> as an example with a minimal <code>run<\/code> file and some example hooks.<\/p>",
"cta": "",
"tags": ["git"]
}, {
"title": "Using a &quot;run&quot; file to simplify project tasks",
"date": "1660521600",
"permalink": "/daily/2022/08/15/using-run-file-simplify-project-tasks",
"text": "<p>Every project has its own set of commands that need to be run regularly.<\/p><p>From starting a local server or the project's containers with Docker or Docker Compose, running tests or clearing a cache, or generating the CSS and JavaScript assets, these commands can get quite complicated and time-consuming and error-prone to type over and over again.<\/p><p>One common way to simplify these commands is using a <code>Makefile<\/code>.<\/p><p>A Makefile contains a number of named targets that you can reference, and each has one or more commands that it executes.<\/p><p>For example:<\/p><pre><code class=\"language-language-yaml\"># Start the project.start: docker-compose up -d# Stop the project.stop: docker-compose down# Run a Drush command.drush: docker-compose exec php-fpm drush $(ARGS)<\/code><\/pre><p>With this Makefile, I can run <code>make start<\/code> to start the project, and <code>make stop<\/code> to stop it.<\/p><p>Makefiles work well, but I don't use the full functionality that they offer, such as dependencies for targets, and passing arguments to a command - like arguments for a Drush, Symfony Console, or Artisan command, doesn't work as I originally expected.<\/p><p>In the example, to pass arguments to the <code>drush<\/code> command, I'd have to type <code>ARGS=\"cache:rebuild\" make drush<\/code> for them to get added and the command to work as expected.<\/p><p>An agency that I worked for created and open-sourced their own Makefile-like tool, written in PHP and built on Symfony Console. I gave a talk on it called <a href=\"https:\/\/www.oliverdavies.uk\/talks\/working-with-workspace\">Working with Workspace<\/a> and used it on some of my own personal and client projects.<\/p><h2 id=\"what-i%27m-using-now\">What I'm using now<\/h2><p>The solution that I'm using now is a <code>run<\/code> file, which is something that I learned from Nick Janetakis' blog and YouTube channel.<\/p><p>It's a simple Bash file where you define your commands (or tasks) as functions, and then execute them by typing <code>.\/run test<\/code> or <code>.\/run composer require something<\/code>.<\/p><p>Here's the Makefile example, but as a <code>run<\/code> script:<\/p><pre><code class=\"bash\">#!\/usr\/bin\/env bashfunction help() { # Display some default help text. # See examples on GitHub of how to list the available tasks.}function start { # Start the project. docker-compose up -d}function stop { # Stop the project. docker-compose down}function drush { # Run a Drush command with any additional arguments. # e.g. \".\/run drush cache:rebuild\" docker-compose exec php-fpm drush \"${@}\"}# Execute the command, or run \"help\".eval \"${@:-help}\"<\/code><\/pre><p>As it's Bash, I can just use <code>$1<\/code>, <code>$2<\/code> etc to get specific arguments, or <code>$@<\/code> to get them all, so <code>.\/run drush cache:rebuild<\/code> works as expected and any additional arguments are included.<\/p><p>You can group tasks by having functions like <code>test:unit<\/code> and <code>test:commit<\/code>, and tasks can run other tasks. I use this for running groups of commands within a CI pipeline, and to extract helper functions for tasks like running <code>docker-compose exec<\/code> within the PHP container that other commands like <code>drush<\/code>, <code>console<\/code> or <code>composer<\/code> could re-use.<\/p><p>As well as running ad-hoc commands during development, I also use the run file to create functions that run Git pre-commit or pre-push hooks, deploy code with Ansible, or build, push or pull the project's latest Docker images.<\/p><p>I also use one within my Talks repository to generate PDF files using rst2pdf, present them using phdpc, and generate thumbnail images.<\/p><p>For examples of <code>run<\/code> files that I use in my open-source code, <a href=\"https:\/\/github.com\/search?l=Shell&amp;q=user%3Aopdavies+filename%3Arun&amp;type=Code\">you can look in my public GitHub repositories<\/a>, and for more information, here is <a href=\"https:\/\/nickjanetakis.com\/blog\/replacing-make-with-a-shell-script-for-running-your-projects-tasks\">Nick's blog post where I first found the idea<\/a>.<\/p>",
"cta": "",
"tags": ["php"]
}, {
"title": "Why I write automated tests",
"date": "1660435200",
"permalink": "/daily/2022/08/14/why-i-write-tests",
"text": "<p>In February 2012, I saw a tweet from Tim Millwood asking if anyone wanted to maintain or co-maintain a Drupal module called <a href=\"https:\/\/www.drupal.org\/project\/override_node_options\">Override Node Options<\/a>.<\/p><p>It had more than 9,200 active installations at that time, with versions for Drupal 5, 6 and 7.<\/p><p>I said yes and became the module\u2019s maintainer.<\/p><p>The module now has versions for Drupal 7, 8 and 9, with (at the latest count, according to Drupal.org) 32,292 active installations - which makes it currently the 197th most installed module.<\/p><p>There have been two main things that come to mind with this module, related to automated testing.<\/p><p>Before I become the maintainer, a feature request had been created, along with a large patch file, to add some new permissions to the module. There were some large merge conflicts that stopped me from just committing the changes but I was able to fix them manually and, because the tests still passed, ensure that the original functionality still worked. There weren\u2019t tests for the new permissions but I committed the patch and added the tests later.<\/p><p>Without the tests to ensure that the original functionality still worked, I probably wouldn\u2019t have committed the patch and would have just closed the issue.<\/p><p>More recently, a friend and ex-colleague and I decided to refactor some of the module's code.<\/p><p>We wanted to split the <code>override_node_options.module<\/code> file so that each override was in its own file and its own class. This would make them easier to edit and maintain, and if anyone wanted to add a new one, they\u2019d just need to create a new file for it and add it to the list of overrides.<\/p><p>Without the tests ensuring that the module still worked after the refactor, we probably wouldn\u2019t have done it as it was used on over 30,000 sites that I didn't want to break.<\/p><p>When I was learning about testing, I was working on projects where I was writing the code during the day and the tests in the evening on my own time.<\/p><p>I remember once when my manual testing had been fine, but when writing the test, I found that I\u2019d used an incorrect permission name in the code that was causing the test to fail. This was a bug that, rather than waiting for a QA Engineer or the client to discover and report, I was able to fix it locally before I'd even committed the code.<\/p><p>I also worked on an event booking and management website, where we had code responsible for calculating the number of available spaces for an event based on orders, determining the correct price based on the customer's status and the time until the event, creating voucher codes for new members and event leaders, and bulk messaging event attendees. All of the custom functionality was covered by automated tests.<\/p><p>The great thing about testing is that it gives you confidence that everything still works how you expect - not only when you wrote the code, but also in the future.<\/p><p>I've talked about this, and how to get started with automated testing in Drupal, in a presentation called <a href=\"https:\/\/www.oliverdavies.uk\/talks\/tdd-test-driven-drupal\">TDD - Test-Driven Drupal<\/a>. If you want to find out more, the slides and a video recording are embedded there.<\/p>",
"cta": "",
"tags": ["testing"]
}, {
"title": "I wrote a Neovim plugin",
"date": "1660348800",
"permalink": "/daily/2022/08/13/i-wrote-a-neovim-plugin",
"text": "<p>I enjoy writing and working with open-source software, starting back to when I started working with PHP and Drupal in 2007.<\/p><p>Since then, I've written and maintained a number of Drupal modules and themes, PHP libraries, npm packages, Ansible roles and Docker images - all of which are available on my GitHub and Drupal.org pages.<\/p><p>Just over a year ago, <a href=\"\/blog\/going-full-vim\">I switched to using Neovim full-time<\/a> for my development and DevOps work, and last week, I wrote my first Neovim plugin, written in Lua.<\/p><p>I've used Lua to configure Neovim but this is the first time that I've written and open-sourced a standalone Neovim plugin.<\/p><p>It's called <a href=\"https:\/\/github.com\/opdavies\/toggle-checkbox.nvim\">toggle-checkbox.nvim<\/a> and is used toggle checkboxes in Markdown files - something that I use frequently for to-do lists.<\/p><p>For example, this a simple list containing both checked and unchecked checkboxes:<\/p><pre><code class=\"markdown\">- [x] A completed task- [ ] An incomplete task<\/code><\/pre><p>To toggle a checkbox, the <code>x<\/code> character needs to be either added or removed, depending on whether we're checking or unchecking it.<\/p><p>This is done by calling the <code>toggle()<\/code> function within the plugin.<\/p><p>In my Neovim configuration, I've added a keymap to do this:<\/p><pre><code class=\"lua\">vim.keymap.set( \"n\", \"&lt;leader&gt;tt\", \"require('toggle-checkbox').toggle()\")<\/code><\/pre><p>This means that I can use the same keymap by running <code>&lt;leader&gt;tt<\/code> to check or uncheck a checkbox. I could use Vim's replace mode to do this, but I really wanted to have one keymap that I could use for both.<\/p><p>As it's my first Neovim plugin, I decided to keep it simple.<\/p><p>The main <code>toggle-checkbox.lua<\/code> file is currently only 41 lines of code, and whilst there is an existing Vim plugin that I could have used, I was excited to write my own plugin for Neovim, to start contributing to the Neovim ecosystem, and add a Neovim plugin to my portfolio of open-source projects.<\/p><p>You can view the plugin at <a href=\"https:\/\/github.com\/opdavies\/toggle-checkbox.nvim\">https:\/\/github.com\/opdavies\/toggle-checkbox.nvim<\/a>, as well as my Neovim configuration (which is also written in Lua) as part of <a href=\"https:\/\/github.com\/opdavies\/dotfiles\/tree\/main\/roles\/neovim\/files\">my Dotfiles repository<\/a>.<\/p>",
"cta": "",
"tags": ["neovim","open-source"]
}, {
"title": "Git Worktrees and Docker Compose",
"date": "1660262400",
"permalink": "/daily/2022/08/12/git-worktrees-docker-compose",
"text": "<p>I've recently started trialing Git worktrees again as part of my development workflow.<\/p><p>If you are unfamiliar with Git worktrees, they allow you to have muliple branches of a repository checked out at the same time in different directories.<\/p><p>For example, this is what I see within my local checkout of my website repository:<\/p><pre><code>.\u251c\u2500\u2500 config\u251c\u2500\u2500 HEAD\u251c\u2500\u2500 main\u2502\u00a0\u00a0 \u251c\u2500\u2500 ansible\u2502\u00a0\u00a0 \u251c\u2500\u2500 nginx\u2502\u00a0\u00a0 \u251c\u2500\u2500 README.md\u2502\u00a0\u00a0 \u2514\u2500\u2500 website\u251c\u2500\u2500 new-post\u2502\u00a0\u00a0 \u251c\u2500\u2500 ansible\u2502\u00a0\u00a0 \u251c\u2500\u2500 nginx\u2502\u00a0\u00a0 \u251c\u2500\u2500 README.md\u2502\u00a0\u00a0 \u2514\u2500\u2500 website\u251c\u2500\u2500 objects\u2502\u00a0\u00a0 \u251c\u2500\u2500 info\u2502\u00a0\u00a0 \u2514\u2500\u2500 pack\u251c\u2500\u2500 packed-refs\u251c\u2500\u2500 refs\u2502\u00a0\u00a0 \u251c\u2500\u2500 heads\u2502\u00a0\u00a0 \u2514\u2500\u2500 tags\u2514\u2500\u2500 worktrees \u251c\u2500\u2500 main \u2514\u2500\u2500 new-post<\/code><\/pre><p>The first thing that you'll notice is, because it's a bare clone, it looks a little different to a what you usually see in a Git repository.<\/p><p>Each worktree has it's own directory, so my \"main\" branch inside the <code>main<\/code> directory.<\/p><p>If I need to work on a different branch, such as <code>new-post<\/code>, then I can create a new worktree, move into that directory and start working. I don't need to commit or stash any in-progress work and switch branches.<\/p><h2 id=\"complications-with-docker-compose\">Complications with Docker Compose<\/h2><p>I use Docker and Docker Compose for my projects, and this caused some issues for me the last time that I tried using worktrees.<\/p><p>By default, Docker Compose will use the name of the directory that the Compose file is in to name its containers. If the directory name is \"oliverdavies-uk\", then the containers will be <code>oliverdavies-uk-web_1<\/code>, <code>oliverdavies-uk-db_1<\/code> etc.<\/p><p>This doesn't work so well if the directory is a worktree called \"main\" or \"master\" as you'll have containers called <code>main_web_1<\/code> or <code>master_db_1<\/code>.<\/p><p>The way to solve this is to use the <code>COMPOSE_PROJECT_NAME<\/code> environment variable.<\/p><p>If you prefix Docker Compose commands with <code>COMPOSE_PROJECT_NAME=your-project<\/code>, or add it to an <code>.env<\/code> file (Docker Compose will load this automatically), then this will override the prefix in the container names to be <code>your-project-{service}<\/code>.<\/p><h2 id=\"container-names-per-worktree\">Container names per worktree<\/h2><p>Whilst you could use the same Compose project name within all of your worktrees, I prefer to include the worktree name as a suffix - something like <code>my-project-main<\/code> or <code>my-project-staging<\/code> - and keep these stored in an <code>.env<\/code> file in each worktree's directory.<\/p><p>As each worktree now has unique container names, I can have multiple instances of a project running at the same time, and each worktree will have it's own separate data - meaning that I can make changes and test something in one worktree without affecting any others.<\/p><p>You can also use the <code>COMPOSE_PROJECT_NAME<\/code> variable inside Docker Compose files.<\/p><p>For example, if you use Traefik and needed to override the host URL for a service, the string will be interpolated and the project name would be injected as you'd expect.<\/p><pre><code class=\"language-yaml\">labels: - \"traefik.http.routers.${COMPOSE_PROJECT_NAME}.rule=Host( `${COMPOSE_PROJECT_NAME}.docker.localhost`, `admin.${COMPOSE_PROJECT_NAME}.docker.localhost` )\"<\/code><\/pre><p>This means that Traefik would continue to use a different URL for each worktree without you needing to make any changes to your Docker Compose file.<\/p>",
"cta": "",
"tags": []
} ]
}
Reference in a new issue View git blame Copy permalink