From e2b683259881dadb308e79c39e63876079f16836 Mon Sep 17 00:00:00 2001 From: Oliver Davies Date: Wed, 3 Jan 2024 20:00:00 +0000 Subject: [PATCH] Add daily emails and archive --- app/config/sculpin_kernel.yml | 2 + source/_daily_emails/2022-08-12.md | 75 ++++++++++ source/_daily_emails/2022-08-13.md | 47 ++++++ source/_daily_emails/2022-08-14.md | 36 +++++ source/_daily_emails/2022-08-15.md | 84 +++++++++++ source/_daily_emails/2022-08-16.md | 42 ++++++ source/_daily_emails/2022-08-17.md | 39 +++++ source/_daily_emails/2022-08-18.md | 27 ++++ source/_daily_emails/2022-08-19.md | 25 ++++ source/_daily_emails/2022-08-20.md | 22 +++ source/_daily_emails/2022-08-21.md | 29 ++++ source/_daily_emails/2022-08-22.md | 25 ++++ source/_daily_emails/2022-08-23.md | 31 ++++ source/_daily_emails/2022-08-24.md | 51 +++++++ source/_daily_emails/2022-08-25.md | 24 +++ source/_daily_emails/2022-08-26.md | 19 +++ source/_daily_emails/2022-08-27.md | 15 ++ source/_daily_emails/2022-08-28.md | 27 ++++ source/_daily_emails/2022-08-29.md | 22 +++ source/_daily_emails/2022-08-30.md | 24 +++ source/_daily_emails/2022-08-31.md | 24 +++ source/_daily_emails/2022-09-01.md | 40 +++++ source/_daily_emails/2022-09-02.md | 22 +++ source/_daily_emails/2022-09-03.md | 57 +++++++ source/_daily_emails/2022-09-04.md | 23 +++ source/_daily_emails/2022-09-05.md | 25 ++++ source/_daily_emails/2022-09-06.md | 26 ++++ source/_daily_emails/2022-09-07.md | 30 ++++ source/_daily_emails/2022-09-08.md | 34 +++++ source/_daily_emails/2022-09-09.md | 20 +++ source/_daily_emails/2022-09-10.md | 38 +++++ source/_daily_emails/2022-09-11.md | 62 ++++++++ source/_daily_emails/2022-09-12.md | 15 ++ source/_daily_emails/2022-09-14.md | 67 +++++++++ source/_daily_emails/2022-09-16.md | 111 ++++++++++++++ source/_daily_emails/2022-09-17.md | 21 +++ source/_daily_emails/2022-09-19.md | 26 ++++ source/_daily_emails/2022-09-20.md | 26 ++++ source/_daily_emails/2022-09-21.md | 34 +++++ source/_daily_emails/2022-09-22.md | 20 +++ source/_daily_emails/2022-09-23.md | 44 ++++++ source/_daily_emails/2022-09-25.md | 28 ++++ source/_daily_emails/2022-09-26.md | 20 +++ source/_daily_emails/2022-09-27.md | 16 ++ source/_daily_emails/2022-09-28.md | 20 +++ source/_daily_emails/2022-09-30.md | 83 +++++++++++ source/_daily_emails/2022-10-01.md | 34 +++++ source/_daily_emails/2022-10-02.md | 32 ++++ source/_daily_emails/2022-10-03.md | 75 ++++++++++ source/_daily_emails/2022-10-08.md | 20 +++ source/_daily_emails/2022-10-09.md | 52 +++++++ source/_daily_emails/2022-10-10.md | 14 ++ source/_daily_emails/2022-10-11.md | 18 +++ source/_daily_emails/2022-10-12.md | 28 ++++ source/_daily_emails/2022-10-17.md | 17 +++ source/_daily_emails/2022-10-18.md | 19 +++ source/_daily_emails/2022-10-19.md | 23 +++ source/_daily_emails/2022-10-20.md | 27 ++++ source/_daily_emails/2022-10-21.md | 23 +++ source/_daily_emails/2022-10-24.md | 21 +++ source/_daily_emails/2022-10-25.md | 25 ++++ source/_daily_emails/2022-10-26.md | 26 ++++ source/_daily_emails/2022-10-27.md | 17 +++ source/_daily_emails/2022-10-28.md | 25 ++++ source/_daily_emails/2022-10-29.md | 25 ++++ source/_daily_emails/2022-10-30.md | 45 ++++++ source/_daily_emails/2022-11-08.md | 26 ++++ source/_daily_emails/2022-11-09.md | 15 ++ source/_daily_emails/2022-11-11.md | 28 ++++ source/_daily_emails/2022-11-12.md | 26 ++++ source/_daily_emails/2022-11-13.md | 23 +++ source/_daily_emails/2022-11-14.md | 43 ++++++ source/_daily_emails/2022-11-15.md | 21 +++ source/_daily_emails/2022-11-16.md | 17 +++ source/_daily_emails/2022-11-17.md | 17 +++ source/_daily_emails/2022-11-18.md | 19 +++ source/_daily_emails/2022-11-19.md | 17 +++ source/_daily_emails/2022-11-20.md | 25 ++++ source/_daily_emails/2022-11-21.md | 21 +++ source/_daily_emails/2022-11-22.md | 26 ++++ source/_daily_emails/2022-11-23.md | 33 +++++ source/_daily_emails/2022-11-24.md | 29 ++++ source/_daily_emails/2022-11-25.md | 19 +++ source/_daily_emails/2022-11-30.md | 43 ++++++ source/_daily_emails/2022-12-01.md | 33 +++++ source/_daily_emails/2022-12-02.md | 27 ++++ source/_daily_emails/2022-12-03.md | 23 +++ source/_daily_emails/2022-12-04.md | 25 ++++ source/_daily_emails/2022-12-05.md | 27 ++++ source/_daily_emails/2022-12-06.md | 33 +++++ source/_daily_emails/2022-12-07.md | 23 +++ source/_daily_emails/2022-12-08.md | 64 ++++++++ source/_daily_emails/2022-12-09.md | 28 ++++ source/_daily_emails/2022-12-10.md | 53 +++++++ source/_daily_emails/2022-12-15.md | 24 +++ source/_daily_emails/2022-12-20.md | 26 ++++ source/_daily_emails/2022-12-21.md | 19 +++ source/_daily_emails/2022-12-22.md | 17 +++ source/_daily_emails/2022-12-23.md | 23 +++ source/_daily_emails/2022-12-28.md | 19 +++ source/_daily_emails/2022-12-29.md | 45 ++++++ source/_daily_emails/2022-12-30.md | 35 +++++ source/_daily_emails/2022-12-31.md | 23 +++ source/_daily_emails/2023-01-01.md | 20 +++ source/_daily_emails/2023-01-02.md | 25 ++++ source/_daily_emails/2023-01-03.md | 33 +++++ source/_daily_emails/2023-01-04.md | 63 ++++++++ source/_daily_emails/2023-01-05.md | 21 +++ source/_daily_emails/2023-01-06.md | 23 +++ source/_daily_emails/2023-01-07.md | 132 +++++++++++++++++ source/_daily_emails/2023-01-16.md | 20 +++ source/_daily_emails/2023-01-17.md | 23 +++ source/_daily_emails/2023-01-18.md | 23 +++ source/_daily_emails/2023-01-19.md | 28 ++++ source/_daily_emails/2023-01-20.md | 18 +++ source/_daily_emails/2023-01-21.md | 20 +++ source/_daily_emails/2023-01-22.md | 18 +++ source/_daily_emails/2023-01-23.md | 27 ++++ source/_daily_emails/2023-01-24.md | 23 +++ source/_daily_emails/2023-01-25.md | 25 ++++ source/_daily_emails/2023-02-07.md | 19 +++ source/_daily_emails/2023-02-08.md | 15 ++ source/_daily_emails/2023-02-09.md | 35 +++++ source/_daily_emails/2023-02-16.md | 20 +++ source/_daily_emails/2023-02-17.md | 19 +++ source/_daily_emails/2023-02-18.md | 18 +++ source/_daily_emails/2023-02-19.md | 17 +++ source/_daily_emails/2023-02-20.md | 56 +++++++ source/_daily_emails/2023-03-01.md | 18 +++ source/_daily_emails/2023-03-02.md | 14 ++ source/_daily_emails/2023-03-03.md | 20 +++ source/_daily_emails/2023-03-04.md | 19 +++ source/_daily_emails/2023-03-05.md | 18 +++ source/_daily_emails/2023-03-08.md | 19 +++ source/_daily_emails/2023-03-09.md | 18 +++ source/_daily_emails/2023-03-13.md | 16 ++ source/_daily_emails/2023-03-14.md | 23 +++ source/_daily_emails/2023-03-15.md | 19 +++ source/_daily_emails/2023-03-21.md | 19 +++ source/_daily_emails/2023-03-22.md | 20 +++ source/_daily_emails/2023-03-27.md | 20 +++ source/_daily_emails/2023-04-07.md | 17 +++ source/_daily_emails/2023-04-08.md | 21 +++ source/_daily_emails/2023-04-09.md | 22 +++ source/_daily_emails/2023-04-10.md | 23 +++ source/_daily_emails/2023-04-11.md | 57 +++++++ source/_daily_emails/2023-04-12.md | 48 ++++++ source/_daily_emails/2023-04-13.md | 35 +++++ source/_daily_emails/2023-04-14.md | 37 +++++ source/_daily_emails/2023-04-15.md | 27 ++++ source/_daily_emails/2023-04-16.md | 39 +++++ source/_daily_emails/2023-04-17.md | 26 ++++ source/_daily_emails/2023-04-18.md | 23 +++ source/_daily_emails/2023-04-19.md | 40 +++++ source/_daily_emails/2023-04-20.md | 35 +++++ source/_daily_emails/2023-04-21.md | 20 +++ source/_daily_emails/2023-04-22.md | 20 +++ source/_daily_emails/2023-04-23.md | 28 ++++ source/_daily_emails/2023-04-24.md | 33 +++++ source/_daily_emails/2023-04-25.md | 21 +++ source/_daily_emails/2023-04-26.md | 56 +++++++ source/_daily_emails/2023-04-27.md | 22 +++ source/_daily_emails/2023-04-30.md | 15 ++ source/_daily_emails/2023-05-01.md | 31 ++++ source/_daily_emails/2023-05-02.md | 25 ++++ source/_daily_emails/2023-05-03.md | 25 ++++ source/_daily_emails/2023-05-04.md | 21 +++ source/_daily_emails/2023-05-05.md | 19 +++ source/_daily_emails/2023-05-06.md | 21 +++ source/_daily_emails/2023-05-07.md | 20 +++ source/_daily_emails/2023-05-08.md | 16 ++ source/_daily_emails/2023-05-09.md | 20 +++ source/_daily_emails/2023-05-10.md | 18 +++ source/_daily_emails/2023-05-11.md | 18 +++ source/_daily_emails/2023-05-12.md | 18 +++ source/_daily_emails/2023-05-13.md | 19 +++ source/_daily_emails/2023-05-14.md | 17 +++ source/_daily_emails/2023-05-15.md | 29 ++++ source/_daily_emails/2023-05-16.md | 19 +++ source/_daily_emails/2023-05-17.md | 34 +++++ source/_daily_emails/2023-05-18.md | 17 +++ source/_daily_emails/2023-05-19.md | 19 +++ source/_daily_emails/2023-05-20.md | 19 +++ source/_daily_emails/2023-05-21.md | 19 +++ source/_daily_emails/2023-06-05.md | 19 +++ source/_daily_emails/2023-06-06.md | 19 +++ source/_daily_emails/2023-06-07.md | 27 ++++ source/_daily_emails/2023-06-08.md | 18 +++ source/_daily_emails/2023-06-09.md | 20 +++ source/_daily_emails/2023-06-10.md | 15 ++ source/_daily_emails/2023-06-11.md | 14 ++ source/_daily_emails/2023-06-12.md | 17 +++ source/_daily_emails/2023-06-13.md | 17 +++ source/_daily_emails/2023-06-14.md | 27 ++++ source/_daily_emails/2023-06-15.md | 18 +++ source/_daily_emails/2023-06-16.md | 20 +++ source/_daily_emails/2023-06-17.md | 26 ++++ source/_daily_emails/2023-06-18.md | 28 ++++ source/_daily_emails/2023-06-19.md | 38 +++++ source/_daily_emails/2023-06-20.md | 29 ++++ source/_daily_emails/2023-06-21.md | 18 +++ source/_daily_emails/2023-06-22.md | 14 ++ source/_daily_emails/2023-06-23.md | 39 +++++ source/_daily_emails/2023-06-24.md | 24 +++ source/_daily_emails/2023-06-25.md | 16 ++ source/_daily_emails/2023-06-26.md | 17 +++ source/_daily_emails/2023-06-27.md | 20 +++ source/_daily_emails/2023-06-28.md | 20 +++ source/_daily_emails/2023-06-29.md | 24 +++ source/_daily_emails/2023-06-30.md | 28 ++++ source/_daily_emails/2023-07-01.md | 30 ++++ source/_daily_emails/2023-07-02.md | 51 +++++++ source/_daily_emails/2023-07-03.md | 43 ++++++ source/_daily_emails/2023-07-04.md | 24 +++ source/_daily_emails/2023-07-05.md | 46 ++++++ source/_daily_emails/2023-07-06.md | 36 +++++ source/_daily_emails/2023-07-15.md | 22 +++ source/_daily_emails/2023-07-16.md | 25 ++++ source/_daily_emails/2023-07-17.md | 30 ++++ source/_daily_emails/2023-07-18.md | 22 +++ source/_daily_emails/2023-07-19.md | 14 ++ source/_daily_emails/2023-07-20.md | 20 +++ source/_daily_emails/2023-07-21.md | 18 +++ source/_daily_emails/2023-07-22.md | 16 ++ source/_daily_emails/2023-07-23.md | 16 ++ source/_daily_emails/2023-07-24.md | 30 ++++ source/_daily_emails/2023-07-25.md | 40 +++++ source/_daily_emails/2023-07-26.md | 19 +++ source/_daily_emails/2023-07-27.md | 23 +++ source/_daily_emails/2023-07-28.md | 23 +++ source/_daily_emails/2023-07-29.md | 25 ++++ source/_daily_emails/2023-07-30.md | 26 ++++ source/_daily_emails/2023-07-31.md | 26 ++++ source/_daily_emails/2023-08-01.md | 40 +++++ source/_daily_emails/2023-08-02.md | 17 +++ source/_daily_emails/2023-08-03.md | 19 +++ source/_daily_emails/2023-08-04.md | 27 ++++ source/_daily_emails/2023-08-05.md | 20 +++ source/_daily_emails/2023-08-06.md | 16 ++ source/_daily_emails/2023-08-07.md | 27 ++++ source/_daily_emails/2023-08-08.md | 22 +++ source/_daily_emails/2023-08-09.md | 17 +++ source/_daily_emails/2023-08-10.md | 16 ++ source/_daily_emails/2023-08-11.md | 22 +++ source/_daily_emails/2023-08-12.md | 20 +++ source/_daily_emails/2023-08-13.md | 18 +++ source/_daily_emails/2023-08-14.md | 27 ++++ source/_daily_emails/2023-08-15.md | 24 +++ source/_daily_emails/2023-08-16.md | 32 ++++ source/_daily_emails/2023-08-17.md | 29 ++++ source/_daily_emails/2023-08-18.md | 28 ++++ source/_daily_emails/2023-08-19.md | 43 ++++++ source/_daily_emails/2023-08-20.md | 57 +++++++ source/_daily_emails/2023-08-21.md | 27 ++++ source/_daily_emails/2023-08-22.md | 32 ++++ source/_daily_emails/2023-08-23.md | 19 +++ source/_daily_emails/2023-08-24.md | 24 +++ source/_daily_emails/2023-08-25.md | 18 +++ source/_daily_emails/2023-08-26.md | 20 +++ source/_daily_emails/2023-08-27.md | 25 ++++ source/_daily_emails/2023-08-28.md | 21 +++ source/_daily_emails/2023-08-29.md | 34 +++++ source/_daily_emails/2023-08-30.md | 22 +++ source/_daily_emails/2023-08-31.md | 16 ++ source/_daily_emails/2023-09-01.md | 28 ++++ source/_daily_emails/2023-09-02.md | 31 ++++ source/_daily_emails/2023-09-03.md | 18 +++ source/_daily_emails/2023-09-04.md | 22 +++ source/_daily_emails/2023-09-05.md | 24 +++ source/_daily_emails/2023-09-06.md | 25 ++++ source/_daily_emails/2023-09-07.md | 59 ++++++++ source/_daily_emails/2023-09-08.md | 24 +++ source/_daily_emails/2023-09-09.md | 26 ++++ source/_daily_emails/2023-09-10.md | 19 +++ source/_daily_emails/2023-09-11.md | 61 ++++++++ source/_daily_emails/2023-09-12.md | 22 +++ source/_daily_emails/2023-09-13.md | 48 ++++++ source/_daily_emails/2023-09-14.md | 25 ++++ source/_daily_emails/2023-09-15.md | 53 +++++++ source/_daily_emails/2023-09-16.md | 60 ++++++++ source/_daily_emails/2023-09-17.md | 26 ++++ source/_daily_emails/2023-09-18.md | 27 ++++ source/_daily_emails/2023-09-19.md | 31 ++++ source/_daily_emails/2023-09-20.md | 46 ++++++ source/_daily_emails/2023-09-21.md | 25 ++++ source/_daily_emails/2023-09-22.md | 23 +++ source/_daily_emails/2023-09-23.md | 27 ++++ source/_daily_emails/2023-09-24.md | 33 +++++ source/_daily_emails/2023-09-25.md | 27 ++++ source/_daily_emails/2023-09-26.md | 36 +++++ source/_daily_emails/2023-09-27.md | 28 ++++ source/_daily_emails/2023-09-28.md | 36 +++++ source/_daily_emails/2023-09-29.md | 36 +++++ source/_daily_emails/2023-09-30.md | 34 +++++ source/_daily_emails/2023-10-01.md | 26 ++++ source/_daily_emails/2023-10-02.md | 37 +++++ source/_daily_emails/2023-10-03.md | 33 +++++ source/_daily_emails/2023-10-04.md | 21 +++ source/_daily_emails/2023-10-05.md | 20 +++ source/_daily_emails/2023-10-06.md | 19 +++ source/_daily_emails/2023-10-07.md | 31 ++++ source/_daily_emails/2023-10-08.md | 25 ++++ source/_daily_emails/2023-10-09.md | 20 +++ source/_daily_emails/2023-10-10.md | 56 +++++++ source/_daily_emails/2023-10-11.md | 25 ++++ source/_daily_emails/2023-10-12.md | 22 +++ source/_daily_emails/2023-10-13.md | 17 +++ source/_daily_emails/2023-10-14.md | 27 ++++ source/_daily_emails/2023-10-15.md | 14 ++ source/_daily_emails/2023-10-23.md | 31 ++++ source/_daily_emails/2023-10-24.md | 31 ++++ source/_daily_emails/2023-10-25.md | 29 ++++ source/_daily_emails/2023-10-26.md | 34 +++++ source/_daily_emails/2023-10-27.md | 38 +++++ source/_daily_emails/2023-10-28.md | 19 +++ source/_daily_emails/2023-10-29.md | 22 +++ source/_daily_emails/2023-10-30.md | 25 ++++ source/_daily_emails/2023-10-31.md | 33 +++++ source/_daily_emails/2023-11-01.md | 26 ++++ source/_daily_emails/2023-11-02.md | 25 ++++ source/_daily_emails/2023-11-03.md | 28 ++++ source/_daily_emails/2023-11-04.md | 26 ++++ source/_daily_emails/2023-11-05.md | 21 +++ source/_daily_emails/2023-11-06.md | 24 +++ source/_daily_emails/2023-11-07.md | 37 +++++ source/_daily_emails/2023-11-08.md | 28 ++++ source/_daily_emails/2023-11-09.md | 24 +++ source/_daily_emails/2023-11-10.md | 23 +++ source/_daily_emails/2023-11-11.md | 28 ++++ source/_daily_emails/2023-11-12.md | 33 +++++ source/_daily_emails/2023-11-13.md | 34 +++++ source/_daily_emails/2023-11-14.md | 26 ++++ source/_daily_emails/2023-11-15.md | 33 +++++ source/_daily_emails/2023-11-16.md | 90 +++++++++++ source/_daily_emails/2023-11-17.md | 19 +++ source/_daily_emails/2023-11-18.md | 48 ++++++ source/_daily_emails/2023-11-19.md | 26 ++++ source/_daily_emails/2023-11-20.md | 35 +++++ source/_daily_emails/2023-11-21.md | 52 +++++++ source/_daily_emails/2023-11-22.md | 23 +++ source/_daily_emails/2023-11-23.md | 50 +++++++ source/_daily_emails/2023-11-24.md | 30 ++++ source/_daily_emails/2023-11-25.md | 23 +++ source/_daily_emails/2023-11-26.md | 98 ++++++++++++ source/_daily_emails/2023-11-27.md | 99 +++++++++++++ source/_daily_emails/2023-11-28.md | 52 +++++++ source/_daily_emails/2023-11-29.md | 26 ++++ source/_daily_emails/2023-11-30.md | 28 ++++ source/_daily_emails/2023-12-01.md | 32 ++++ source/_daily_emails/2023-12-04.md | 45 ++++++ source/_daily_emails/2023-12-05.md | 47 ++++++ source/_daily_emails/2023-12-06.md | 27 ++++ source/_daily_emails/2023-12-07.md | 20 +++ source/_daily_emails/2023-12-08.md | 22 +++ source/_daily_emails/2023-12-09.md | 36 +++++ source/_daily_emails/2023-12-10.md | 29 ++++ source/_daily_emails/2023-12-11.md | 44 ++++++ source/_daily_emails/2023-12-12.md | 64 ++++++++ source/_daily_emails/2023-12-13.md | 42 ++++++ source/_daily_emails/2023-12-14.md | 28 ++++ source/_daily_emails/2023-12-15.md | 23 +++ source/_daily_emails/2023-12-16.md | 28 ++++ source/_daily_emails/2023-12-17.md | 34 +++++ source/_daily_emails/2023-12-18.md | 29 ++++ source/_daily_emails/2023-12-19.md | 23 +++ source/_daily_emails/2023-12-20.md | 34 +++++ source/_daily_emails/2023-12-21.md | 14 ++ source/_daily_emails/2023-12-22.md | 23 +++ source/_daily_emails/2023-12-23.md | 28 ++++ source/_daily_emails/2023-12-24.md | 20 +++ source/_daily_emails/2023-12-25.md | 206 ++++++++++++++++++++++++++ source/_daily_emails/2023-12-26.md | 18 +++ source/_daily_emails/2023-12-27.md | 38 +++++ source/_daily_emails/2023-12-28.md | 31 ++++ source/_daily_emails/2023-12-29.md | 37 +++++ source/_daily_emails/2023-12-30.md | 27 ++++ source/_daily_emails/2023-12-31.md | 28 ++++ source/_layouts/daily_email.html.twig | 18 +++ source/_pages/archive.html | 39 +++++ 379 files changed, 11132 insertions(+) create mode 100644 source/_daily_emails/2022-08-12.md create mode 100644 source/_daily_emails/2022-08-13.md create mode 100644 source/_daily_emails/2022-08-14.md create mode 100644 source/_daily_emails/2022-08-15.md create mode 100644 source/_daily_emails/2022-08-16.md create mode 100644 source/_daily_emails/2022-08-17.md create mode 100644 source/_daily_emails/2022-08-18.md create mode 100644 source/_daily_emails/2022-08-19.md create mode 100644 source/_daily_emails/2022-08-20.md create mode 100644 source/_daily_emails/2022-08-21.md create mode 100644 source/_daily_emails/2022-08-22.md create mode 100644 source/_daily_emails/2022-08-23.md create mode 100644 source/_daily_emails/2022-08-24.md create mode 100644 source/_daily_emails/2022-08-25.md create mode 100644 source/_daily_emails/2022-08-26.md create mode 100644 source/_daily_emails/2022-08-27.md create mode 100644 source/_daily_emails/2022-08-28.md create mode 100644 source/_daily_emails/2022-08-29.md create mode 100644 source/_daily_emails/2022-08-30.md create mode 100644 source/_daily_emails/2022-08-31.md create mode 100644 source/_daily_emails/2022-09-01.md create mode 100644 source/_daily_emails/2022-09-02.md create mode 100644 source/_daily_emails/2022-09-03.md create mode 100644 source/_daily_emails/2022-09-04.md create mode 100644 source/_daily_emails/2022-09-05.md create mode 100644 source/_daily_emails/2022-09-06.md create mode 100644 source/_daily_emails/2022-09-07.md create mode 100644 source/_daily_emails/2022-09-08.md create mode 100644 source/_daily_emails/2022-09-09.md create mode 100644 source/_daily_emails/2022-09-10.md create mode 100644 source/_daily_emails/2022-09-11.md create mode 100644 source/_daily_emails/2022-09-12.md create mode 100644 source/_daily_emails/2022-09-14.md create mode 100644 source/_daily_emails/2022-09-16.md create mode 100644 source/_daily_emails/2022-09-17.md create mode 100644 source/_daily_emails/2022-09-19.md create mode 100644 source/_daily_emails/2022-09-20.md create mode 100644 source/_daily_emails/2022-09-21.md create mode 100644 source/_daily_emails/2022-09-22.md create mode 100644 source/_daily_emails/2022-09-23.md create mode 100644 source/_daily_emails/2022-09-25.md create mode 100644 source/_daily_emails/2022-09-26.md create mode 100644 source/_daily_emails/2022-09-27.md create mode 100644 source/_daily_emails/2022-09-28.md create mode 100644 source/_daily_emails/2022-09-30.md create mode 100644 source/_daily_emails/2022-10-01.md create mode 100644 source/_daily_emails/2022-10-02.md create mode 100644 source/_daily_emails/2022-10-03.md create mode 100644 source/_daily_emails/2022-10-08.md create mode 100644 source/_daily_emails/2022-10-09.md create mode 100644 source/_daily_emails/2022-10-10.md create mode 100644 source/_daily_emails/2022-10-11.md create mode 100644 source/_daily_emails/2022-10-12.md create mode 100644 source/_daily_emails/2022-10-17.md create mode 100644 source/_daily_emails/2022-10-18.md create mode 100644 source/_daily_emails/2022-10-19.md create mode 100644 source/_daily_emails/2022-10-20.md create mode 100644 source/_daily_emails/2022-10-21.md create mode 100644 source/_daily_emails/2022-10-24.md create mode 100644 source/_daily_emails/2022-10-25.md create mode 100644 source/_daily_emails/2022-10-26.md create mode 100644 source/_daily_emails/2022-10-27.md create mode 100644 source/_daily_emails/2022-10-28.md create mode 100644 source/_daily_emails/2022-10-29.md create mode 100644 source/_daily_emails/2022-10-30.md create mode 100644 source/_daily_emails/2022-11-08.md create mode 100644 source/_daily_emails/2022-11-09.md create mode 100644 source/_daily_emails/2022-11-11.md create mode 100644 source/_daily_emails/2022-11-12.md create mode 100644 source/_daily_emails/2022-11-13.md create mode 100644 source/_daily_emails/2022-11-14.md create mode 100644 source/_daily_emails/2022-11-15.md create mode 100644 source/_daily_emails/2022-11-16.md create mode 100644 source/_daily_emails/2022-11-17.md create mode 100644 source/_daily_emails/2022-11-18.md create mode 100644 source/_daily_emails/2022-11-19.md create mode 100644 source/_daily_emails/2022-11-20.md create mode 100644 source/_daily_emails/2022-11-21.md create mode 100644 source/_daily_emails/2022-11-22.md create mode 100644 source/_daily_emails/2022-11-23.md create mode 100644 source/_daily_emails/2022-11-24.md create mode 100644 source/_daily_emails/2022-11-25.md create mode 100644 source/_daily_emails/2022-11-30.md create mode 100644 source/_daily_emails/2022-12-01.md create mode 100644 source/_daily_emails/2022-12-02.md create mode 100644 source/_daily_emails/2022-12-03.md create mode 100644 source/_daily_emails/2022-12-04.md create mode 100644 source/_daily_emails/2022-12-05.md create mode 100644 source/_daily_emails/2022-12-06.md create mode 100644 source/_daily_emails/2022-12-07.md create mode 100644 source/_daily_emails/2022-12-08.md create mode 100644 source/_daily_emails/2022-12-09.md create mode 100644 source/_daily_emails/2022-12-10.md create mode 100644 source/_daily_emails/2022-12-15.md create mode 100644 source/_daily_emails/2022-12-20.md create mode 100644 source/_daily_emails/2022-12-21.md create mode 100644 source/_daily_emails/2022-12-22.md create mode 100644 source/_daily_emails/2022-12-23.md create mode 100644 source/_daily_emails/2022-12-28.md create mode 100644 source/_daily_emails/2022-12-29.md create mode 100644 source/_daily_emails/2022-12-30.md create mode 100644 source/_daily_emails/2022-12-31.md create mode 100644 source/_daily_emails/2023-01-01.md create mode 100644 source/_daily_emails/2023-01-02.md create mode 100644 source/_daily_emails/2023-01-03.md create mode 100644 source/_daily_emails/2023-01-04.md create mode 100644 source/_daily_emails/2023-01-05.md create mode 100644 source/_daily_emails/2023-01-06.md create mode 100644 source/_daily_emails/2023-01-07.md create mode 100644 source/_daily_emails/2023-01-16.md create mode 100644 source/_daily_emails/2023-01-17.md create mode 100644 source/_daily_emails/2023-01-18.md create mode 100644 source/_daily_emails/2023-01-19.md create mode 100644 source/_daily_emails/2023-01-20.md create mode 100644 source/_daily_emails/2023-01-21.md create mode 100644 source/_daily_emails/2023-01-22.md create mode 100644 source/_daily_emails/2023-01-23.md create mode 100644 source/_daily_emails/2023-01-24.md create mode 100644 source/_daily_emails/2023-01-25.md create mode 100644 source/_daily_emails/2023-02-07.md create mode 100644 source/_daily_emails/2023-02-08.md create mode 100644 source/_daily_emails/2023-02-09.md create mode 100644 source/_daily_emails/2023-02-16.md create mode 100644 source/_daily_emails/2023-02-17.md create mode 100644 source/_daily_emails/2023-02-18.md create mode 100644 source/_daily_emails/2023-02-19.md create mode 100644 source/_daily_emails/2023-02-20.md create mode 100644 source/_daily_emails/2023-03-01.md create mode 100644 source/_daily_emails/2023-03-02.md create mode 100644 source/_daily_emails/2023-03-03.md create mode 100644 source/_daily_emails/2023-03-04.md create mode 100644 source/_daily_emails/2023-03-05.md create mode 100644 source/_daily_emails/2023-03-08.md create mode 100644 source/_daily_emails/2023-03-09.md create mode 100644 source/_daily_emails/2023-03-13.md create mode 100644 source/_daily_emails/2023-03-14.md create mode 100644 source/_daily_emails/2023-03-15.md create mode 100644 source/_daily_emails/2023-03-21.md create mode 100644 source/_daily_emails/2023-03-22.md create mode 100644 source/_daily_emails/2023-03-27.md create mode 100644 source/_daily_emails/2023-04-07.md create mode 100644 source/_daily_emails/2023-04-08.md create mode 100644 source/_daily_emails/2023-04-09.md create mode 100644 source/_daily_emails/2023-04-10.md create mode 100644 source/_daily_emails/2023-04-11.md create mode 100644 source/_daily_emails/2023-04-12.md create mode 100644 source/_daily_emails/2023-04-13.md create mode 100644 source/_daily_emails/2023-04-14.md create mode 100644 source/_daily_emails/2023-04-15.md create mode 100644 source/_daily_emails/2023-04-16.md create mode 100644 source/_daily_emails/2023-04-17.md create mode 100644 source/_daily_emails/2023-04-18.md create mode 100644 source/_daily_emails/2023-04-19.md create mode 100644 source/_daily_emails/2023-04-20.md create mode 100644 source/_daily_emails/2023-04-21.md create mode 100644 source/_daily_emails/2023-04-22.md create mode 100644 source/_daily_emails/2023-04-23.md create mode 100644 source/_daily_emails/2023-04-24.md create mode 100644 source/_daily_emails/2023-04-25.md create mode 100644 source/_daily_emails/2023-04-26.md create mode 100644 source/_daily_emails/2023-04-27.md create mode 100644 source/_daily_emails/2023-04-30.md create mode 100644 source/_daily_emails/2023-05-01.md create mode 100644 source/_daily_emails/2023-05-02.md create mode 100644 source/_daily_emails/2023-05-03.md create mode 100644 source/_daily_emails/2023-05-04.md create mode 100644 source/_daily_emails/2023-05-05.md create mode 100644 source/_daily_emails/2023-05-06.md create mode 100644 source/_daily_emails/2023-05-07.md create mode 100644 source/_daily_emails/2023-05-08.md create mode 100644 source/_daily_emails/2023-05-09.md create mode 100644 source/_daily_emails/2023-05-10.md create mode 100644 source/_daily_emails/2023-05-11.md create mode 100644 source/_daily_emails/2023-05-12.md create mode 100644 source/_daily_emails/2023-05-13.md create mode 100644 source/_daily_emails/2023-05-14.md create mode 100644 source/_daily_emails/2023-05-15.md create mode 100644 source/_daily_emails/2023-05-16.md create mode 100644 source/_daily_emails/2023-05-17.md create mode 100644 source/_daily_emails/2023-05-18.md create mode 100644 source/_daily_emails/2023-05-19.md create mode 100644 source/_daily_emails/2023-05-20.md create mode 100644 source/_daily_emails/2023-05-21.md create mode 100644 source/_daily_emails/2023-06-05.md create mode 100644 source/_daily_emails/2023-06-06.md create mode 100644 source/_daily_emails/2023-06-07.md create mode 100644 source/_daily_emails/2023-06-08.md create mode 100644 source/_daily_emails/2023-06-09.md create mode 100644 source/_daily_emails/2023-06-10.md create mode 100644 source/_daily_emails/2023-06-11.md create mode 100644 source/_daily_emails/2023-06-12.md create mode 100644 source/_daily_emails/2023-06-13.md create mode 100644 source/_daily_emails/2023-06-14.md create mode 100644 source/_daily_emails/2023-06-15.md create mode 100644 source/_daily_emails/2023-06-16.md create mode 100644 source/_daily_emails/2023-06-17.md create mode 100644 source/_daily_emails/2023-06-18.md create mode 100644 source/_daily_emails/2023-06-19.md create mode 100644 source/_daily_emails/2023-06-20.md create mode 100644 source/_daily_emails/2023-06-21.md create mode 100644 source/_daily_emails/2023-06-22.md create mode 100644 source/_daily_emails/2023-06-23.md create mode 100644 source/_daily_emails/2023-06-24.md create mode 100644 source/_daily_emails/2023-06-25.md create mode 100644 source/_daily_emails/2023-06-26.md create mode 100644 source/_daily_emails/2023-06-27.md create mode 100644 source/_daily_emails/2023-06-28.md create mode 100644 source/_daily_emails/2023-06-29.md create mode 100644 source/_daily_emails/2023-06-30.md create mode 100644 source/_daily_emails/2023-07-01.md create mode 100644 source/_daily_emails/2023-07-02.md create mode 100644 source/_daily_emails/2023-07-03.md create mode 100644 source/_daily_emails/2023-07-04.md create mode 100644 source/_daily_emails/2023-07-05.md create mode 100644 source/_daily_emails/2023-07-06.md create mode 100644 source/_daily_emails/2023-07-15.md create mode 100644 source/_daily_emails/2023-07-16.md create mode 100644 source/_daily_emails/2023-07-17.md create mode 100644 source/_daily_emails/2023-07-18.md create mode 100644 source/_daily_emails/2023-07-19.md create mode 100644 source/_daily_emails/2023-07-20.md create mode 100644 source/_daily_emails/2023-07-21.md create mode 100644 source/_daily_emails/2023-07-22.md create mode 100644 source/_daily_emails/2023-07-23.md create mode 100644 source/_daily_emails/2023-07-24.md create mode 100644 source/_daily_emails/2023-07-25.md create mode 100644 source/_daily_emails/2023-07-26.md create mode 100644 source/_daily_emails/2023-07-27.md create mode 100644 source/_daily_emails/2023-07-28.md create mode 100644 source/_daily_emails/2023-07-29.md create mode 100644 source/_daily_emails/2023-07-30.md create mode 100644 source/_daily_emails/2023-07-31.md create mode 100644 source/_daily_emails/2023-08-01.md create mode 100644 source/_daily_emails/2023-08-02.md create mode 100644 source/_daily_emails/2023-08-03.md create mode 100644 source/_daily_emails/2023-08-04.md create mode 100644 source/_daily_emails/2023-08-05.md create mode 100644 source/_daily_emails/2023-08-06.md create mode 100644 source/_daily_emails/2023-08-07.md create mode 100644 source/_daily_emails/2023-08-08.md create mode 100644 source/_daily_emails/2023-08-09.md create mode 100644 source/_daily_emails/2023-08-10.md create mode 100644 source/_daily_emails/2023-08-11.md create mode 100644 source/_daily_emails/2023-08-12.md create mode 100644 source/_daily_emails/2023-08-13.md create mode 100644 source/_daily_emails/2023-08-14.md create mode 100644 source/_daily_emails/2023-08-15.md create mode 100644 source/_daily_emails/2023-08-16.md create mode 100644 source/_daily_emails/2023-08-17.md create mode 100644 source/_daily_emails/2023-08-18.md create mode 100644 source/_daily_emails/2023-08-19.md create mode 100644 source/_daily_emails/2023-08-20.md create mode 100644 source/_daily_emails/2023-08-21.md create mode 100644 source/_daily_emails/2023-08-22.md create mode 100644 source/_daily_emails/2023-08-23.md create mode 100644 source/_daily_emails/2023-08-24.md create mode 100644 source/_daily_emails/2023-08-25.md create mode 100644 source/_daily_emails/2023-08-26.md create mode 100644 source/_daily_emails/2023-08-27.md create mode 100644 source/_daily_emails/2023-08-28.md create mode 100644 source/_daily_emails/2023-08-29.md create mode 100644 source/_daily_emails/2023-08-30.md create mode 100644 source/_daily_emails/2023-08-31.md create mode 100644 source/_daily_emails/2023-09-01.md create mode 100644 source/_daily_emails/2023-09-02.md create mode 100644 source/_daily_emails/2023-09-03.md create mode 100644 source/_daily_emails/2023-09-04.md create mode 100644 source/_daily_emails/2023-09-05.md create mode 100644 source/_daily_emails/2023-09-06.md create mode 100644 source/_daily_emails/2023-09-07.md create mode 100644 source/_daily_emails/2023-09-08.md create mode 100644 source/_daily_emails/2023-09-09.md create mode 100644 source/_daily_emails/2023-09-10.md create mode 100644 source/_daily_emails/2023-09-11.md create mode 100644 source/_daily_emails/2023-09-12.md create mode 100644 source/_daily_emails/2023-09-13.md create mode 100644 source/_daily_emails/2023-09-14.md create mode 100644 source/_daily_emails/2023-09-15.md create mode 100644 source/_daily_emails/2023-09-16.md create mode 100644 source/_daily_emails/2023-09-17.md create mode 100644 source/_daily_emails/2023-09-18.md create mode 100644 source/_daily_emails/2023-09-19.md create mode 100644 source/_daily_emails/2023-09-20.md create mode 100644 source/_daily_emails/2023-09-21.md create mode 100644 source/_daily_emails/2023-09-22.md create mode 100644 source/_daily_emails/2023-09-23.md create mode 100644 source/_daily_emails/2023-09-24.md create mode 100644 source/_daily_emails/2023-09-25.md create mode 100644 source/_daily_emails/2023-09-26.md create mode 100644 source/_daily_emails/2023-09-27.md create mode 100644 source/_daily_emails/2023-09-28.md create mode 100644 source/_daily_emails/2023-09-29.md create mode 100644 source/_daily_emails/2023-09-30.md create mode 100644 source/_daily_emails/2023-10-01.md create mode 100644 source/_daily_emails/2023-10-02.md create mode 100644 source/_daily_emails/2023-10-03.md create mode 100644 source/_daily_emails/2023-10-04.md create mode 100644 source/_daily_emails/2023-10-05.md create mode 100644 source/_daily_emails/2023-10-06.md create mode 100644 source/_daily_emails/2023-10-07.md create mode 100644 source/_daily_emails/2023-10-08.md create mode 100644 source/_daily_emails/2023-10-09.md create mode 100644 source/_daily_emails/2023-10-10.md create mode 100644 source/_daily_emails/2023-10-11.md create mode 100644 source/_daily_emails/2023-10-12.md create mode 100644 source/_daily_emails/2023-10-13.md create mode 100644 source/_daily_emails/2023-10-14.md create mode 100644 source/_daily_emails/2023-10-15.md create mode 100644 source/_daily_emails/2023-10-23.md create mode 100644 source/_daily_emails/2023-10-24.md create mode 100644 source/_daily_emails/2023-10-25.md create mode 100644 source/_daily_emails/2023-10-26.md create mode 100644 source/_daily_emails/2023-10-27.md create mode 100644 source/_daily_emails/2023-10-28.md create mode 100644 source/_daily_emails/2023-10-29.md create mode 100644 source/_daily_emails/2023-10-30.md create mode 100644 source/_daily_emails/2023-10-31.md create mode 100644 source/_daily_emails/2023-11-01.md create mode 100644 source/_daily_emails/2023-11-02.md create mode 100644 source/_daily_emails/2023-11-03.md create mode 100644 source/_daily_emails/2023-11-04.md create mode 100644 source/_daily_emails/2023-11-05.md create mode 100644 source/_daily_emails/2023-11-06.md create mode 100644 source/_daily_emails/2023-11-07.md create mode 100644 source/_daily_emails/2023-11-08.md create mode 100644 source/_daily_emails/2023-11-09.md create mode 100644 source/_daily_emails/2023-11-10.md create mode 100644 source/_daily_emails/2023-11-11.md create mode 100644 source/_daily_emails/2023-11-12.md create mode 100644 source/_daily_emails/2023-11-13.md create mode 100644 source/_daily_emails/2023-11-14.md create mode 100644 source/_daily_emails/2023-11-15.md create mode 100644 source/_daily_emails/2023-11-16.md create mode 100644 source/_daily_emails/2023-11-17.md create mode 100644 source/_daily_emails/2023-11-18.md create mode 100644 source/_daily_emails/2023-11-19.md create mode 100644 source/_daily_emails/2023-11-20.md create mode 100644 source/_daily_emails/2023-11-21.md create mode 100644 source/_daily_emails/2023-11-22.md create mode 100644 source/_daily_emails/2023-11-23.md create mode 100644 source/_daily_emails/2023-11-24.md create mode 100644 source/_daily_emails/2023-11-25.md create mode 100644 source/_daily_emails/2023-11-26.md create mode 100644 source/_daily_emails/2023-11-27.md create mode 100644 source/_daily_emails/2023-11-28.md create mode 100644 source/_daily_emails/2023-11-29.md create mode 100644 source/_daily_emails/2023-11-30.md create mode 100644 source/_daily_emails/2023-12-01.md create mode 100644 source/_daily_emails/2023-12-04.md create mode 100644 source/_daily_emails/2023-12-05.md create mode 100644 source/_daily_emails/2023-12-06.md create mode 100644 source/_daily_emails/2023-12-07.md create mode 100644 source/_daily_emails/2023-12-08.md create mode 100644 source/_daily_emails/2023-12-09.md create mode 100644 source/_daily_emails/2023-12-10.md create mode 100644 source/_daily_emails/2023-12-11.md create mode 100644 source/_daily_emails/2023-12-12.md create mode 100644 source/_daily_emails/2023-12-13.md create mode 100644 source/_daily_emails/2023-12-14.md create mode 100644 source/_daily_emails/2023-12-15.md create mode 100644 source/_daily_emails/2023-12-16.md create mode 100644 source/_daily_emails/2023-12-17.md create mode 100644 source/_daily_emails/2023-12-18.md create mode 100644 source/_daily_emails/2023-12-19.md create mode 100644 source/_daily_emails/2023-12-20.md create mode 100644 source/_daily_emails/2023-12-21.md create mode 100644 source/_daily_emails/2023-12-22.md create mode 100644 source/_daily_emails/2023-12-23.md create mode 100644 source/_daily_emails/2023-12-24.md create mode 100644 source/_daily_emails/2023-12-25.md create mode 100644 source/_daily_emails/2023-12-26.md create mode 100644 source/_daily_emails/2023-12-27.md create mode 100644 source/_daily_emails/2023-12-28.md create mode 100644 source/_daily_emails/2023-12-29.md create mode 100644 source/_daily_emails/2023-12-30.md create mode 100644 source/_daily_emails/2023-12-31.md create mode 100644 source/_layouts/daily_email.html.twig create mode 100644 source/_pages/archive.html diff --git a/app/config/sculpin_kernel.yml b/app/config/sculpin_kernel.yml index 7c6a0cb85..36c72975e 100644 --- a/app/config/sculpin_kernel.yml +++ b/app/config/sculpin_kernel.yml @@ -1,4 +1,6 @@ sculpin_content_types: + daily_emails: + permalink: /archive/:year/:month/:day/:basename/ pages: permalink: /:basename/ podcast_episode: diff --git a/source/_daily_emails/2022-08-12.md b/source/_daily_emails/2022-08-12.md new file mode 100644 index 000000000..c235f8b2a --- /dev/null +++ b/source/_daily_emails/2022-08-12.md @@ -0,0 +1,75 @@ +--- +permalink: archive/2022/08/12/git-worktrees-docker-compose +title: Git Worktrees and Docker Compose +pubDate: 2022-08-12 +--- + +I've recently started trialing Git worktrees again as part of my development workflow. + +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. + +For example, this is what I see within my local checkout of my website repository: + +``` +. +├── config +├── HEAD +├── main +│   ├── ansible +│   ├── nginx +│   ├── README.md +│   └── website +├── new-post +│   ├── ansible +│   ├── nginx +│   ├── README.md +│   └── website +├── objects +│   ├── info +│   └── pack +├── packed-refs +├── refs +│   ├── heads +│   └── tags +└── worktrees + ├── main + └── new-post +``` + +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. + +Each worktree has it's own directory, so my "main" branch inside the `main` directory. + +If I need to work on a different branch, such as `new-post`, 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. + +## Complications with Docker Compose + +I use Docker and Docker Compose for my projects, and this caused some issues for me the last time that I tried using worktrees. + +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 `oliverdavies-uk-web_1`, `oliverdavies-uk-db_1` etc. + +This doesn't work so well if the directory is a worktree called "main" or "master" as you'll have containers called `main_web_1` or `master_db_1`. + +The way to solve this is to use the `COMPOSE_PROJECT_NAME` environment variable. + +If you prefix Docker Compose commands with `COMPOSE_PROJECT_NAME=your-project`, or add it to an `.env` file (Docker Compose will load this automatically), then this will override the prefix in the container names to be `your-project-{service}`. + +## Container names per worktree + +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 `my-project-main` or `my-project-staging` - and keep these stored in an `.env` file in each worktree's directory. + +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. + +You can also use the `COMPOSE_PROJECT_NAME` variable inside Docker Compose files. + +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. + +```yaml +labels: + - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.rule=Host( + `${COMPOSE_PROJECT_NAME}.docker.localhost`, + `admin.${COMPOSE_PROJECT_NAME}.docker.localhost` + )" +``` + +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. diff --git a/source/_daily_emails/2022-08-13.md b/source/_daily_emails/2022-08-13.md new file mode 100644 index 000000000..f84564573 --- /dev/null +++ b/source/_daily_emails/2022-08-13.md @@ -0,0 +1,47 @@ +--- +permalink: archive/2022/08/13/i-wrote-a-neovim-plugin +pubDate: 2022-08-13 +title: I wrote a Neovim plugin +tags: + - neovim + - open-source +--- + +I enjoy writing and working with open-source software, starting back to when I started working with PHP and Drupal in 2007. + +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. + +Just over a year ago, [I switched to using Neovim full-time](/blog/going-full-vim) for my development and DevOps work, and last week, I wrote my first Neovim plugin, written in Lua. + +I've used Lua to configure Neovim but this is the first time that I've written and open-sourced a standalone Neovim plugin. + +It's called [toggle-checkbox.nvim](https://github.com/opdavies/toggle-checkbox.nvim) and is used toggle checkboxes in Markdown files - something that I use frequently for to-do lists. + +For example, this a simple list containing both checked and unchecked checkboxes: + +```markdown +- [x] A completed task +- [ ] An incomplete task +``` + +To toggle a checkbox, the `x` character needs to be either added or removed, depending on whether we're checking or unchecking it. + +This is done by calling the `toggle()` function within the plugin. + +In my Neovim configuration, I've added a keymap to do this: + +```lua +vim.keymap.set( + "n", + "tt", + "require('toggle-checkbox').toggle()" +) +``` + +This means that I can use the same keymap by running `tt` 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. + +As it's my first Neovim plugin, I decided to keep it simple. + +The main `toggle-checkbox.lua` 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. + +You can view the plugin at , as well as my Neovim configuration (which is also written in Lua) as part of [my Dotfiles repository](https://github.com/opdavies/dotfiles/tree/main/roles/neovim/files). diff --git a/source/_daily_emails/2022-08-14.md b/source/_daily_emails/2022-08-14.md new file mode 100644 index 000000000..3347a630d --- /dev/null +++ b/source/_daily_emails/2022-08-14.md @@ -0,0 +1,36 @@ +--- +permalink: archive/2022/08/14/why-i-write-tests +pubDate: 2022-08-14 +title: "Why I write automated tests" +tags: [testing] +--- + +In February 2012, I saw a tweet from Tim Millwood asking if anyone wanted to maintain or co-maintain a Drupal module called [Override Node Options](https://www.drupal.org/project/override_node_options). + +It had more than 9,200 active installations at that time, with versions for Drupal 5, 6 and 7. + +I said yes and became the module’s maintainer. + +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. + +There have been two main things that come to mind with this module, related to automated testing. + +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’t tests for the new permissions but I committed the patch and added the tests later. + +Without the tests to ensure that the original functionality still worked, I probably wouldn’t have committed the patch and would have just closed the issue. + +More recently, a friend and ex-colleague and I decided to refactor some of the module's code. + +We wanted to split the `override_node_options.module` 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’d just need to create a new file for it and add it to the list of overrides. + +Without the tests ensuring that the module still worked after the refactor, we probably wouldn’t have done it as it was used on over 30,000 sites that I didn't want to break. + +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. + +I remember once when my manual testing had been fine, but when writing the test, I found that I’d 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. + +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. + +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. + +I've talked about this, and how to get started with automated testing in Drupal, in a presentation called [TDD - Test-Driven Drupal]({{site.url}}/talks/tdd-test-driven-drupal). If you want to find out more, the slides and a video recording are embedded there. diff --git a/source/_daily_emails/2022-08-15.md b/source/_daily_emails/2022-08-15.md new file mode 100644 index 000000000..6d2435d3d --- /dev/null +++ b/source/_daily_emails/2022-08-15.md @@ -0,0 +1,84 @@ +--- +permalink: archive/2022/08/15/using-run-file-simplify-project-tasks +pubDate: 2022-08-15 +title: Using a "run" file to simplify project tasks +tags: ["php"] +--- + +Every project has its own set of commands that need to be run regularly. + +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. + +One common way to simplify these commands is using a `Makefile`. + +A Makefile contains a number of named targets that you can reference, and each has one or more commands that it executes. + +For example: + +```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) +``` + +With this Makefile, I can run `make start` to start the project, and `make stop` to stop it. + +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. + +In the example, to pass arguments to the `drush` command, I'd have to type `ARGS="cache:rebuild" make drush` for them to get added and the command to work as expected. + +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 [Working with Workspace]({{site.url}}/talks/working-with-workspace) and used it on some of my own personal and client projects. + +## What I'm using now + +The solution that I'm using now is a `run` file, which is something that I learned from Nick Janetakis' blog and YouTube channel. + +It's a simple Bash file where you define your commands (or tasks) as functions, and then execute them by typing `./run test` or `./run composer require something`. + +Here's the Makefile example, but as a `run` script: + +```bash +#!/usr/bin/env bash + +function 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}" +``` + +As it's Bash, I can just use `$1`, `$2` etc to get specific arguments, or `$@` to get them all, so `./run drush cache:rebuild` works as expected and any additional arguments are included. + +You can group tasks by having functions like `test:unit` and `test:commit`, 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 `docker-compose exec` within the PHP container that other commands like `drush`, `console` or `composer` could re-use. + +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. + +I also use one within my Talks repository to generate PDF files using rst2pdf, present them using phdpc, and generate thumbnail images. + +For examples of `run` files that I use in my open-source code, [you can look in my public GitHub repositories](https://github.com/search?l=Shell&q=user%3Aopdavies+filename%3Arun&type=Code), and for more information, here is [Nick's blog post where I first found the idea](https://nickjanetakis.com/blog/replacing-make-with-a-shell-script-for-running-your-projects-tasks). diff --git a/source/_daily_emails/2022-08-16.md b/source/_daily_emails/2022-08-16.md new file mode 100644 index 000000000..c94c05d57 --- /dev/null +++ b/source/_daily_emails/2022-08-16.md @@ -0,0 +1,42 @@ +--- +permalink: archive/2022/08/16/what-are-git-hooks-why-are-they-useful +pubDate: 2022-08-16 +title: "What are Git hooks and why are they useful?" +tags: ["git"] +--- + +In yesterday's email, I mentioned Git hooks but didn't go into any detail. So, what are they? + +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. + +By default, the script files need to be within the `.git/hooks` directory, have executable permissions, and be named to exactly match the name of the hook - e.g. `pre-push` - with no file extension. + +If it returns an error exit code then the process is stopped and the action doesn't complete. + +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. + +But, the main benefit that I get from Git hooks if from the `pre-push` hook. + +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. + +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. + +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. + +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. + +But what have Git hooks got to do with the "run" file? + +Firstly, I like to keep the scripts as minimal as possible and move the majority of the code into functions within the `run` file. This means that the scripts are only responsible for running functions like `./run test:commit` 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). + +Secondly, I like to simplify the setup of Git hooks with their own functions. + +For security reasons, the `.git/hooks` directory cannot be committed and pushed to your remote so they need to be enabled per user within their own clone of the repository. + +A common workaround is to put the scripts in a directory like `.githooks` and either symlink them to where Git expects them to be, or to use the `core.hooksPath` configuration option and change where Git is going to look. + +I like to lower the barrier for any team members by creating `git-hooks:on` and `git-hooks:off` functions which either set or unset the `core.hooksPath`. 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. + +There are other Git hooks that can be used but just using `pre-commit` and `pre-push` 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 `run` file. + +Lastly, I've created as an example with a minimal `run` file and some example hooks. diff --git a/source/_daily_emails/2022-08-17.md b/source/_daily_emails/2022-08-17.md new file mode 100644 index 000000000..e0474f33b --- /dev/null +++ b/source/_daily_emails/2022-08-17.md @@ -0,0 +1,39 @@ +--- +permalink: archive/2022/08/17/one-more-run-command-git-worktrees +pubDate: 2022-08-17 +title: One more "run" command, for Git worktrees +tags: ["drupal", "git"] +--- + +Here's another `run` file example, this time relating to Git worktrees... + +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. + +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. + +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). + +I could do this manually each time or I could automate it in a `run` command. :) + +Here's the function that I came up with: + +```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 +} +``` + +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. + +This is a good example of why I like using `run` files and how I use them to automate and simplify parts of my workflow. diff --git a/source/_daily_emails/2022-08-18.md b/source/_daily_emails/2022-08-18.md new file mode 100644 index 000000000..c3d004b01 --- /dev/null +++ b/source/_daily_emails/2022-08-18.md @@ -0,0 +1,27 @@ +--- +permalink: archive/2022/08/18/talking-drupal-tailwind-css +pubDate: 2022-08-18 +title: "'Talking Drupal' and Tailwind CSS" +tags: + - css + - tailwind-css + - twig +--- + +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. + +I've become a big fan of this approach to styling websites and was an early adopter of Tailwind, and have released [a starter-kit theme](https://www.drupal.org/project/tailwindcss) for building custom Drupal themes with Tailwind CSS based on what I was using for my own client projects. + +## Rebuilding Talking Drupal with Tailwind + +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 blog post]({{site.url}}/blog/uis-ive-rebuilt-tailwind-css) that lists the ones that I've done before). + +After this podcast episode, I built a [Tailwind version of the Talking Drupal homepage](https://talking-drupal-tailwindcss.oliverdavies.uk). + +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. + +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. + +[The code repository](https://github.com/opdavies/talking-drupal-tailwindcss) 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. + +You can [listen to the episode](https://talkingdrupal.com/338), and if you want any more information, the slides and video from my [Taking Flight with Tailwind CSS talk]({{site.url}}/talks/taking-flight-with-tailwind-css) are on my website. diff --git a/source/_daily_emails/2022-08-19.md b/source/_daily_emails/2022-08-19.md new file mode 100644 index 000000000..dcda3afc8 --- /dev/null +++ b/source/_daily_emails/2022-08-19.md @@ -0,0 +1,25 @@ +--- +permalink: archive/2022/08/19/pair-programming-or-code-reviews +pubDate: 2022-08-19 +title: Pair programming or code reviews? +--- + +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. + +On the majority of teams and projects that I've worked on, this was how things were done. + +Tasks would be worked on in separate branches which would need to be reviewed by one or more other Developers before being merged. + +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. + +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. + +But there are other benefits too. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-08-20.md b/source/_daily_emails/2022-08-20.md new file mode 100644 index 000000000..f5b7dcc3b --- /dev/null +++ b/source/_daily_emails/2022-08-20.md @@ -0,0 +1,22 @@ +--- +pubDate: 2022-08-20 +title: "A return to offline meetups and conferences" +permalink: "archive/2022/08/20/return-to-offline-meetups-conferences" +tags: ["community"] +--- + +Yesterday, I dusted off our Meetup page and posted our next [PHP South Wales meetup](https://www.meetup.com/php-south-wales) event. + +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. + +As well as organising our online meetups during COVID, I attended a lot of other online events, [usually giving various talks or workshops]({{site.url}}/blog/speaking-remotely-during-covid-19), and whilst they were good for a while, I eventually started to get burned out by them. + +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. + +It's been great to see some offline events returning, from local user groups to conferences such as DevOpsDays, DrupalCon and SymfonyLive. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-08-21.md b/source/_daily_emails/2022-08-21.md new file mode 100644 index 000000000..a1916fbe7 --- /dev/null +++ b/source/_daily_emails/2022-08-21.md @@ -0,0 +1,29 @@ +--- +permalink: archive/2022/08/21/2022-08-21 +pubDate: 2022-08-21 +title: "Why I use Docker and Docker Compose for my projects" +tags: + - docker +--- + +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. + + + +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. + +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. + +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. + +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. + +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 `docker-compose build` or `docker-compose run` command within a pipeline to check that the project builds correctly and to execute tasks such as automated tests or static analysis. + +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. + +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. + +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. + +For some examples of how I work with Docker and Docker Compose, you can [see my public GitHub repositories](https://github.com/opdavies?tab=repositories&q=docker) and how things are put together there. diff --git a/source/_daily_emails/2022-08-22.md b/source/_daily_emails/2022-08-22.md new file mode 100644 index 000000000..45af8ed7f --- /dev/null +++ b/source/_daily_emails/2022-08-22.md @@ -0,0 +1,25 @@ +--- +permalink: archive/2022/08/22/2022-08-22 +pubDate: 2022-08-22 +title: "Being a T-shaped Developer" +--- + +A blog post appeared on my feed this morning, titled [How to be T-Shaped](https://www.nomensa.com/blog/how-to-be-t-shaped). + +"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. + +I would say that I'm T-shaped. + +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. + +As I worked on my own personal and client projects, I needed to learn more complementary skills. + +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. + +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. + +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. + +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. + +I've said that one of the best and worst things about software development is that there's always something new to learn! diff --git a/source/_daily_emails/2022-08-23.md b/source/_daily_emails/2022-08-23.md new file mode 100644 index 000000000..7b546f53e --- /dev/null +++ b/source/_daily_emails/2022-08-23.md @@ -0,0 +1,31 @@ +--- +pubDate: 2022-08-23 +title: "Git: GUI or command-line?" +permalink: "archive/2022/08/23/git-gui-command-line" +tags: + - "git" +--- + +I’ve 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’s version control system. + +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. + +In fact, GitHub only started two years earlier in 2008, and GitLab wasn’t around until 2014. + +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. + +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. + +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. + +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. + +In my opinion, understanding what’s 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’ve 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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-08-24.md b/source/_daily_emails/2022-08-24.md new file mode 100644 index 000000000..3790c2a25 --- /dev/null +++ b/source/_daily_emails/2022-08-24.md @@ -0,0 +1,51 @@ +--- +permalink: archive/2022/08/24/2022-08-24 +pubDate: 2022-08-24 +title: "How I've configured Git" +tags: + - "git" +--- + +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. + +First, I rarely ever run the `git` command - I usually run a `g` function that I've created within my zsh configuration. + +Rather than being an simple alias, it's a shell function that will run `git status -sb` to show the current status of the repository if there are no additional arguments. If there are, such as when running `g add`, then this is executed as a normal Git command. (This is something that I first saw from Thoughtbot, if I remember correctly). + +## Using .gitconfig + +The main part of my configuration is within Git's `~/.gitconfig` file, where I can configure Git to work how I want. + +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 `ff = only` and `rebase = true` to the `[pull]` section of my `~/.gitconfig` file. + +I can do this manually, or running `git config --global pull.rebase true` will set the option but also update the file automatically. + +Some of the tweaks that I've made are to only allow fast-forward merges by adding `merge.ff = only`, automatically squash commits when rebasing by setting `rebase.autosquash = true`, and automatically pruning branches by adding `fetch.prune = true`. + +### Simple aliases + +Another way that I configure Git is using aliases, which are also within the `~/.gitconfig` file. + +For example, if I ran `git config --global alias.b "branch"`, then running `git b` would just run `git branch` which shortens the command and saves some time and keystrokes. + +I have similar one- or two letter "short" aliases for pushing and pulling code, and some that also set some additional arguments such as `aa` for `add --all` and `worktrees` for `worktree list`. + +### More complicated aliases + +Aliases can be more complex if needed by prefixing it with a `!`, meaning that it executes it as a shell command. + +This means that I can have `repush = !git pull --rebase && git push` to chain two separate Git commands and combine them into one, and `ureset = !git reset --hard $(git upstream)` which executes the full command, including another alias as part of it. + +I also have `issues = !gh issue list --web` and `pulls = !gh pr list --web` to open the current repository's GitHub issues or pull requests respectively, which can be done as it's not limited to just running `git` commands. + +### Custom functions + +Finally, if an alias is getting too long or complex, then it can extracted to it's own file. + +Any executable file within your `$PATH` that starts with `git-` will automatically become a Git command. + +One example that I have is [git-cm](https://github.com/opdavies/dotfiles/blob/2b20cd1e59ae3b1fa81074077e855cbdfa02f146/bin/bin/git-cm) which, similar to the `g` 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. + +These are just some examples. If you want to see my entire configuration, then check out [my dotfiles repository on GitHub](https://github.com/opdavies/dotfiles/tree/2b20cd1e59ae3b1fa81074077e855cbdfa02f146/roles/git/files). + +How have you configured Git for your workflow? Reply to this email and let me know. diff --git a/source/_daily_emails/2022-08-25.md b/source/_daily_emails/2022-08-25.md new file mode 100644 index 000000000..304e1a531 --- /dev/null +++ b/source/_daily_emails/2022-08-25.md @@ -0,0 +1,24 @@ +--- +pubDate: 2022-08-25 +title: "Why I work in Neovim" +tags: ["vim", "neovim"] +permalink: "archive/2022/08/25/why-i-work-in-neovim" +--- + +Over a year ago, I posted that I was [switching to using Neovim full-time]({{site.url}}/blog/going-full-vim) for my development work. + +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. + +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. + +TJ DeVries - a Neovim core team member - has recently coined the term "PDE" (a personalised development environment) which, for me, describes Neovim perfectly. + +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. + +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. + +I've learned Lua. Not just for my own Neovim configuration, but I recently wrote and open-sourced my own simple plugin. + +Like Git, I enjoy and prefer using tools that I can configure and adapt to my workflow. + +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. diff --git a/source/_daily_emails/2022-08-26.md b/source/_daily_emails/2022-08-26.md new file mode 100644 index 000000000..d6cb695f8 --- /dev/null +++ b/source/_daily_emails/2022-08-26.md @@ -0,0 +1,19 @@ +--- +pubDate: 2022-08-26 +title: "Always be learning" +permalink: "archive/2022/08/26/always-be-learning" +--- + +I've been a Developer for 15 years and one thing that I've always focussed on is to always keep learning. + +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. + +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. + +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. + +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. + +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. + +As I said in a previous email, one of the great things about software development is that there's always something new to learn. diff --git a/source/_daily_emails/2022-08-27.md b/source/_daily_emails/2022-08-27.md new file mode 100644 index 000000000..3e6950ece --- /dev/null +++ b/source/_daily_emails/2022-08-27.md @@ -0,0 +1,15 @@ +--- +pubDate: 2022-08-27 +title: "Giving back" +permalink: "archive/2022/08/27/giving-back" +--- + +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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-08-28.md b/source/_daily_emails/2022-08-28.md new file mode 100644 index 000000000..c531f4e43 --- /dev/null +++ b/source/_daily_emails/2022-08-28.md @@ -0,0 +1,27 @@ +--- +pubDate: 2022-08-28 +title: "How I started programming" +permalink: "archive/2022-08-28/how-started-programming" +--- + +In 2007, I was working in the IT sector in a Desktop Support role but hadn't done any coding professionally. + +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. + +This would be my introduction to programming. + +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. + +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. + +I wanted to make it more dynamic, and started to learn about PHP and MySQL from video courses and online forums. + +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 screenshot of the reply](https://twitter.com/opdavies/status/1185456825103241216)). This was a new concept to me as until that point, I'd written everything so far myself whilst learning it. + +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. + +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. + +I started blogging, attending meetups, and when an opportunity to switch careers to software development came along, I applied for and got the job. + +That job was also using Drupal and, in another email, I'll write more about why I still like and use Drupal years later. diff --git a/source/_daily_emails/2022-08-29.md b/source/_daily_emails/2022-08-29.md new file mode 100644 index 000000000..78ba11f03 --- /dev/null +++ b/source/_daily_emails/2022-08-29.md @@ -0,0 +1,22 @@ +--- +pubDate: 2022-08-29 +title: "Why I like Drupal" +permalink: "archive/2022/08/29/why-like-drupal" +tags: ["drupal"] +--- + +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. + +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. + +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. + +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. + +Whatever the size and complexity of the project, Drupal is flexible enough to fit it. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-08-30.md b/source/_daily_emails/2022-08-30.md new file mode 100644 index 000000000..7b1a35775 --- /dev/null +++ b/source/_daily_emails/2022-08-30.md @@ -0,0 +1,24 @@ +--- +pubDate: 2022-08-30 +title: "Why I don't only use Drupal" +permalink: "archive/2022/08/30/why-dont-only-use-drupal" +tags: ["drupal"] +--- + +Yesterday, [I shared some of the reasons]({{site.url}}/archive/2022/08/29/why-like-drupal) 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. + +Essentially, I always try to recommend and use the best tool for the job. + +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. + +This is the same approach that I use when making recommendations for a new project. + +I've delivered projects using other tools like the Symfony framework or a static site generator, as long as it fitted the requirements. + +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. + +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. + +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. + +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 [Tailwind CSS]({{site.url}}/talks/taking-flight-with-tailwind-css) and [Illuminate Collections]({{site.url}}//talks/using-illuminate-collections-outside-laravel) that I've been able to bring back into my other Drupal projects. diff --git a/source/_daily_emails/2022-08-31.md b/source/_daily_emails/2022-08-31.md new file mode 100644 index 000000000..fdefa4a2d --- /dev/null +++ b/source/_daily_emails/2022-08-31.md @@ -0,0 +1,24 @@ +--- +title: "To monorepo, or not to monorepo?" +permalink: "archive/2022/08/31/monorepo-or-not" +pubDate: 2022-08-31 +tags: ["git"] +--- + +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. + +It's something that I've been trialling recently in my [Docker examples](https://github.com/opdavies/docker-examples) and [Docker images](https://github.com/OliverDaviesLtd/docker-images) repositories, where one repository contains and builds multiple Docker images. + +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. + +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. + +Using a monorepo approach, all of these projects would be in the same repository. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-09-01.md b/source/_daily_emails/2022-09-01.md new file mode 100644 index 000000000..638335fb0 --- /dev/null +++ b/source/_daily_emails/2022-09-01.md @@ -0,0 +1,40 @@ +--- +pubDate: 2022-09-01 +title: "Conventional commits and CHANGELOGs" +tags: [] +permalink: "archive/2022/09/01/conventional-commits-changelogs" +--- + +One of the things that I've done since joining my current team is to implement a standard approach for our commit messages. + +We're using the [Conventional Commits specification](https://www.conventionalcommits.org), which gives some additional rules to follow when writing commit messages. + +For example: + +``` +build(deps): update Drupal to 9.4.5 + +Updated Drupal's `drupal/core-*` packages to 9.4.5. + +See https://www.drupal.org/project/drupal/releases/9.4.5. + +Refs: #123 +``` + +We can see that this is a `build` task that relates to our project dependencies, in this example, we're updating Drupal core. We can also see this in the subject line. + +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. + +So far, I've mostly used the `build`, `chore`, `ci`, `docs` and `refactor` commit types, which are types that are recommended and used by [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). + +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. + +Conventional commits also works nicely with something else that we've introduced, which is a CHANGELOG file. + +There are tools that can generate and update CHANGELOGs automatically from conventional commits, but so far, we've been following the [Keep a Changelog](https://keepachangelog.com) format. + +It's easy to match the commits to the `Added`, `Changed` or `Fixed` types, and although it needs to be updated manually, it's easy to add to the `Unreleased` section of the file and re-organise everything within the appropriate headings as needed as part of a release. + +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. + +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. diff --git a/source/_daily_emails/2022-09-02.md b/source/_daily_emails/2022-09-02.md new file mode 100644 index 000000000..7857b9169 --- /dev/null +++ b/source/_daily_emails/2022-09-02.md @@ -0,0 +1,22 @@ +--- +title: "Automating all the things with Ansible" +pubDate: 2022-09-02 +permalink: "archive/2022/09/02/automating-all-the-things-with-ansible" +tags: ["ansible"] +--- + +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 [presented talks on]({{site.url}}/talks/deploying-php-ansible-ansistrano) previously. + +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. + +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. + +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. + +Lastly, I use Ansible to deploy application code onto servers and automatically run any required steps, ensuring that deployments are simple, robust and repeatable. + +In the next few emails, I'll explain how I've been able to utilise Ansible for each of these situations. + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). diff --git a/source/_daily_emails/2022-09-03.md b/source/_daily_emails/2022-09-03.md new file mode 100644 index 000000000..479cec25c --- /dev/null +++ b/source/_daily_emails/2022-09-03.md @@ -0,0 +1,57 @@ +--- +pubDate: 2022-09-03 +title: Creating infrastructure with Ansible +permalink: archives/2022/09/03/creating-infrastructure-with-ansible +tags: ["ansible"] +--- + +Let's start at the beginning. + +If we want to automate our infrastructure then we first need to create it. This could be done manually or we can automate it. + +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. + +By using one of these tools, you can programatically provision a new, blank server that is ready for you to be configered. + +For example, to [create a DigitalOcean droplet](https://docs.ansible.com/ansible/latest/collections/community/digitalocean/digital_ocean_module.htm): + +```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 +``` + +Running this playbook will create a new Droplet with the specified name, size, and operating system, and within the specified region. + +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. + +[Creating an Amazon EC2 instance](https://docs.ansible.com/ansible/latest/collections/amazon/aws/ec2_instance_module.html#ansible-collections-amazon-aws-ec2-instance-module) looks very similar: + +```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 +``` + +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. + +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. + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). diff --git a/source/_daily_emails/2022-09-04.md b/source/_daily_emails/2022-09-04.md new file mode 100644 index 000000000..c20427e28 --- /dev/null +++ b/source/_daily_emails/2022-09-04.md @@ -0,0 +1,23 @@ +--- +title: "Using Ansible for server configuration" +pubDate: 2022-09-04 +permalink: "archive/2022/09/04/using-ansible-for-server-configuration" +--- + +[In yesterday's email]({{site.url}}/archives/2022/09/03/creating-infrastructure-with-ansible), I described how to set up a blank server with Ansible. + +Now that we've done that, it needs to be configured. + +Once the server’s IP address or hostname has been added to a `hosts.ini` file, you can run ad-hoc commands against it - such as `ansible all -i hosts.ini -m ping` to run Ansible's `ping` module on all of the hosts in your inventory and check that you can connect to them. + +Another useful one that you can use is the `shell` module, that runs ad-hoc run commands on each host. If you need to check the uptime of each of your servers, run `ansible all -i hosts.ini -m shell -a uptime`. You can replace the last argument with any other shell command that you need to run, like `df` or `free`. + +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. + +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. + +Very quickly, you can get a full stack installed and configured - ready to serve your application. + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). diff --git a/source/_daily_emails/2022-09-05.md b/source/_daily_emails/2022-09-05.md new file mode 100644 index 000000000..c1f22cc1d --- /dev/null +++ b/source/_daily_emails/2022-09-05.md @@ -0,0 +1,25 @@ +--- +title: "Using Ansible for local environment configuration" +pubDate: 2022-09-05 +permalink: "archive/2022/09/05/using-ansible-for-local-configuration" +--- + +As well as [configuring servers]({{site.url}}/archive/2022/09/04/using-ansible-for-server-configuration), you can use Ansible to configure your own local machine and development environment. + +The change that you need to make is within the `hosts.ini` file: + +``` +127.0.0.1 ansible_connection=local +``` + +Instead of the server's IP address or hostname, use the localhost IP address and set `ansible_connection` to `local` to tell Ansible to run locally instead of using an SSH connection. + +Another way to do this is to set `hosts: 127.0.0.1` and `connection: true` in your playbook. + +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. + +For an example of this, you can see [my dotfiles repository on GitHub](https://github.com/opdavies/dotfiles). + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). diff --git a/source/_daily_emails/2022-09-06.md b/source/_daily_emails/2022-09-06.md new file mode 100644 index 000000000..149f6bb8c --- /dev/null +++ b/source/_daily_emails/2022-09-06.md @@ -0,0 +1,26 @@ +--- +title: "Deploying applications with Ansible" +pubDate: 2022-09-06 +permalink: "archive/2022/09/06/deploying-applications-with-ansible" +--- + +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. + +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 `synchronize` module. + +It's a wrapper around the `rsync` command and makes it as simple as specifying `src` and `dest` values for the local and remote paths. + +For more complicated deployments, I like to use a tool called Ansistrano - an Ansible port of a deployment tool called Capistrano. + +It creates a new directory for each release and updates a `current` symlink to identify and serve the current release, and can share files and directories between releases. + +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. + +If you're running your applications in Docker, you could use Ansible to pull the latest images and restart your applications. + +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 [deploying applications with Ansistrano]({{site.url}}/talks/deploying-php-ansible-ansistrano). + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). + diff --git a/source/_daily_emails/2022-09-07.md b/source/_daily_emails/2022-09-07.md new file mode 100644 index 000000000..ac0dd7143 --- /dev/null +++ b/source/_daily_emails/2022-09-07.md @@ -0,0 +1,30 @@ +--- +title: "My Tailwind CSS origin story" +pubDate: 2022-09-07 +permalink: "archive/2022/09/07/my-tailwind-css-origin-story" +tags: ["tailwind-css"] +--- + +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. + +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. + +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. + +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. + +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). + +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. + +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. + +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. + +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. + +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, [presented a Tailwind CSS talk]({{site.url}}/talks/taking-flight-tailwind-css) at a number of PHP, Drupal, WordPress, and JavaScript events, and maintain [a starter-kit theme](https://www.drupal.org/project/tailwindcss) for using Tailwind in custom Drupal themes. + +I've also rebuilt a [number of existing sites]({{site.url}}/blog/uis-ive-rebuilt-tailwind-css) as examples and written some [Tailwind CSS related blog posts]({{site.url}}/blog/tags/tailwind-css). + +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. diff --git a/source/_daily_emails/2022-09-08.md b/source/_daily_emails/2022-09-08.md new file mode 100644 index 000000000..6b5b933e5 --- /dev/null +++ b/source/_daily_emails/2022-09-08.md @@ -0,0 +1,34 @@ +--- +title: "Keeping secrets with Ansible Vault" +pubDate: 2022-09-08 +permalink: "archive/2022/09/08/keeping-secrets-with-ansible-vault" +tags: ["ansible"] +--- + +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. + +Rather than committing these to a code repository in plain text, Ansible includes the `ansible-vault` command to encrypt values. + +To see this working, run `ansible-vault encrypt_string my-secret-password`, enter a password, and then you should see something like this: + +``` +!vault | + $ANSIBLE_VAULT;1.1;AES256 + 33353031663366313132333831343930643830346531666564363562666136383838343235646661 + 6336326637333230396133393936646636346230623932650a333035303265383437633032326566 + 38616262653933353033376161633961323666366132633033633933653763373539613434333039 + 6132623630643261300a346438636332613963623231623161626133393464643634663735303664 + 66306433633363643561316362663464646139626533323363663337363361633333 +``` + +This is the encrypted version of that password, and this could be committed and pushed to a code repository. + +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. + +Rather than a single string, you could have a file of variables that you want to encrypt. You can do this by running `ansible-vault encrypt vault.yml` and include it as before. Again, you'll be prompted by Ansible so that it can decrypt and use the values. + +For an example of how I'm using Ansible Vault, see [the Dransible repository](https://github.com/opdavies/dransible/tree/986ba5097d62ff4cd0e637d40181bab2c4417f2e/tools/ansible) on GitHub or my [ Deploying PHP applications with Ansible, Ansible Vault and Ansistrano]({{site.url}}/talks/deploying-php-ansible-ansistrano) talk. + +--- + +Want to learn more about how I use Ansible? [Register for my upcoming free email course]({{site.url}}/ansible-course). diff --git a/source/_daily_emails/2022-09-09.md b/source/_daily_emails/2022-09-09.md new file mode 100644 index 000000000..9e0c6990b --- /dev/null +++ b/source/_daily_emails/2022-09-09.md @@ -0,0 +1,20 @@ +--- +title: "Refactoring a Tailwind CSS component" +pubDate: 2022-09-09 +permalink: "archive/2022/09/09/refactoring-tailwind-component" +tags: ["tailwind-css"] +--- + +After last night's Pro Tailwind theming workshop, I decided to revisit and refactor some similar code that I'd worked on before. + +It was a demo for a presentation on utility-first CSS and Tailwind whilst I was at Inviqa. + +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. + +[The original version](https://play.tailwindcss.com/Yfmw8O5UNN) was written in Tailwind 1 and used custom CSS with `@apply` rules to include text or background colours to elements based on the theme being used on that page or component. + +As well as moving it into a Next.js application, [the new version](https://github.com/opdavies/inviqa-tailwindcss-example) 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. + +I also moved the `flex-basis` classes into their own standalone plugin and might release that as it's own open-source plugin. + +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. diff --git a/source/_daily_emails/2022-09-10.md b/source/_daily_emails/2022-09-10.md new file mode 100644 index 000000000..83740c06b --- /dev/null +++ b/source/_daily_emails/2022-09-10.md @@ -0,0 +1,38 @@ +--- +title: "Automating Ansible deployments in CI" +pubDate: 2022-09-10 +permalink: "archive/2022/09/10/automating-ansible-deployments-ci" +tags: ["ansible"] +--- + +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. + +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. + +If you're using Ansistrano or other roles, you can install dependencies by using `ansible-galaxy`, and `ansible-vault` to decrypt and use any encrypted variables - securely storing the Vault password and any other secrets as environment variables within your pipeline. + +Here's an example using GitHub Actions: + +``` +- name: Download Ansible roles + run: ansible-galaxy install -r requirements.yml + +- name: Export the Ansible Vault password + run: echo $ANSIBLE_VAULT_PASS > .vault-pass.txt + env: + ANSIBLE_VAULT_PASS: ${{ secrets.ANSIBLE_VAULT_PASS }} + +- name: Deploy the code + run: > + 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 +``` + +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. + +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. diff --git a/source/_daily_emails/2022-09-11.md b/source/_daily_emails/2022-09-11.md new file mode 100644 index 000000000..81a502efe --- /dev/null +++ b/source/_daily_emails/2022-09-11.md @@ -0,0 +1,62 @@ +--- +title: "Custom styles in Tailwind CSS: `@apply`, `theme` or custom plugins" +pubDate: 2022-09-11 +permalink: "archive/2022/09/11/custom-styles-tailwind-css-apply-theme-custom-plugins" +tags: ["tailwind-css"] +--- + +There are three ways to add custom styles to a Tailwind CSS project. As there have been [some recent tweets](https://twitter.com/adamwathan/status/1559250403547652097) around one of them - the `@apply` directive - I'd like to look at and give examples for each. + +## What is `@apply`? + +`@apply` is a PostCSS directive, provided by Tailwind, to allow re-using it's classes - either when extracting components or overriding third-party styles. + +The CSS file is the same as if you were writing traditional CSS, but rather than adding declarations to a ruleset, you use the `@apply` directive and specify the Tailwind CSS class names that you want to apply. + +For example: + +```css +fieldset { + @apply bg-primary-dark; +} +``` + +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. + +Adam said in a another tweet: + +> I estimate that we spend at least $10,000/month trying to debug extremely edge-case issues people run into by using `@apply` in weird ways. + +## Using the `theme` function + +As well as `@apply`, Tailwind also provides a `theme` 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 `theme` section of your tailwind.config.js file. + +```css +fieldset { + backgroundColor: theme('colors.primary.dark'); +} +``` + +This seems to be the preferred approach over using `@apply`. + +## Creating a custom plugin + +The `theme` function is also available if you write a custom Tailwind CSS plugin: + +```javascript +const plugin = require('tailwindcss/plugin') + +plugin(({ addBase, theme }) => { + addBase({ + fieldset: { + backgroundColor: theme('colors.primary.dark'), + } + }) +}) +``` + +This is an approach that I've used for [generic, open-source plugins](https://github.com/opdavies?tab=repositories&q=%23tailwindcss-plugin) but for project-specific styling, I've mostly used `@apply` or the `theme` function. + +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 `plugins` array. + +I usually don't write many custom styles in a Tailwind project but I think that I'll focus on using the `theme` function going forward, either in a stylesheet or a custom plugin. diff --git a/source/_daily_emails/2022-09-12.md b/source/_daily_emails/2022-09-12.md new file mode 100644 index 000000000..b6a5c8e3d --- /dev/null +++ b/source/_daily_emails/2022-09-12.md @@ -0,0 +1,15 @@ +--- +title: "A month of daily emails" +pubDate: 2022-09-12 +permalink: "archive/2022/09/12/month-daily-emails" +--- + +It’s already been a month since I started my email list and writing daily emails. + +Since then, I’ve written emails on various development and workflow-based topics, including Drupal, Git, Docker, Neovim, Ansible and Tailwind CSS. + +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. + +I can confirm what [Jonathan Stark](https://jonathanstark.com) and [Jonathan Hall](https://jhall.io) 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. + +If you're considering starting a daily email list, I'd recommend it. diff --git a/source/_daily_emails/2022-09-14.md b/source/_daily_emails/2022-09-14.md new file mode 100644 index 000000000..617b9cb88 --- /dev/null +++ b/source/_daily_emails/2022-09-14.md @@ -0,0 +1,67 @@ +--- +title: "The simplest Drupal test" +pubDate: 2022-09-14 +permalink: "archive/2022/09/14/simpletest-drupal-test" +--- + +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. + +I cloned a fresh version of my [Docker Examples repository](https://github.com/opdavies/docker-examples) and started the Drupal example. + +I ran `mkdir -p web/modules/custom/example/tests/src/Functional` to create the directory structure that I needed, and then `touch web/modules/custom/example/tests/src/Functional/ExampleTest.php` to create a new test file and populated it with some initial code: + +```php +drupalGet(''); + + $this->assertSession()->statusCodeEquals(Response::HTTP_OK); +} +``` + +To execute the test, I ran `SIMPLETEST_DB=sqlite://localhost//dev/shm/test.sqlite SIMPLETEST_BASE_URL=http://web phpunit -c web/core web/modules/custom`. The environment variables could be added to a `phpunit.xml.dist` file but I decided to add them to the command and use Drupal core's PHPUnit configuration file. + +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. + +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: + +```php +/** @test */ +public function the_admin_page_is_not_accessible_to_anonymous_users() { + $this->drupalGet('admin'); + + $this->assertSession()->statusCodeEquals(Response::HTTP_FORBIDDEN); +} + +/** @test */ +public function the_admin_page_is_accessible_by_admin_users() { + $adminUser = $this->createUser([ + 'access administration pages', + ]); + + $this->drupalLogin($adminUser); + + $this->drupalGet('admin'); + + $this->assertSession()->statusCodeEquals(Response::HTTP_OK); +} +``` + +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 [Test-Driven Drupal talk]({{site.url}}/talks/tdd-test-driven-drupal) are online. diff --git a/source/_daily_emails/2022-09-16.md b/source/_daily_emails/2022-09-16.md new file mode 100644 index 000000000..4048b26ae --- /dev/null +++ b/source/_daily_emails/2022-09-16.md @@ -0,0 +1,111 @@ +--- +title: "Why I mostly write functional and integration tests" +pubDate: 2022-09-16 +permalink: "archive/2022/09/16/why-mostly-write-functional-and-integration-tests" +tags: ["drupal"] +--- + +In [Wednesday's email]({{site.url}}/archive/2022/09/14/simpletest-drupal-test), I showed how quick it is to get started writing automated tests for a new Drupal module, starting with a functional test. + +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’ll use a functional test. If not, I’ll use a kernel (or integration) test. + +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. + +## An example + +For example, this `Device` class which is a data transfer object around Drupal's `NodeInterface`. 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: + +```php +final class Device { + + private NodeInterface $node; + + public function __construct(NodeInterface $node) { + if ($node->bundle() != 'device') { + throw new \InvalidArgumentException(); + } + + $this->node = $node; + } + + public function getAssetId(): string { + return $this->node->get('field_asset_id')->getString(); + } + + public static function fromNode(NodeInterface $node): self { + return new self($node); + } + +} +``` + +## Testing getting the asset ID using a unit test + +As the `Node::create()` 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. + +I need to specify what value is returned from the `bundle()` method as well as getting the asset ID field value. + +I need to mock the `get()` method and specify the field name that I'm getting the value for, which also returns it's own mock for `FieldItemListInterface` with a value set for the `getString()` method. + +```php +/** @test */ +public function should_return_an_asset_id(): void { + // Arrange. + $fieldItemList = $this->createMock(FieldItemListInterface::class); + + $fieldItemList + ->method('getString') + ->willReturn('ABC'); + + $deviceNode = $this->createMock(NodeInterface::class); + + $deviceNode + ->method('bundle') + ->willReturn('device'); + + $deviceNode + ->method('get') + ->with('field_asset_id') + ->willReturn($fieldItemList); + + // Act. + $device = Device::fromNode($deviceNode); + + // Assert. + self::assertSame('ABC', $device->getAssetId()); +} +``` + +This is quite a long 'arrange' section for this test, and just be confusing for those new to automated testing. + +If I was to refactor from using the `get()` and `getString()` methods to a different implementation, it's likely that the test would fail. + +## Refactoring to a kernel test + +This is how I could write the same test using a kernel (integration) test: + +```php +/** @test */ +public function should_return_an_asset_id(): void { + // Arrange. + $node = Node::create([ + 'field_asset_id' => 'ABC', + 'type' => 'device' + ]); + + // Assert. + self::assertSame('ABC', Device::fromNode($node)->getAssetId()); +} +``` + +I can create a real `Node` object, pass that to the `Device` DTO, and call the `getAssetId()` method. + +As I can interact with the database, there's no need to create mocks or define return values. + +The 'arrange' step is much smaller, and I think that this is easier to read and understand. + +### Trade-offs + +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. + +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. diff --git a/source/_daily_emails/2022-09-17.md b/source/_daily_emails/2022-09-17.md new file mode 100644 index 000000000..beb78de05 --- /dev/null +++ b/source/_daily_emails/2022-09-17.md @@ -0,0 +1,21 @@ +--- +title: "Thoughts on automated code formatting" +pubDate: 2022-09-17 +permalink: "archive/2022/09/17/thoughts-automated-code-formatting" +--- + +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. + +Complying with the standards though is something that I've done manually. + +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. + +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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-09-19.md b/source/_daily_emails/2022-09-19.md new file mode 100644 index 000000000..5ffa47a14 --- /dev/null +++ b/source/_daily_emails/2022-09-19.md @@ -0,0 +1,26 @@ +--- +title: "Useful Git configuration" +pubDate: 2022-09-19 +permalink: "archive/2022/09/19/useful-git-configuration" +tags: ["git"] +--- + +Here are some snippets from my Git configuration file. + +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. + +`branch.autosetuprebase = always` and `pull.rebase = true` configure Git to always rebase instead of pull. It does this for all branches, though I might override this for `main` branches. + +`pull.ff = only` and `merge.ff = only` 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 `--no-ff` option on the command line. + +I use `checkout.defaultRemote = origin` to ensure that the `origin` remote is used if I have multiple remotes configured, and `push.default = upstream` to set the default remote to push to. + +`merge.autoStash` allows for running merges on a dirty worktree by automatically creating and re-applying a stash of the changes, and `fetch.prune` will automatically prune branches on fetch - keeping things tidy. + +I also have and use a number of aliases. + +Some like `pl = pull` and `ps = push` are shorter versions of existing commands, and some like `aa = add --all`, `fixup = commit --fixup` and some additional arguments to commands. + +I also have some like `current-branch = rev-parse --abbrev-ref HEAD` and `worktrees = worktree list` which add simple additional commands, and some like `repush = !git pull --rebase && git push` which use execute shell commands to execute more complex commands or combine multiple commands. + +This is a snapshot of my Git configuration. The [full version is on GitHub](https://github.com/opdavies/dotfiles/blob/7e935b12c09358adad480a566988b9cbfaf5999e/roles/git/files/.gitconfig). diff --git a/source/_daily_emails/2022-09-20.md b/source/_daily_emails/2022-09-20.md new file mode 100644 index 000000000..035b9672e --- /dev/null +++ b/source/_daily_emails/2022-09-20.md @@ -0,0 +1,26 @@ +--- +title: "Why I like trunk-based development" +pubDate: 2022-09-20 +permalink: "archive/2022/09/20/why-like-trunk-based-development" +tags: ["git"] +--- + +For the majority of my software development career, I've worked with version control in a very similar way. + +There are one or two long-lived branches, usually a combination of `develop`, `master` or `main`, 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". + +Whilst those changes are awaiting review, a new task is started and the process is repeated. + +## Trunk-based development + +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. + +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. + +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. + +There are still occassions when a temporary branch is needed, but in general, all changes are made to the single branch. + +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. + +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. diff --git a/source/_daily_emails/2022-09-21.md b/source/_daily_emails/2022-09-21.md new file mode 100644 index 000000000..2dae3e4ea --- /dev/null +++ b/source/_daily_emails/2022-09-21.md @@ -0,0 +1,34 @@ +--- +title: "Being a Drupal contribution mentor" +pubDate: 2022-09-21 +permalink: "archive/2022/09/21/being-drupal-contribution-mentor" +tags: ["drupal"] +--- + +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. + +## My first DrupalCon + +The first DrupalCon that I attended was in 2013, also in Prague. + +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. + +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. + +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. + +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. + +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! + +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. + +## The Five Year Issue + +One of the most memorable times mentoring was whilst working with a group of contributors at DrupalCon in May 2015. + +Someone was working on a Drupal core issue that was very similar to [one that I'd looked at](https://www.drupal.org/project/drupal/issues/753898) a few years before. + +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". + +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 [one of mine](https://git.drupalcode.org/project/drupal/-/commits/9.5.x?search=opdavies). diff --git a/source/_daily_emails/2022-09-22.md b/source/_daily_emails/2022-09-22.md new file mode 100644 index 000000000..83a0df2e7 --- /dev/null +++ b/source/_daily_emails/2022-09-22.md @@ -0,0 +1,20 @@ +--- +title: "Releasing a Drupal module template" +pubDate: 2022-09-22 +permalink: "archive/2022/09/22/releasing-drupal-module-template" +tags: ["drupal"] +--- + +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. + +So I did, and released it for free [on my GitHub account](https://github.com/opdavies/drupal-module-template). + +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. + +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. + +The Controller is defined as a service and uses autowiring to automatically inject the its dependencies, the same as in my workshop example code. + +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. + +If you're creating a new Drupal module and try it out, start a discussion on the GitHub repository or [let me know on Twitter](https://twitter.com/opdavies). If you have questions, create a discussion or just reply to this email and I'll get back to you. diff --git a/source/_daily_emails/2022-09-23.md b/source/_daily_emails/2022-09-23.md new file mode 100644 index 000000000..e490fd24e --- /dev/null +++ b/source/_daily_emails/2022-09-23.md @@ -0,0 +1,44 @@ +--- +title: "ADRs and Technical Design Documents" +pubDate: 2022-09-23 +permalink: "archive/2022/09/23/adrs-technical-design-documents" +tags: [] +--- + +## Architectural Decision Records + +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. + +They usually consist of the sections: + +* Status - is it proposed, accepted, rejected, deprecated, superseded, etc.? +* Context - what is the issue that is causing the decision or change? +* Decision - what is the change that's being done or proposed? +* Consequences - what becomes easier or more difficult to do? + +Any change that is architecturally significant should require an ADR to be written, after which it can be reviewed and potentially actioned. + +These will remain in place to form a decision log, with specific ADRs being marked as superseded if a newer ADR replaces it. + +## Technical Design Documents + +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. + +The first heading is always "What problem are we trying to solve?", or sometimes just "The problem". + +Similar to the Context heading in an ADR, this should include a short paragraph describing the issue. + +Unlike ADRs, there are no other set headings but these are some suggested ones: + +- What is the current process? +- What are any requirements? +- How do we solve this problem? +- Alternative approaches + +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. + +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. + +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. + +[Find our more about ADRs](https://adr.github.io) or [find out more about TDDs](https://altf4.wiki/t/how-do-i-write-a-tdd/21). diff --git a/source/_daily_emails/2022-09-25.md b/source/_daily_emails/2022-09-25.md new file mode 100644 index 000000000..50cc987dc --- /dev/null +++ b/source/_daily_emails/2022-09-25.md @@ -0,0 +1,28 @@ +--- +title: "Using a component library for front-end development" +pubDate: 2022-09-25 +permalink: "archive/2022/09/25/using-component-library-for-front-end-development" +tags: [] +--- + +On a current project, I've decided to use a component library as the first place to do front-end development. + +I'm using [Fractal](https://fractal.build) 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. + +Rather than developing directly within the custom Drupal theme, I've been creating new components and pages initially within Fractal. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-09-26.md b/source/_daily_emails/2022-09-26.md new file mode 100644 index 000000000..894a31cb0 --- /dev/null +++ b/source/_daily_emails/2022-09-26.md @@ -0,0 +1,20 @@ +--- +title: "Experimenting with the Nix package manager" +pubDate: 2022-09-26 +permalink: "archive/2022/09/26/experimenting-with-the-nix-package-manager" +tags: ["nix"] +--- + +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. + +Separate from the NixOS operating system, Nix is a cross-platform package manager, so instead of using `apt` on Ubuntu and `brew` on macOS, you could run Nix on both and install from the 80,000 packages listed on https://search.nixos.org/packages. + +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. + +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!\_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. + +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. + +I have a work-in-progress Nix-based version [in my dotfiles repository](https://github.com/opdavies/dotfiles/tree/7c3436c553f8b81f99031e6bcddf385d47b7e785) where you can also see [how I've configured Git with Home Manager](https://github.com/opdavies/dotfiles/blob/7c3436c553f8b81f99031e6bcddf385d47b7e785/home-manager/modules/git.nix). + +I may install NixOS on an old laptop to test that out too. diff --git a/source/_daily_emails/2022-09-27.md b/source/_daily_emails/2022-09-27.md new file mode 100644 index 000000000..6dc063fa1 --- /dev/null +++ b/source/_daily_emails/2022-09-27.md @@ -0,0 +1,16 @@ +--- +title: "Mentoring with Drupal Career Online" +pubDate: 2022-09-27 +permalink: "archive/2022/09/27/mentoring-with-drupal-career-online" +tags: ["drupal"] +--- + +Today, I met my new mentee from the Drupal Career Online program. + +[As well as mentoring at events like DrupalCamps and DrupalCons]({{site.url}}/archive/2022/09/21/being-drupal-contribution-mentor), 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. + +I've talked about [how I got started programming]({{site.url}}/archive/2022-08-28/how-started-programming), 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. + +Maybe this is more applicable these days with more people learning and working from home since COVID-19? + +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. diff --git a/source/_daily_emails/2022-09-28.md b/source/_daily_emails/2022-09-28.md new file mode 100644 index 000000000..dfe1dbe0a --- /dev/null +++ b/source/_daily_emails/2022-09-28.md @@ -0,0 +1,20 @@ +--- +title: "Mob programming at PHP South Wales" +pubDate: 2022-09-28 +permalink: "archive/2022/09/28/mob-programming-php-south-wales" +tags: [] +--- + +Tonight was our September meetup for the PHP South Wales user group, where I ran a hands-on session on mob programming. + +I created [a small slide deck](https://speakerdeck.com/opdavies/an-introduction-to-mob-programming) before we started a mob session with the group. + +We worked on the FizzBuzz kata in PHP, using Pest for our automated tests. + +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. + +You can [see the code that we wrote](https://github.com/opdavies/code-katas/blob/1da5dd5a79bc7ca083c0c4216fc3b4b0854f623d/php/tests/FizzBuzzTest.php) on my code katas GitHub repository. + +It was a fun experience and nice to code with some people who I hadn't coded with before. + +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. diff --git a/source/_daily_emails/2022-09-30.md b/source/_daily_emails/2022-09-30.md new file mode 100644 index 000000000..85ccb1151 --- /dev/null +++ b/source/_daily_emails/2022-09-30.md @@ -0,0 +1,83 @@ +--- +title: "Store Wars: different state management in Vue.js" +pubDate: 2022-09-30 +permalink: "archive/2022/09/30/store-wars-vuejs" +tags: ["vue"] +--- + +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. + +In the original version, I was using Vuex for state management within the application, and interacting with Vuex directly within my Vue components - calling `getters` and `dispatch` to retrieve and update data. + +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. + +But because I was integrating with Vuex directly, switching to an alternative would mean changing code within my components. + +## Defining a Store interface + +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. + +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. + +This is what I did by adding a `Store` interface: + +```javascript +export default interface Store { + actions: { + addRow(): void; + init(): void; + removeRow(index: Number): void; + }; + + state: { + isLoading: boolean; + selection: { + items: []; + }; + }; +} +``` + +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. + +## Creating a native Vue store + +This is one implementation of the `Store` interface, using just Vue's `reactive` function from the Composition API: + +```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; +``` + +If I needed to add a Pinia version or another library, I can create another implementation that complies with same interface. + +Each implementation being responsible for any specifics for that library - extracting that logic from the component code making it more flexible and reusable. diff --git a/source/_daily_emails/2022-10-01.md b/source/_daily_emails/2022-10-01.md new file mode 100644 index 000000000..da21b82ea --- /dev/null +++ b/source/_daily_emails/2022-10-01.md @@ -0,0 +1,34 @@ +--- +title: Why do code katas? +pubDate: 2022-10-01 +permalink: archive/2022/10/01/code-katas +tags: [] +--- + +## What are code katas? + +Code katas are programming exercises which, like katas in martial arts, use practice and repetition to improve your skills. + +Common katas are Fizzbuzz, the Bowling score calculator, and the Gilded Rose. + +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. + +Once you have completed the solution and the criteria is satisfied, the kata is complete. + +## Why I do code katas + +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. + +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. + +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. + +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. + +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. + +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.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. + +I have [some GitHub repositories for my code kata solutions](https://github.com/opdavies?tab=repositories&q=katas) and will continue to build these as I do more. diff --git a/source/_daily_emails/2022-10-02.md b/source/_daily_emails/2022-10-02.md new file mode 100644 index 000000000..e24f3050d --- /dev/null +++ b/source/_daily_emails/2022-10-02.md @@ -0,0 +1,32 @@ +--- +title: Minimum viable CI pipelines +pubDate: 2022-10-02 +permalink: archive/2022/10/02/minimum-viable-pipelines +tags: [] +--- + +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. + +In that case, where should you start when adding a CI pipeline? + +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. + +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 `docker image build` or `docker compose build`. + +Having a task that ensures the project builds correctly is a great next step. + +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. + +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. + +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. + +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. + +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. + +If there is a failure that wasn't caught in the CI pipeline, then the pipeline itself should be iterated on and improved. + +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. + +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. diff --git a/source/_daily_emails/2022-10-03.md b/source/_daily_emails/2022-10-03.md new file mode 100644 index 000000000..82be5b659 --- /dev/null +++ b/source/_daily_emails/2022-10-03.md @@ -0,0 +1,75 @@ +--- +title: Refactoring to value objects +pubDate: 2022-10-03 +permalink: archive/2022/10/03/refactoring-value-objects +tags: [php] +--- + + +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. + +```php +return Collection::make($stationNodes) + ->map(fn (NodeInterface $station): string => $station->get('field_station_code')->getString()) + ->values(); +``` + +There are two issues with this code. + +First, whilst I'm implicitly saying that it accepts a certain type of node, because of the `NodeInterface` 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. + +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. + +## Introducing a value object + +This is the value object that I created. + +It accepts the original node but checks to ensure that the node is the correct type. If not, an Exception is thrown. + +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. + +```php +namespace Drupal\mymodule\ValueObject; + +use Drupal\node\NodeInterface; + +final class Station implements StationInterface { + + private NodeInterface $node; + + private function __construct(NodeInterface $node) { + if ($node->bundle() != 'station') { + throw new \InvalidArgumentException(); + } + + $this->node = $node; + } + + public function getStationCode(): string { + return $this->node->get('field_station_code')->getString(); + } + + public static function fromNode(NodeInterface $node): self { + return new self($node); + } + +} +``` + +## Refactoring to use the value object + +This is what my code now looks like: + +```php +return Collection::make($stationNodes) + ->map(fn (NodeInterface $node): StationInterface => Station::fromNode($node)) + ->map(fn (StationInterface $station): string => $station->getStationCode()) + ->values(); +``` +<<<<<<< HEAD:website/source/_daily_emails/2022-10-03.md +======= + +>>>>>>> b9cea6d (chore: replace Sculpin with Astro):website/src/pages/daily-emails/2022-10-03.md +I've added an additional `map` 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. + +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. diff --git a/source/_daily_emails/2022-10-08.md b/source/_daily_emails/2022-10-08.md new file mode 100644 index 000000000..a74f15bff --- /dev/null +++ b/source/_daily_emails/2022-10-08.md @@ -0,0 +1,20 @@ +--- +title: First impressions of Astro +pubDate: 2022-10-08 +permalink: archive/2022/10/08/first-impressions-astro +tags: [astro] +--- + +This week I attended another of Simon Vrachliotis' Pro Tailwind workshops. + +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. + +For this workshop though, the examples and challenges used a tool that I wasn't familiar with - the Astro web framework. + +I've seen a lot of blog posts and streams mentioning it but I hadn't tried it out for myself until the workshop. + +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 `yarn astro add tailwindcss`. + +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. + +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. diff --git a/source/_daily_emails/2022-10-09.md b/source/_daily_emails/2022-10-09.md new file mode 100644 index 000000000..8be3f91de --- /dev/null +++ b/source/_daily_emails/2022-10-09.md @@ -0,0 +1,52 @@ +--- +title: Coding defensively, and Implicit vs explicit coding +pubDate: 2022-10-09 +permalink: archive/2022/10/09/coding-defensively-implicit-explicit +tags: [tailwindcss, php] +--- + +As well as [being introduced to Astro](https://www.oliverdavies.uk/archive/2022/10/08/first-impressions-astro) in Simon's most recent Pro Tailwind workshop, something else that we discussed was implicit vs explicit coding, and coding defensively. + +For example, if you had this code: + +```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', +} +``` + +Both the `medium` size and `square` shape have an implicit value. + +The `small` size has a text size class of `text-sm` and the `large` size has `text-lg`. As there isn't a text size added for `medium`, it is implicitly `text-base` - the default text size. + +Likewise, the `rounded` shape has a class of `rounded` and the `pill` shape has `rounded-full`. As a square button doesn't have any rounding, it has an empty string but it is implicitly `rounded-none` - the default border radius value. + +If we were to code this explicitly, `text-base` and `rounded-none` would be added to their respective size and shape classes. + +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. + +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. + +It's similar to having this example PHP code: + +```php +function __invoke(string $type, int $limit): void {}; +``` + +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? + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-10-10.md b/source/_daily_emails/2022-10-10.md new file mode 100644 index 000000000..064ba84a0 --- /dev/null +++ b/source/_daily_emails/2022-10-10.md @@ -0,0 +1,14 @@ +--- +title: Contributing to open-source software, one small change at a time +pubDate: 2022-10-10 +permalink: archive/2022/10/10/contributing-open-source-software-one-small-change-time +tags: [open-source] +--- + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-10-11.md b/source/_daily_emails/2022-10-11.md new file mode 100644 index 000000000..2c6a4e17c --- /dev/null +++ b/source/_daily_emails/2022-10-11.md @@ -0,0 +1,18 @@ +--- +title: Not long until Drupal 10 +pubDate: 2022-10-11 +permalink: archive/2022/10/11/not-long-until-drupal-10 +tags: [drupal, php] +--- + +I was surprised to see this week that it’s only two months until Drupal 10 is released (14th December 2022). + +I’m starting a new Drupal development project in December so will be looking to get that on Drupal 10 as soon as possible. + +From the client’s 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. + +As a module maintainer, it’s been great to again see issues being created with automated Drupal 10 compatibility patches - thanks to Rector. + +It’s 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. + +It’s 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. diff --git a/source/_daily_emails/2022-10-12.md b/source/_daily_emails/2022-10-12.md new file mode 100644 index 000000000..ce9691503 --- /dev/null +++ b/source/_daily_emails/2022-10-12.md @@ -0,0 +1,28 @@ +--- +title: Overcoming deployment anxiety +pubDate: 2022-10-12 +permalink: 'archive/2022/10/12/overcoming-deployment-anxiety' +--- + +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. + +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: + +* 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. +* It's been a long time, maybe weeks or months, since the last production release. + +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. + +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. + +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. + +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. + +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. + +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. + +In my [Deployments with Ansible and Ansistrano talk](https://www.oliverdavies.uk/talks/deploying-php-ansible-ansistrano), I mention that there is a separate rollback role, but I don't think that I've ever used it. + +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. diff --git a/source/_daily_emails/2022-10-17.md b/source/_daily_emails/2022-10-17.md new file mode 100644 index 000000000..33c12d6cb --- /dev/null +++ b/source/_daily_emails/2022-10-17.md @@ -0,0 +1,17 @@ +--- +title: 14 years on Drupal.org and working with PHP and Drupal +pubDate: 2022-10-17 +permalink: 'archive/2022/10/17/14-years-drupalorg' +--- + +Today I saw that my Drupal.org profile is showing that I’ve been on that website for 14 years. + +![A screenshot of my Drupal.org profile showing "On Drupal.org for 14 years 1 hour".](/images/14-drupalorg.jpg) + +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’s been where I’ve uploaded and maintain my own contributed projects and contribute patches to others, including Drupal core. + +I even spent time working for the Drupal Association on Drupal.org itself. + +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. + +With Drupal 10 just around the corner, I'm looking forward to seeing how Drupal continues to evolve and develop. diff --git a/source/_daily_emails/2022-10-18.md b/source/_daily_emails/2022-10-18.md new file mode 100644 index 000000000..b25da30ff --- /dev/null +++ b/source/_daily_emails/2022-10-18.md @@ -0,0 +1,19 @@ +--- +title: Pair and mob programming +pubDate: 2022-10-18 +permalink: 'archive/2022/10/18/pair-mob-programming' +--- + +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. + +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 [technical design document](https://www.oliverdavies.uk/archive/2022/09/23/adrs-technical-design-documents) before moving on to the implementation. + +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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-10-19.md b/source/_daily_emails/2022-10-19.md new file mode 100644 index 000000000..785a3b420 --- /dev/null +++ b/source/_daily_emails/2022-10-19.md @@ -0,0 +1,23 @@ +--- +title: run file vs task runners +pubDate: 2022-10-19 +permalink: archive/2022/10/19/run-vs-task-runners +# tags: +# - +--- + +[I've written a few earlier emails](https://www.oliverdavies.uk/archive/2022/08/15/using-run-file-simplify-project-tasks) about `run` files - a simple bash file that I add to my projects to simplify or combine common commands that I need to run often. + +Recently, I've looked at a couple of alternatives to see how they compare. + +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 `.PHONY`. + +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 `run` file. + +The main reason for this is that I like the simplicity of the `run` file, and that it's just a Bash file that contains functions. + +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 `run` 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. + +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. + +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 `run` files. diff --git a/source/_daily_emails/2022-10-20.md b/source/_daily_emails/2022-10-20.md new file mode 100644 index 000000000..3bd4a8417 --- /dev/null +++ b/source/_daily_emails/2022-10-20.md @@ -0,0 +1,27 @@ +--- +title: > + Cherry picking commits is an anti-pattern +pubDate: 2022-10-20 +permalink: >- + archive/2022/10/20/cherry-picking-commits-is-an-anti-pattern +tags: + - git +--- + +`git cherry-pick` 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. + +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 `develop` onto a feature branch rather than merging or rebasing, or to re-apply a hotfix from the `main` branch. + +The main issue that I've seen with `cherry-pick` 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. + +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. + +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. + +A good automated test suite would help, ensuring that the tests still pass once the cherry picking is done. + +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. + +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. + +These are the use-cases that I can think of or have seen for `git cherry-pick`. If you know of any others or use `cherry-pick` in your workflow in another way, reply to the email and let me know. diff --git a/source/_daily_emails/2022-10-21.md b/source/_daily_emails/2022-10-21.md new file mode 100644 index 000000000..378ac054c --- /dev/null +++ b/source/_daily_emails/2022-10-21.md @@ -0,0 +1,23 @@ +--- +title: > + Automated testing and test-driven development are not the same +pubDate: 2022-10-21 +permalink: >- + archive/2022/10/21/automated-testing-and-test-driven-development-are-not-the-same +tags: + - testing +--- + +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. + +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. + +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. + +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. + +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. + +If you don't write the tests first, you may be tempted to skip writing them completely, leaving untested code or adding `TODO: add test` comments that may never get reviewed. + +Also, where's the fun in writing tests for code that you've already written, that you know are going to pass? diff --git a/source/_daily_emails/2022-10-24.md b/source/_daily_emails/2022-10-24.md new file mode 100644 index 000000000..7e1c2d26f --- /dev/null +++ b/source/_daily_emails/2022-10-24.md @@ -0,0 +1,21 @@ +--- +title: > + Looking at LocalGov Drupal +pubDate: 2022-10-24 +permalink: >- + archive/2022/10/24/looking-at-localgov-drupal +tags: + - drupal +--- + +Today, I've been looking at [LocalGov](https://localgovdrupal.org) - a Drupal distribution for building council websites, with a focus on code reuse and collaboration. + +After a few small changes, I was able to get it running based on my [Docker Examples](https://github.com/opdavies/docker-examples) repository. + +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. + +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. + +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 [LocalGov issue queue on Drupal.org](https://www.drupal.org/project/localgov/issues/3307516#comment-14759989) by answering a support request, and after spotting a potential issue within the alert banner styling, [submitted a pull request with a fix](https://github.com/localgovdrupal/localgov_alert_banner/pull/225). + +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. diff --git a/source/_daily_emails/2022-10-25.md b/source/_daily_emails/2022-10-25.md new file mode 100644 index 000000000..738a677cf --- /dev/null +++ b/source/_daily_emails/2022-10-25.md @@ -0,0 +1,25 @@ +--- +title: > + What are Drupal distributions? +pubDate: 2022-10-25 +permalink: >- + archive/2022/10/25/what-are-drupal-distributions +tags: + - drupal +--- + +Yesterday's email was about the LocalGov Drupal distribution that I've been looking at, but I glossed over what a Drupal distribution is. + +It's an interesting topic for me, having [written an article for Linux Journal](https://www.linuxjournal.com/content/speed-your-drupal-development-using-installations-and-distributions) about it in 2012. + +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. + +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. + +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. + +A few months ago, I started developing a distribution for managing meetup group websites, like PHP South Wales. + +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. + +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. diff --git a/source/_daily_emails/2022-10-26.md b/source/_daily_emails/2022-10-26.md new file mode 100644 index 000000000..c4314cd9c --- /dev/null +++ b/source/_daily_emails/2022-10-26.md @@ -0,0 +1,26 @@ +--- +title: > + Neovim as a Personalised Development Environment +pubDate: 2022-10-26 +permalink: >- + archive/2022/10/26/neovim-as-a-personalised-development-environment +tags: + - neovim +--- + +A few months ago, TJ DeVries (a Neovim core team member) coined the phrase "Personalised Development Environment" or PDE. + +[I've been using Neovim full-time](https://www.oliverdavies.uk/blog/going-full-vim) 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. + + +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. + +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. + +Recently, I found and added plugins that added a [HTTP client](https://github.com/rest-nvim/rest.nvim) and a [database connection manager](https://github.com/kristijanhusak/vim-dadbod-ui) to Neovim - two pieces of functionality that I'd used in other IDEs or separate applications. + +I also [wrote my own Neovim plugin](https://github.com/opdavies/toggle-checkbox.nvim) for toggling checkboxes within Markdown lists. + +Like Drupal and other open-source solutions that I use, I love being able to add or edit functionality as needed. + +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). diff --git a/source/_daily_emails/2022-10-27.md b/source/_daily_emails/2022-10-27.md new file mode 100644 index 000000000..028789100 --- /dev/null +++ b/source/_daily_emails/2022-10-27.md @@ -0,0 +1,17 @@ +--- +title: > + Getting back into live streaming +pubDate: 2022-10-27 +permalink: >- + archive/2022/10/27/getting-back-into-live-streaming +--- + +Surprisingly, it's been two and a half years since I last did a live coding stream. + +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. + +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. + +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. + +I'll be streaming again on my YouTube channel, so if you'd like to be notified when I do, [please subscribe](https://www.youtube.com/channel/UCkeK0qF9HHUPQH_fvn4ghqQ?sub_confirmation=1). diff --git a/source/_daily_emails/2022-10-28.md b/source/_daily_emails/2022-10-28.md new file mode 100644 index 000000000..3879b65b8 --- /dev/null +++ b/source/_daily_emails/2022-10-28.md @@ -0,0 +1,25 @@ +--- +title: > + Why write framework agnostic packages? +pubDate: 2022-10-28 +permalink: >- + archive/2022/10/28/why-write-framework-agnostic-packages +tags: + - php +--- + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-10-29.md b/source/_daily_emails/2022-10-29.md new file mode 100644 index 000000000..8141ed2ee --- /dev/null +++ b/source/_daily_emails/2022-10-29.md @@ -0,0 +1,25 @@ +--- +title: > + The open-source-first development workflow +pubDate: 2022-10-29 +permalink: >- + archive/2022/10/29/the-open-source-first-development-workflow +tags: + - open-source +--- + +Yesterday's email talked about [writing reusable, framework-agnostic packages](https://www.oliverdavies.uk/archive/2022/10/28/why-write-framework-agnostic-packages) but didn't mention where those packages could be located. + +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. + +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. + +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. + +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. + +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. + +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 [Private Message Queue](https://www.drupal.org/project/private_message_queue), [System User](https://www.drupal.org/project/system_user), and [Null User](https://www.drupal.org/project/null_user) 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. + +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. diff --git a/source/_daily_emails/2022-10-30.md b/source/_daily_emails/2022-10-30.md new file mode 100644 index 000000000..658bdb673 --- /dev/null +++ b/source/_daily_emails/2022-10-30.md @@ -0,0 +1,45 @@ +--- +title: > + Refactoring one large test into multiple smaller tests +pubDate: 2022-10-30 +permalink: >- + archive/2022/10/30/refactoring-one-large-test-into-multiple-smaller-tests +tags: + - php + - phpunit +--- + +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. + +So, why did I do this? + +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". + +But it did much more than that: + +1. It asserted that there are no initial existing products or product variations. +1. It ran a product import using some stub data. +1. It asserted that there are two products, each with two variations. +1. It asserted that each product has the correct title. +1. It asserted that each product variation has the correct title. +1. It asserted that each variation has the correct SKU. +1. It asserted that each variation has the correct price. +1. It asserted that each variation has the correct value for 10 product attributes. + +All of this was hidden within a single test. + +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. + +This refactoring task was to split the remaining assertions into their own named tests, after which I had six different tests. + +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. + +If an assertion fails, I can easily see in which test the failure occurred. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-11-08.md b/source/_daily_emails/2022-11-08.md new file mode 100644 index 000000000..58fe6863c --- /dev/null +++ b/source/_daily_emails/2022-11-08.md @@ -0,0 +1,26 @@ +--- +title: > + Are sprints incompatible with Continuous Deployment? +pubDate: 2022-11-08 +permalink: >- + archive/2022/11/08/are-sprints-incompatible-with-continuous-deployment +# tags: +# - a +# - b +--- + +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. + +In my experience, those changes are usually released at the end of that cycle. But it seems that's not always the case; see [release sprints](https://scrumdictionary.com/term/release-sprint): + +> 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. + +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? + +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? + +Does the release cycle need to be tightly coupled to the sprint cycle or can they be separate and independent of each other? + +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? + +This is something that I'm going to continue to experiment with, iterate on, and learn more about going forward. diff --git a/source/_daily_emails/2022-11-09.md b/source/_daily_emails/2022-11-09.md new file mode 100644 index 000000000..7338a3118 --- /dev/null +++ b/source/_daily_emails/2022-11-09.md @@ -0,0 +1,15 @@ +--- +title: > + Your conference talk has been accepted +pubDate: 2022-11-09 +permalink: >- + archive/2022/11/09/your-conference-talk-has-been-accepted +--- + +I’m happy to have had a conference talk proposal accepted for what will be my first in-person conference since DrupalCamp London in February 2020. + +I’ll be giving my "[Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css)" talk for the first time since February 2021, and in front of an in-person audience since June 2019. + +The talk itself will need some updating. The last time I gave it, Tailwind CSS was on version 2.0.3. It’s 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. + +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. diff --git a/source/_daily_emails/2022-11-11.md b/source/_daily_emails/2022-11-11.md new file mode 100644 index 000000000..f13a36638 --- /dev/null +++ b/source/_daily_emails/2022-11-11.md @@ -0,0 +1,28 @@ +--- +title: > + Creating a small proof-of-concept application in an afternoon +pubDate: 2022-11-11 +permalink: >- + archive/2022/11/12/creating-small-proof-of-concept-application-afternoon +# tags: +# - a +# - b +--- + +This morning, I was asked a “Could you build…” question. + +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. + +I’d 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. + +This afternoon, I built a small proof-of-concept application with Vue.js and TypeScript. + +There’s 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. + +The results are shown by adding a `
{{ results }}
` to the page, with a `
{{ state.selection }}
` to show the input data. + +There isn’t even any styling, with just some basic horizontal rules to split the page - similar to [these screenshots from Taylor Otwell](https://twitter.com/taylorotwell/status/1203356860818087944) of some work-in-progress versions of Vapor and Nova. + +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. + +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. diff --git a/source/_daily_emails/2022-11-12.md b/source/_daily_emails/2022-11-12.md new file mode 100644 index 000000000..4a49796cf --- /dev/null +++ b/source/_daily_emails/2022-11-12.md @@ -0,0 +1,26 @@ +--- +title: > + Building a minimum viable product and managing technical debt +pubDate: 2022-11-12 +permalink: >- + archive/2022/11/12/building-a-minimum-viable-product-and-managing-technical-debt +# tags: +# - a +# - b +--- + +Yesterday's email was about a proof-of-concept application that I’d quickly built to validate an idea and explore some initial approaches. + +Today, I’ve been working on a client project that I’ve improved and maintained for a few years. + +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’s multi-site functionality. + +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). + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-11-13.md b/source/_daily_emails/2022-11-13.md new file mode 100644 index 000000000..2887c033f --- /dev/null +++ b/source/_daily_emails/2022-11-13.md @@ -0,0 +1,23 @@ +--- +title: > + How I manage multiple Drupal websites using the same codebase +pubDate: 2022-11-13 +permalink: >- + archive/2022/11/13/how-i-manage-multiple-drupal-websites-using-the-same-codebase +tags: + - drupal +--- + +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? + +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. + +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. + +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 [Feature toggle](https://www.drupal.org/project/feature_toggle) or another way like a checkbox on a settings form. Anything that I can use to say "Do this if that is enabled". + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-11-14.md b/source/_daily_emails/2022-11-14.md new file mode 100644 index 000000000..9fb162f37 --- /dev/null +++ b/source/_daily_emails/2022-11-14.md @@ -0,0 +1,43 @@ +--- +title: > + Camel-case or snake-case for test methods? +pubDate: 2022-11-14 +permalink: >- + archive/2022/11/14/camel-case-or-snake-case-for-test-methods +tags: + - testing +--- + +When writing object-orientated code, particularly in PHP, you usually write method names using camel-case letters - such as: + +```php +public function doSomething(): void { + // ... +} +``` + +This is also true when writing methods within a test class - only that the method name is prefixed with the word `test`: + +```php +public function testSomething(): void { +} +``` + +This is probably expected and complies with the PSR code style standards like PSR-12. + +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 `test` prefix in favour of using an annotation: + +```php +/** @test */ +public function the_api_should_return_a_200_response_code_if_everything_is_ok(): void { + // ... +} +``` + +This is something that I've done myself for a while, but now I'm starting to reconsider both options. + +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. + +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. + +Which do you prefer, and which would you expect to see in your project? diff --git a/source/_daily_emails/2022-11-15.md b/source/_daily_emails/2022-11-15.md new file mode 100644 index 000000000..11bdc89da --- /dev/null +++ b/source/_daily_emails/2022-11-15.md @@ -0,0 +1,21 @@ +--- +title: > + Writing good automated test names +pubDate: 2022-11-15 +permalink: >- + archive/2022/11/15/writing-good-automated-test-names +tags: + - testing +--- + +Something that I often see in code examples or tutorials are test methods like `testGet` or `testAdd`, or `testSubtract`. Short method names that don't describe the scenario that they're testing in much detail. + +What if a `get` method returns different types of value based on the input or a string is passed into a calculator method like `add` or `subtract`? + +I'd assume that the result of the calculation returns the total, but the test method doesn't say this. + +I'd rather be overly descriptive and write methods like `should_add_two_or_more_numbers_and_return_the_total()` rather than `testAdd`. 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 `--testdox` with PHPUnit, which converts the method name into a sentence, which is what I do when running tests in CI pipelines. + +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. + +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. diff --git a/source/_daily_emails/2022-11-16.md b/source/_daily_emails/2022-11-16.md new file mode 100644 index 000000000..ea3d988e4 --- /dev/null +++ b/source/_daily_emails/2022-11-16.md @@ -0,0 +1,17 @@ +--- +title: > + Why don't you write automated tests? +pubDate: 2022-11-16 +permalink: >- + archive/2022/11/16/why-don't-you-write-automated-tests +tags: + - testing +--- + +Many projects I’ve worked on in the past haven’t had an automated test suite. + +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 [let me know on Twitter](https://twitter.com/opdavies) and let me know why. + +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. + +Then I'll do some follow-up posts to look into and address them. diff --git a/source/_daily_emails/2022-11-17.md b/source/_daily_emails/2022-11-17.md new file mode 100644 index 000000000..9c03c195d --- /dev/null +++ b/source/_daily_emails/2022-11-17.md @@ -0,0 +1,17 @@ +--- +title: > + Agnostic CI pipelines with run files +pubDate: 2022-11-17 +permalink: >- + archive/2022/11/17/agnostic-ci-pipelines-with-run-files +--- + +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. + +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. + +Each tool has its configuration file with different settings and formats. + +Rather than being too tightly coupled to a particular tool, I like to keep things as agnostic as possible and [use a run file](https://www.oliverdavies.uk/archive/2022/08/15/using-run-file-simplify-project-tasks) with separate `ci:build` and `ci:deploy` tasks. + +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. diff --git a/source/_daily_emails/2022-11-18.md b/source/_daily_emails/2022-11-18.md new file mode 100644 index 000000000..f232c89b7 --- /dev/null +++ b/source/_daily_emails/2022-11-18.md @@ -0,0 +1,19 @@ +--- +title: > + One test a day keeps bugs away +pubDate: 2022-11-18 +permalink: >- + archive/2022/11/18/one-test-a-day-keeps-bugs-away +tags: + - testing +--- + +This is a quote from a presentation by Diego Aguiar at SymfonyCon that I saw from [a tweet from SymfonyCasts](https://twitter.com/SymfonyCasts/status/1593551105471938560?t=A8wnRUa0tLbb2q5qLhcQnA). + +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. + +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. + +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. + +Small changes over time add up. diff --git a/source/_daily_emails/2022-11-19.md b/source/_daily_emails/2022-11-19.md new file mode 100644 index 000000000..d40cd030c --- /dev/null +++ b/source/_daily_emails/2022-11-19.md @@ -0,0 +1,17 @@ +--- +title: > + Are missing tests a blocker to refactoring? +pubDate: 2022-11-19 +permalink: >- + archive/2022/11/19/are-missing-tests-a-blocker-to-refactoring +--- + +Is having automated tests a prerequisite for refactoring a piece of code? + +Without passing tests for that code, any changes made could introduce a regression, and bugs can be accidentally introduced. + +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. + +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. + +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! diff --git a/source/_daily_emails/2022-11-20.md b/source/_daily_emails/2022-11-20.md new file mode 100644 index 000000000..216485a8d --- /dev/null +++ b/source/_daily_emails/2022-11-20.md @@ -0,0 +1,25 @@ +--- +title: > + Version-controlled commented-out code +pubDate: 2022-11-20 +permalink: >- + archive/2022/11/20/version-controlled-commented-out-code +tags: + - git +--- + +Today, whilst debugging some legacy code within an application, I found several blocks of commented-out code. + +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. + +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. + +The codebase is version-controlled, so why would there be a need to comment out and keep the lines? + +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. + +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. + +If you need to re-add a change that had been removed, you can either do this manually or by reverting the commit. + +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. diff --git a/source/_daily_emails/2022-11-21.md b/source/_daily_emails/2022-11-21.md new file mode 100644 index 000000000..730c1c8c5 --- /dev/null +++ b/source/_daily_emails/2022-11-21.md @@ -0,0 +1,21 @@ +--- +title: > + Git tricks to avoid committing commented-out and other unneeded code +pubDate: 2022-11-21 +permalink: >- + archive/2022/11/21/git-tricks-to-avoid-committing-commented-out-and-other-unneeded-code +tags: + - git +--- + +[Yesterday's email](https://www.oliverdavies.uk/archive/2022/11/20/version-controlled-commented-out-code) 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? + +You could make sure that you remove everything manually before you stage and commit your changes, or I like to use `git add --patch` (or `git add -p`) 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 `--patch` option also works for other commands, including `checkout` and `reset`. + +If you've already committed something like some debug code, you can use `git commit --amend` to amend the previous commit before pushing it, or if you have a separate clean-up commit, you can use `git rebase --interactive` and either the squash or fixup options to amend the original commit. + +If some old code has been removed and you want to find it, you can use `git log -S` with a string to search for, and Git will show a list of commits where the specified string was changed. + +If instead, you wanted to search for text within the commit message, you can use `git log --grep` with a string like an issue number to see a list of commits with that text in the commit message subject line or body. + +I hope these tips help keep unwanted code out of your version-control repository. diff --git a/source/_daily_emails/2022-11-22.md b/source/_daily_emails/2022-11-22.md new file mode 100644 index 000000000..d43abe15e --- /dev/null +++ b/source/_daily_emails/2022-11-22.md @@ -0,0 +1,26 @@ +--- +title: > + tldr +pubDate: 2022-11-22 +permalink: >- + archive/2022/11/22/tldr +# tags: +# - a +# - b +--- + +`tldr` is a command-line tool that I've been using a lot recently. + +Usually, on the command line, you'd use the `man` command to show a manual page for a certain command - like `man ls`. + +`tldr` is "a collection of simplified and community-driven man pages". + +After installing it, run `man tldr` or even `tldr tldr` to learn more about it. + +Then, run a command like `tldr ls` to get output for a specific command. + +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. + +For `ls`, 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. + +For commands like `tar`, `rsync`, and `scp` 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. diff --git a/source/_daily_emails/2022-11-23.md b/source/_daily_emails/2022-11-23.md new file mode 100644 index 000000000..8d95b4de0 --- /dev/null +++ b/source/_daily_emails/2022-11-23.md @@ -0,0 +1,33 @@ +--- +title: > + Do you need to branch if you're the only one working on a project? +pubDate: 2022-11-23 +permalink: >- + archive/2022/11/23/do-you-need-to-branch +tags: + - git +--- + +Yesterday, I [saw a tweet](https://twitter.com/scottkeckwarren/status/1594752744165847040) where the writer said they were “falling into the branch, pull request, and merge after actions pass I use at work even though I'm the only one working on it”. + +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?". + +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. + +[I used to use Git Flow](https://www.oliverdavies.uk/talks/git-flow) 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’t a major issue, it wouldn't have seemed professional. + +In a team environment, feature branches are intended to keep different changes and different people's work separate. + +But is this needed if you’re the only in the team? + +Assumingly, you're only working on one change at a time, so what's the benefit of creating a separate branch? + +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. + +The other part of the tweet said, “I like the little integrations to make sure the tests pass”. + +I’m comfortable working on a single branch and committing and pushing small changes often. + +My CI pipelines run for every change that I push, and if one fails, I’ll either push a small fix to get it passing again or revert the failing change and investigate further. + +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’m working on. diff --git a/source/_daily_emails/2022-11-24.md b/source/_daily_emails/2022-11-24.md new file mode 100644 index 000000000..425ddffe6 --- /dev/null +++ b/source/_daily_emails/2022-11-24.md @@ -0,0 +1,29 @@ +--- +title: > + Doing the simplest possible thing +pubDate: 2022-11-24 +permalink: >- + archive/2022/11/24/doing-the-simplest-possible-thing +--- + +I spent most of today working on some code I wrote for the first phase of a client project a few months ago. + +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. + +It was the simplest thing that worked. + +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. + +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?". + +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. + +The idea of "What's the simplest thing?" is something that I use regularly. + +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. + +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. + +Even when writing an email or blog post, once I start writing, it's much easier to continue once I'm in the flow. + +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. diff --git a/source/_daily_emails/2022-11-25.md b/source/_daily_emails/2022-11-25.md new file mode 100644 index 000000000..ade7cbe88 --- /dev/null +++ b/source/_daily_emails/2022-11-25.md @@ -0,0 +1,19 @@ +--- +title: > + Plan, then code +pubDate: 2022-11-25 +permalink: >- + archive/2022/11/25/plan-then-code +--- + +Recently I [saw this tweet](https://twitter.com/OneJKMolina/status/1303047499238776832) in a screenshot on a LinkedIn post. + +The post was about improving business writing, but the original tweet was about software engineering. + +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.". + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-11-30.md b/source/_daily_emails/2022-11-30.md new file mode 100644 index 000000000..e7bd74f35 --- /dev/null +++ b/source/_daily_emails/2022-11-30.md @@ -0,0 +1,43 @@ +--- +title: > + Ship, Show or Ask +pubDate: 2022-11-30 +permalink: >- + archive/2022/11/30/ship-show-or-ask +tags: + - git +--- + +"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. + +Each change is either a "Ship", "Show", or "Ask". + +## Ship + +"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. + +## Show + +"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. + +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. + +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. + +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. + +## Ask + +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. + +This is also common when new Developers join a project or need to change some code they haven't worked on before. + +## Conclusion + +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. + +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. + +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. + +The full article with more information is at https://martinfowler.com/articles/ship-show-ask.html. diff --git a/source/_daily_emails/2022-12-01.md b/source/_daily_emails/2022-12-01.md new file mode 100644 index 000000000..49710417d --- /dev/null +++ b/source/_daily_emails/2022-12-01.md @@ -0,0 +1,33 @@ +--- +title: > + Writing readable code +pubDate: 2022-12-01 +permalink: >- + archive/2022/12/01/writing-readable-code +--- + +This week, I needed to investigate and fix a bug within some existing code. + +It's code written some time ago and not by anyone working on the team. + +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. + +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. + +I also watched a video of a conference talk titled "Writing code you won't hate tomorrow", which re-introduced me to Object Callisthenics. + +They are from "The ThoughtWorks Anthology" book and are some steps that include some of the points that I had written: + +1. Use only one level of indentation per method. +1. Don’t use the else keyword. +1. Wrap all primitives and strings. +1. Use only one dot per line. +1. Don’t abbreviate. +1. Keep all entities small. +1. Don’t use any classes with more than two instance variables. +1. Use first-class collections. +1. Don’t use any getters/setters/properties + +As well as the original book, there are numerous blog posts and videos on this topic. + +Why try some of them on the next code you write and see if it's easier to read and understand? diff --git a/source/_daily_emails/2022-12-02.md b/source/_daily_emails/2022-12-02.md new file mode 100644 index 000000000..4224cc611 --- /dev/null +++ b/source/_daily_emails/2022-12-02.md @@ -0,0 +1,27 @@ +--- +title: > + Commit and push something every day +pubDate: 2022-12-02 +permalink: >- + archive/2022/12/02/commit-and-push-something-every-day +--- + +One of the significant changes that I've found and that's benefitted me whilst developing is to commit and push something every day. + +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. + +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. + +It could be updating some documentation or [writing a technical document](https://www.oliverdavies.uk/archive/2022/09/23/adrs-technical-design-documents); 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. + +Committing something at least once a day creates a different mindset to "I'll write everything and push it when it's done". + +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. + +You don't need to push your change to mainline. If you use the ["Ship, Show, Ask" approach](https://www.oliverdavies.uk/archive/2022/11/30/ship-show-or-ask) 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. + +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. + +This became my normal approach instead of having long-lived feature branches or lots of unpushed local commits. + +I much prefer making as small charges as possible and pushing them as often as I can. diff --git a/source/_daily_emails/2022-12-03.md b/source/_daily_emails/2022-12-03.md new file mode 100644 index 000000000..cf58f8764 --- /dev/null +++ b/source/_daily_emails/2022-12-03.md @@ -0,0 +1,23 @@ +--- +title: > + What to do with TODO comments +pubDate: 2022-12-03 +permalink: >- + archive/2022/12/03/what-to-do-with-todo-comments +--- + +[In a previous email](https://www.oliverdavies.uk/archive/2022/11/20/version-controlled-commented-out-code), 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. + +But what about TODO comments that remind you to do something? + +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. + +I recently removed a small number from a codebase I added while working on the first MVP. + +They were comments like "Move this to a repository" or "Remove this hard-coded value and make this configurable". + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-12-04.md b/source/_daily_emails/2022-12-04.md new file mode 100644 index 000000000..347bf8c01 --- /dev/null +++ b/source/_daily_emails/2022-12-04.md @@ -0,0 +1,25 @@ +--- +title: > + Writing "Why first" user stories +pubDate: 2022-12-04 +permalink: >- + archive/2022/12/04/writing-why-first-user-stories +--- + +I've usually written user stories that follow this format: + +As a... +I want... +So that... + +You focus on the person who needs the task first, followed by what they want, and why they want it. + +Lately, I've been re-ordering stories to follow this order: + +So that... +As a... +I want... + +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. + +What's needed and who needs it doesn't matter unless you also capture why it's needed. diff --git a/source/_daily_emails/2022-12-05.md b/source/_daily_emails/2022-12-05.md new file mode 100644 index 000000000..4d5e2626e --- /dev/null +++ b/source/_daily_emails/2022-12-05.md @@ -0,0 +1,27 @@ +--- +title: > + Outcomes or output +pubDate: 2022-12-05 +permalink: >- + archive/2022/12/05/outcomes-or-output +--- + +I was reading a Twitter thread recently that [started with this tweet](https://twitter.com/allenholub/status/1594786089994067969). + +TL;DR: + +> "Measuring output (e.g. velocity) is a waste of time. It's outcomes you care about - customer happiness." + +This is definitely something that I agree with. + +I can't remember the last time I looked at an output burndown chart or a velocity score. + +I'd rather focus on what outcomes have been delivered and adding value to clients and customers. + +What features did we release, what bugs did we fix, and what impact and value did that provide? + +What increased revenue or improved a customer's experience? + +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. + +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? diff --git a/source/_daily_emails/2022-12-06.md b/source/_daily_emails/2022-12-06.md new file mode 100644 index 000000000..b10ece4b2 --- /dev/null +++ b/source/_daily_emails/2022-12-06.md @@ -0,0 +1,33 @@ +--- +title: > + Should you comment your code? +pubDate: 2022-12-06 +permalink: >- + archive/2022/12/06/should-you-comment-your-code +--- + +Something that I hear often is "self-documenting code", and that code should be easy to understand without comments. + +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. + +I agree with this, but I still think there is a place for comments within the code as long as they add value. + +## What comments shouldn't be + +Comments shouldn't just repeat what the code says. + +If the comment says "Returns false", and I can read that from the code, the comment isn't adding any value. + +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. + +Comments like "Constructor" and "This shouldn't happen" add no context. + +## What comments should be + +Comments need to add value by adding extra information or explaining why the code does what it does. + +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. + +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. + +Comments should make the code easier to read, understand, and work with for yourself and other team members. diff --git a/source/_daily_emails/2022-12-07.md b/source/_daily_emails/2022-12-07.md new file mode 100644 index 000000000..592e41570 --- /dev/null +++ b/source/_daily_emails/2022-12-07.md @@ -0,0 +1,23 @@ +--- +title: > + Separating releases from deployments with feature flags +pubDate: 2022-12-07 +permalink: >- + archive/2022/12/07/separating-releases-from-deployments-with-feature-flags +--- + +In a typical feature release process, a feature is released when you merge the code and push it to production. + +If a bug is found after the release, the code needs to be reverted (and any conflicts or issues dealt with) and deployed again. + +Also, features can only be merged once they are complete, which may take hours, days or weeks, depending on the size of the feature. + +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. + +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. + +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. + +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. + +Another way I use feature flags is within a [multi-site Drupal application](https://www.oliverdavies.uk/archive/2022/11/13/how-i-manage-multiple-drupal-websites-using-the-same-codebase) 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. diff --git a/source/_daily_emails/2022-12-08.md b/source/_daily_emails/2022-12-08.md new file mode 100644 index 000000000..d09fe2fb9 --- /dev/null +++ b/source/_daily_emails/2022-12-08.md @@ -0,0 +1,64 @@ +--- +title: > + The Decorator design pattern +pubDate: 2022-12-08 +permalink: >- + archive/2022/12/08/the-decorator-design-pattern +tags: + - design-patterns +--- + +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. + +As long as a class implements an Interface, it can be decorated. + +For example, if I have this PHP interface: + +```php +interface DoesSomething +{ + public function doSomething(): void; +} +``` + +I could have this class that does something: + +```php +final class FirstClass implements DoesSomething +{ + public function doSomething(): void + { + // Does something. + } +} +``` + +If I need to do something else, like caching or logging the result, I can decorate it. + +To do this, I need another class that implements the same interface and inject the original version. + +```php +final class SecondClass implements DoesSomething +{ + public function __constuct( + private DoesSomething $originalClass + ) {} + + public function doSomething() + { + // Do something else before. + + $this->originalClass->doSomething(); + + // Do something else afterwards. + } +} +``` + +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. + +As the two classes implement the same interface, I can swap between different versions and decorate multiple times if needed. + +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. + +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. diff --git a/source/_daily_emails/2022-12-09.md b/source/_daily_emails/2022-12-09.md new file mode 100644 index 000000000..937186a7d --- /dev/null +++ b/source/_daily_emails/2022-12-09.md @@ -0,0 +1,28 @@ +--- +title: > + How and why I started using PostCSS +pubDate: 2022-12-09 +permalink: >- + archive/2022/12/09/how-and-why-i-started-using-postcss +tags: + - css + - front-end +--- + +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. + +This was the case when I first saw what became Tailwind CSS, which were some stylesheets written in Less and ported manually between projects. + +I remember watching one of those streams, and a fellow viewer suggested PostCSS, which Tailwind CSS would later be written in. + +PostCSS, a CSS post-processor rather than a pre-processor, has become my preferred way of writing CSS because of Tailwind. + +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. + +I moved to use PostCSS by default - removing one of the build steps. + +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. + +It's also quick and easy to use, using the PostCSS CLI tool and without more complex tools like Webpack. + +If you haven't tried PostCSS, I recommend taking a look. diff --git a/source/_daily_emails/2022-12-10.md b/source/_daily_emails/2022-12-10.md new file mode 100644 index 000000000..6fd0ad1a1 --- /dev/null +++ b/source/_daily_emails/2022-12-10.md @@ -0,0 +1,53 @@ +--- +title: > + Managing databases with Neovim and Docker +pubDate: 2022-12-10 +permalink: >- + archive/2022/12/10/managing-databases-with-neovim-and-docker +tags: + - docker + - neovim +--- + +If you work on software projects that use a database, you need a convenient way to connect, inspect, and query them. + +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. + +## Configuring Docker Compose + +A local port needs to be exposed from the database container that Neovim can connect to. + +I usually do this with a `docker-compose.override.yaml` file: + +```yaml +services: + database: + ports: + - 3307:3306 +``` + +Docker Compose recognises this by default, extends the normal `docker-compose.yaml` file and adds a port forwarding to the `database` service. + +## Configuring Neovim + +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. + +Once installed, run `:DBUIAddconnection` to add a database connection. + +Here is an example connection string: + +``` +mysql://drupal:drupal@localhost:3307/drupal?protocol=tcp +``` + +Using the local port mapping, this connects to a MySQL database within the `database` service. + +Then run `:DBUI` to toggle the UI and see a list of databases in the left-hand sidebar. + +You can enter `R` to refresh databases or `r` to rename or update connection details for a specific database. + +Once connected, you can enter and save queries, using table and column name completion, which are executed every time the query is saved. + +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. + +If you're a Vim or Neovim user, I'd suggest trying this setup and seeing if it works for you. diff --git a/source/_daily_emails/2022-12-15.md b/source/_daily_emails/2022-12-15.md new file mode 100644 index 000000000..d3b2b7933 --- /dev/null +++ b/source/_daily_emails/2022-12-15.md @@ -0,0 +1,24 @@ +--- +title: > + Happy Drupal 10 release day! +pubDate: 2022-12-15 +permalink: >- + archive/2022/12/15/happy-drupal-10-release-day +tags: + - drupal + - php +--- + +Today, Drupal 10 was released alongside Drupal 9.5. + +This means that, as of today, Drupal 9.3 is no longer supported, so people should update to 9.4, 9.5, or 10. + +As things stand, Drupal 7 is still supported until November 2023. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-12-20.md b/source/_daily_emails/2022-12-20.md new file mode 100644 index 000000000..2f8c877a6 --- /dev/null +++ b/source/_daily_emails/2022-12-20.md @@ -0,0 +1,26 @@ +--- +title: > + Automating all the things, including infrastructure +pubDate: 2022-12-20 +permalink: >- + archive/2022/12/20/automating-all-the-things,-including-infrastructure +tags: + - automation + - devops +--- + +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. + +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. + +Another main piece of automation I use is to create and manage the infrastructure my applications run in. + +I've talked about it in my [Deploying PHP applications with Ansible and Ansistrano talk](https://www.oliverdavies.uk/talks/deploying-php-ansible-ansistrano), 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. + +Using automation tools like Terraform, Pulumi or Ansible, you can run a single command to create, update or destroy resources or your entire stack. + +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. + +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. + +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. diff --git a/source/_daily_emails/2022-12-21.md b/source/_daily_emails/2022-12-21.md new file mode 100644 index 000000000..d0f77073f --- /dev/null +++ b/source/_daily_emails/2022-12-21.md @@ -0,0 +1,19 @@ +--- +title: > + Duck typing +pubDate: 2022-12-21 +permalink: >- + archive/2022/12/21/duck-typing +--- + +If it looks like a duck, walks like a duck, and quacks like a duck, it must be a duck. + +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. + +If not, you'd get an error that the method or property doesn't exist when trying to invoke or access it. + +This is the opposite of strict typing, where you'd get a Type error if you passed the wrong thing. + +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. + +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. diff --git a/source/_daily_emails/2022-12-22.md b/source/_daily_emails/2022-12-22.md new file mode 100644 index 000000000..c5c854cb5 --- /dev/null +++ b/source/_daily_emails/2022-12-22.md @@ -0,0 +1,17 @@ +--- +title: > + The Boy Scout rule +pubDate: 2022-12-22 +permalink: >- + archive/2022/12/22/the-boy-scout-rule +--- + +The Boy Scout rule is "Always leave the campground cleaner than you found it". + +From a programming perspective, "Always leave the code better than you find it". + +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. + +If there's a variable that could have a more descriptive name, change it. + +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. diff --git a/source/_daily_emails/2022-12-23.md b/source/_daily_emails/2022-12-23.md new file mode 100644 index 000000000..c295fd9e9 --- /dev/null +++ b/source/_daily_emails/2022-12-23.md @@ -0,0 +1,23 @@ +--- +title: > + Speaking at PHP Stoke and nor(DEV):con +pubDate: 2022-12-23 +permalink: >- + archive/2022/12/23/speaking-at-php-stoke-and-nordevcon +tags: + - public-speaking +--- + +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. + +## PHP Stoke + +The first PHP Stoke meetup will be held at Genr8 Smithfield Works on the 12th of January. I'll be presenting "[Things you should know about PHP](https://www.oliverdavies.uk/talks/things-you-should-know-about-php)". It'll be great to be the first speaker at this new meetup. + +## nor(DEV):con + +The Norfolk Developers conference is in Norwich on the 23rd and 24th of February. + +I'll be presenting "[Taking Flight about Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css)". 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. + +It'll be great to be speaking at these events and hopefully others in 2023. diff --git a/source/_daily_emails/2022-12-28.md b/source/_daily_emails/2022-12-28.md new file mode 100644 index 000000000..965ed3d7b --- /dev/null +++ b/source/_daily_emails/2022-12-28.md @@ -0,0 +1,19 @@ +--- +title: > + Debugging gitignore rules +pubDate: 2022-12-28 +permalink: >- + archive/2022/12/28/debugging-gitignore-rules +tags: + - git +--- + +Have you wondered why a file or directory is being ignored in your Git repository and isn't appearing when you run `git status`? + +Maybe you have multiple `.gitignore` 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. + +## `check-ignore` to the rescue + +`git check-ignore` accepts a list of paths and checks if each is ignored. + +There's also a `--verbose` option that will tell you which `.gitignore` 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. diff --git a/source/_daily_emails/2022-12-29.md b/source/_daily_emails/2022-12-29.md new file mode 100644 index 000000000..566e39e01 --- /dev/null +++ b/source/_daily_emails/2022-12-29.md @@ -0,0 +1,45 @@ +--- +title: > + What is the cost of a bug? +pubDate: 2022-12-29 +permalink: >- + archive/2022/12/29/what-is-the-cost-of-a-bug +--- + +All software has bugs, but each has a different cost depending on when and where it's found. + +## In production + +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. + +You'd need to create a ticket and schedule the work, meaning you're not working on something else. + +Cost: High + +## In a pre-production environment + +It's likely found by a test analyst or product owner but hidden from the end users and customers. + +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. + +Cost: High + +## In a CI pipeline + +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. + +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. + +Cost: Medium + +## Locally + +If an automated check fails in CI, why not run it locally before you commit and push the change? + +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. + +If you were working in a pair or mob, could someone else have spotted the issue and suggested a fix? + +Cost: Low + +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. diff --git a/source/_daily_emails/2022-12-30.md b/source/_daily_emails/2022-12-30.md new file mode 100644 index 000000000..1156f1db2 --- /dev/null +++ b/source/_daily_emails/2022-12-30.md @@ -0,0 +1,35 @@ +--- +title: > + Tests are living documentation +pubDate: 2022-12-30 +permalink: >- + archive/2022/12/30/tests-are-living-documentation +tags: + - testing +--- + +Today I was working on a project and made a one-line change that updated a single value within an API response. + +Unexpectedly, it caused a test to fail. The API response returned a 500 status code instead of the expected 201 code. + +I reverted the change locally and ensured that the test passed again, so I knew it was causing the failure. + +## Fixing the failure + +The change was removing a hard-coded part of a URL to a dynamic one, using Drupal's `Settings` class. + +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. + +## How does the Settings class work? + +To fix the test failure, I needed to learn how to set a Settings value within a test. + +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. + +## Tests are living documentation + +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. + +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. + +By writing tests, you're ensuring that your code works as expected and documenting it at the same time. diff --git a/source/_daily_emails/2022-12-31.md b/source/_daily_emails/2022-12-31.md new file mode 100644 index 000000000..dad74b5e5 --- /dev/null +++ b/source/_daily_emails/2022-12-31.md @@ -0,0 +1,23 @@ +--- +title: > + Just start writing +pubDate: 2022-12-31 +permalink: >- + archive/2022/12/31/just-start-writing +tags: + - productivity +--- + +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. + +When this happens, I try to find the smallest thing I can do to start the task and get the ball rolling. + +This could be just opening Neovim or Notion and finding the smallest task I can do to get going. + +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. + +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. + +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. + +Things are great once the ball is rolling; the question sometimes is, "what is the simplest thing I can do to start it?". diff --git a/source/_daily_emails/2023-01-01.md b/source/_daily_emails/2023-01-01.md new file mode 100644 index 000000000..a58d5e27c --- /dev/null +++ b/source/_daily_emails/2023-01-01.md @@ -0,0 +1,20 @@ +--- +title: > + Types and static analysis saved me today +pubDate: 2023-01-01 +permalink: >- + archive/2023/01/01/types-and-static-analysis-saved-me-today +tags: + - static-analysis + - types +--- + +Today I was writing Pulumi code in Typescript, and I although I have autocompletion, I mistyped the name of a property. + +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. + +It only took a second or two for me to make and fix the mistake. + +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. + +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. diff --git a/source/_daily_emails/2023-01-02.md b/source/_daily_emails/2023-01-02.md new file mode 100644 index 000000000..26df9ffdf --- /dev/null +++ b/source/_daily_emails/2023-01-02.md @@ -0,0 +1,25 @@ +--- +title: > + Don't use arbitrary values in Tailwind CSS +pubDate: 2023-01-02 +permalink: >- + archive/2023/01/02/dont-use-arbitrary-values-in-tailwind-css +tags: + - tailwind-css +--- + +It's been almost five years since I gave the first version of my "[Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css)" talk at the Drupal Bristol meetup in January 2018. + +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. + +As I prepare for the Norfolk Developers Conference (nordevcon) next month, I'm updating the talk again. + +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. + +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. + +A set list of colours, text sizes, margins and padding, for example, meant that UIs looked more consistent and the generated CSS was smaller. + +If you need an additional value or to replace the existing values, you can do so within your `tailwind.config.js` file, and Tailwind will generate classes accordingly. + +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. diff --git a/source/_daily_emails/2023-01-03.md b/source/_daily_emails/2023-01-03.md new file mode 100644 index 000000000..90d141780 --- /dev/null +++ b/source/_daily_emails/2023-01-03.md @@ -0,0 +1,33 @@ +--- +title: > + Tailwind CSS' extensibility is one of its best features +pubDate: 2023-01-03 +permalink: >- + archive/2023/01/03/tailwind-css-extensibility-is-one-of-its-best-features +tags: + - tailwind-css +--- + +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. + +You can add your own CSS to a stylesheet within a specific layer, customise the theme settings within a `tailwind.config.js` file, and write your own custom plugins that you can reuse and even release as separate open-source projects. + +Here is a complete plugin that I've added to some projects recently: + +```js +const plugin = require('tailwindcss/plugin'); + +plugin(function({ addVariant }) { + addVariant('hocus', ['&:hover', '&:focus']) +}); +``` + +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. + +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. + +I've also released some [as open-source projects on GitHub](https://github.com/opdavies?tab=repositories&q=tailwind-plugin). + +The interesting thing is that the plugin API is how Tailwind itself generates its own classes, and I like the stability that provides. + +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. diff --git a/source/_daily_emails/2023-01-04.md b/source/_daily_emails/2023-01-04.md new file mode 100644 index 000000000..0fc5481b3 --- /dev/null +++ b/source/_daily_emails/2023-01-04.md @@ -0,0 +1,63 @@ +--- +title: > + Testable Tailwind CSS plugins +pubDate: 2023-01-04 +permalink: >- + archive/2023/01/04/testable-tailwind-css-plugins +tags: + - tailwind-css +--- + +A great thing about [Tailwind CSS plugins](https://www.oliverdavies.uk/archive/2023/01/03/tailwind-css-extensibility-is-one-of-its-best-features) being written in JavaScript is that they can be tested using tools like Jest. + +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): + +```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', () => { + const output = ` + .test { + display: block + } + ` + + run().then(result => { + expect(result.css).toMatchCss(output) + }) +}) + +test('it generates the correct classes with variants', () => { + const output = ` + .test { + display: block + } + .hover\\:test:hover { + display: block + } + .focus\\:test:focus { + display: block + } + ` + + run({ variants: ['hover', 'focus'] }).then(result => { + expect(result.css).toMatchCss(output) + }) +}); +``` + +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. diff --git a/source/_daily_emails/2023-01-05.md b/source/_daily_emails/2023-01-05.md new file mode 100644 index 000000000..f801ac027 --- /dev/null +++ b/source/_daily_emails/2023-01-05.md @@ -0,0 +1,21 @@ +--- +title: > + Adding Tailwind CSS to an existing project +pubDate: 2023-01-05 +permalink: >- + archive/2023/01/05/adding-tailwind-to-an-existing-project +tags: + - tailwind-css +--- + +Tailwind's configuration file also makes it easy to add it to an existing codebase, whether it uses custom CSS or another CSS framework. + +You can opt-out of Tailwind's CSS reset and normalisation by adding `corePlugins: { preflight: false }` to tailwind.config.js, and if you have duplicate classes with existing classes and Tailwind-generated ones, you can add `prefix: 'tw-'` to prefix all of Tailwind's class names and avoid the conflicts. + +If you need to deal with specificity, you can mark Tailwind-generated classes as important by adding `important: true` 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. `!flex`. + +Or, if you know that your Tailwind styles will only be used within a certain element, like `#app`, instead of making all classes important, by adding `important: "#app"` to the configuration, Tailwind classes will be prefixed with that selector - making them more specific. + +Once these options are set, you can start using Tailwind without affecting the existing styles. + +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. diff --git a/source/_daily_emails/2023-01-06.md b/source/_daily_emails/2023-01-06.md new file mode 100644 index 000000000..6837e838f --- /dev/null +++ b/source/_daily_emails/2023-01-06.md @@ -0,0 +1,23 @@ +--- +title: > + Utility-first or utility-last? +pubDate: 2023-01-06 +permalink: >- + archive/2023/01/06/utility-first-or-utility-last +tags: + - tailwind-css +--- + +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. + +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 [adding a utility-based framework like Tailwind CSS](https://www.oliverdavies.uk/archive/2023/01/05/adding-tailwind-to-an-existing-project) to an existing project and you want to use it for a new page or component whilst keeping the existing styles. + +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. + +You could do the opposite too, and refactor groups of utilities into a CSS component, either by using Tailwind's `@apply` directive or [writing a plugin](https://www.oliverdavies.uk/archive/2023/01/03/tailwind-css-extensibility-is-one-of-its-best-features). + +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. + +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. + +Do you typically do styling utility-first or utility-last, or are you transitioning from one to the other? diff --git a/source/_daily_emails/2023-01-07.md b/source/_daily_emails/2023-01-07.md new file mode 100644 index 000000000..6540cc85d --- /dev/null +++ b/source/_daily_emails/2023-01-07.md @@ -0,0 +1,132 @@ +--- +title: > + Reducing utility class duplication +pubDate: 2023-01-07 +permalink: >- + archive/2023/01/07/reducing-utility-class-duplication +tags: + - tailwind-css +--- + + + +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. + +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: + +```html +
  • + About +
    • +``` + +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. + +## Extracting a variable of class names + +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. + +```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"; +--- + +
  • About
    • +
  • Talks
    • +
  • Blog
    • +``` + +## Extracting CSS components + +Instead of extracting a variable, you could also extract a CSS component. With Tailwind, the `@apply` directive within a stylesheet will create a reusable CSS component: + +```astro + + + + + +``` + +The `link` 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. + +## Loops and maps + +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. + +For example, in Astro: + +```astro +--- +const links = [ + { name: "About" }, + { name: "Blog" }, + { name: "Talks" }, + { name: "Daily list" }, + { name: "Search" }, +]; +--- + +{links.map(link => ( +
  • + + {link.name} + +
    • +))} +``` + +## Extracting HTML components + +Finally, if the component needs to be reused, it can be extracted into its own file and re-imported where needed. + +This is the extracted component: + +```astro +--- +const { name } = Astro.props; +--- + + + {name} + +``` + +And the original file: + +```astro +--- +import Layout from "~/layouts/Layout.astro"; +import Link from "~/components/Link.astro"; +--- + + +
      +
      • +
      • +
      • +
      • +
      • +
    +     +``` + +This can now be used anywhere within this project and could be combined with the loop approach, passing the appropriate value to the `name` prop. + +## Summary + +All of these approaches remove duplication, either using features provided by Tailwind CSS or a templating engine, to make the code more maintainable. + +I've shown [Astro](https://astro.build) in these examples but the same can be done with PHP, Twig, Blade, Vue, React, etc. + +The examples are public on GitHub at https://github.com/opdavies/reducing-utility-class-duplication/tree/main/src/pages. diff --git a/source/_daily_emails/2023-01-16.md b/source/_daily_emails/2023-01-16.md new file mode 100644 index 000000000..a1bdf4b71 --- /dev/null +++ b/source/_daily_emails/2023-01-16.md @@ -0,0 +1,20 @@ +--- +title: > + Back after PHP Stoke +pubDate: 2023-01-16 +permalink: >- + archive/2023/01/16/back-after-php-stoke +# tags: +# - a +# - b +--- + +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. + +It was a great event with around 35 attendees and two other speakers as well as myself. + +The [latest version of my slides are online](https://www.oliverdavies.uk/talks/things-you-should-know-about-php) as well [some updated resources](https://www.oliverdavies.uk/things-about-php). + +My next talk will be at the Norfolk Developers conference next month where I'll be presenting an updated version of [Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css). + +If you have a topic idea for a talk or would like me to speak at your meetup or conference, please get in touch. diff --git a/source/_daily_emails/2023-01-17.md b/source/_daily_emails/2023-01-17.md new file mode 100644 index 000000000..673a2a57a --- /dev/null +++ b/source/_daily_emails/2023-01-17.md @@ -0,0 +1,23 @@ +--- +title: > + Things to know about PHP +pubDate: 2023-01-17 +permalink: >- + archive/2023/01/17/things-to-know-about-php +tags: + - php +--- + +The talk that I gave last week at PHP Stoke was [Things to know about PHP](https://www.oliverdavies.uk/talks/things-you-should-know-about-php) - 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. + +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. + +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. + +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. + +Oh, and elePHPants! + +The latest versions of the slides are on the Talks section of my website (the link is at the top of the email). + +If you'd like me to come and speak at your meetup or conference, please get in touch! diff --git a/source/_daily_emails/2023-01-18.md b/source/_daily_emails/2023-01-18.md new file mode 100644 index 000000000..ee7da016a --- /dev/null +++ b/source/_daily_emails/2023-01-18.md @@ -0,0 +1,23 @@ +--- +title: > + Drupal turns 22! +pubDate: 2023-01-18 +permalink: >- + archive/2023/01/18/drupal-turns-22 +tags: + - php +--- + +On Sunday, the Drupal project turned 22 years old. + +I've personally been working with Drupal primarily for almost 15 years [according to my Drupal.org profile](https://www.drupal.org/u/opdavies), 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. + +Last month, I started my first Drupal 10 project for a client. + +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. + +I'm also happy to have [presented talks and workshops](https://www.oliverdavies.uk/talks) 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. + +I've had opportunities to contribute to open-source by having patches committed to Drupal core and maintaining modules and themes like [Override Node Options](https://www.drupal.org/project/override_node_options) and the [Tailwind CSS starter kit](https://www.drupal.org/project/tailwindcss). I've also mentored and helped others to get their first commits to Drupal core and open-source. + +I plan to continue working with Drupal and being part of the community for a long time, hopefully for at least another 22 years. diff --git a/source/_daily_emails/2023-01-19.md b/source/_daily_emails/2023-01-19.md new file mode 100644 index 000000000..52577fc22 --- /dev/null +++ b/source/_daily_emails/2023-01-19.md @@ -0,0 +1,28 @@ +--- +title: > + Long-term maintainability with utility classes and Tailwind CSS +pubDate: 2023-01-19 +permalink: >- + archive/2023/01/19/long-term-maintainability-with-utility-classes-and-tailwind-css +tags: + - css + - tailwind-css +--- + +One of the common initial concerns of utility classes and Tailwind CSS is its maintainability. + +How you manage all the classes within the HTML and how easy is it to make changes? + +Today, [I saw this tweet](https://twitter.com/mauro_codes/status/1615726036737576960): + +> 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. + + One of my earliest Tailwind projects was the [PHP South West website](https://phpsw.uk). We [worked on this in November 2017](https://twitter.com/opdavies/status/934488762276564993) and it still uses Tailwind CSS 0.5. + +These are the classes used on the main menu: + +`bg-grey-lightest hidden absolute z-20 w-full border border-grey-lighter sm:flex sm:relative sm:w-auto sm:border-none` + +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. + +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. diff --git a/source/_daily_emails/2023-01-20.md b/source/_daily_emails/2023-01-20.md new file mode 100644 index 000000000..03cb45dfd --- /dev/null +++ b/source/_daily_emails/2023-01-20.md @@ -0,0 +1,18 @@ +--- +title: > + Tailwind's classes are your classes +pubDate: 2023-01-20 +permalink: >- + archive/2023/01/20/tailwinds-classes-are-your-classes +tags: + - css + - tailwind-css +--- + +In my [Taking Flight with Tailwind CSS talk](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css), I've described Tailwind as a CSS utility class generator. You write a configuration file that Tailwind reads and generates the appropriate classes. + +Yesterday I mentioned the [PHP South West user group](https://phpsw.uk) website. It's a project that [I worked on in November 2017](https://twitter.com/opdavies/status/934488762276564993) and uses Tailwind 0.5. + +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. + +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. diff --git a/source/_daily_emails/2023-01-21.md b/source/_daily_emails/2023-01-21.md new file mode 100644 index 000000000..bbc4c152c --- /dev/null +++ b/source/_daily_emails/2023-01-21.md @@ -0,0 +1,20 @@ +--- +title: > + Tailwind: Not just translating CSS to utility classes +pubDate: 2023-01-21 +permalink: >- + archive/2023/01/21/tailwind-not-just-translating-css-to-utility-classes +tags: + - css + - tailwind-css +--- + +Whilst a number of classes that Tailwind CSS generates are single-value utility classes such as `.block { display: block; }` and `.relative { position: relative; }`, it also includes additional things such as [setting a default line height with a font size](https://tailwindcss.com/docs/font-size#setting-the-font-size), adding variants for [group-hover](https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state) and [focus-within](https://tailwindcss.com/docs/hover-focus-and-other-states#focus-within) (as well as various other pseudo states). + +It includes utilities for adding [horizontal or vertical space](https://tailwindcss.com/docs/space#add-horizontal-space-between-children) or [styling dividers between elements](https://tailwindcss.com/docs/divide-style). + +As well prefixing a class using a screen modifier, such as `md:flex`, you can stack them and set a maximum screen value. For example, `md:max-lg:flex` will only flex between the `md` and `lg` breakpoints. + +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. + +If you take a look at the [Tailwind CSS documentation](https://tailwindcss.com/docs), you'll definitely find some interesting and useful things. diff --git a/source/_daily_emails/2023-01-22.md b/source/_daily_emails/2023-01-22.md new file mode 100644 index 000000000..c9e91a987 --- /dev/null +++ b/source/_daily_emails/2023-01-22.md @@ -0,0 +1,18 @@ +--- +title: > + Building Bootstrap CSS examples with Tailwind +pubDate: 2023-01-22 +permalink: >- + archive/2023/01/22/building-bootstrap-css-examples-with-tailwind +tags: + - css + - tailwind-css +--- + +Previously when I gave my [Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css) talk, I created examples that relate to the event such as something related to that technology or event. + +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 [Bootstrap CSS components](https://getbootstrap.com/docs/4.0/examples) with Tailwind CSS. + +I've created the [Album](http://bootstrap-with-tailwind.s3-website.eu-west-2.amazonaws.com/album) and [Pricing](http://bootstrap-with-tailwind.s3-website.eu-west-2.amazonaws.com/pricing) components so far but will likely do more before the conference as I think they're good examples. + +[The source code](https://github.com/opdavies/bootstrap-with-tailwind) 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. diff --git a/source/_daily_emails/2023-01-23.md b/source/_daily_emails/2023-01-23.md new file mode 100644 index 000000000..9d84be2d1 --- /dev/null +++ b/source/_daily_emails/2023-01-23.md @@ -0,0 +1,27 @@ +--- +title: > + Debugging with git bisect +pubDate: 2023-01-23 +permalink: >- + archive/2023/01/23/debugging-with-git-bisect +tags: + - git +--- + +Last week, I had to debug a regression in a codebase. + +Something was working at the last release but is now broken. + +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. + +Git has a great tool for this - `git bisect`. + +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. + +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. + +Based on your answers, Git will then tell you which the first bad commit is. + +Even better, if it's something that you can script or is covered with an automated test, `git bisect` can run a command for you and find the failure automatically rather than a human needing to check manually. + +Once you've found the commit that breaks, you can view it and find and fix the bug. diff --git a/source/_daily_emails/2023-01-24.md b/source/_daily_emails/2023-01-24.md new file mode 100644 index 000000000..84fda75a2 --- /dev/null +++ b/source/_daily_emails/2023-01-24.md @@ -0,0 +1,23 @@ +--- +title: > + Small commits and good commit messges +pubDate: 2023-01-24 +permalink: >- + archive/2023/01/24/small-commits-and-good-commit-messges +tags: + - git +--- + +An important thing when using a tool like [git bisect](https://www.oliverdavies.uk/archive/2023/01/23/debugging-with-git-bisect) as well as reviewing pull/merge requests and commits is to have small (aka "atomic") commits. + +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. + +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. + +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. + +Also take some time to write good, informative commit messages. + +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. + +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 [conventional commits specification](https://www.oliverdavies.uk/archive/2022/09/01/conventional-commits-changelogs), though the main objective is to have all of the information documented so it's available in the future. diff --git a/source/_daily_emails/2023-01-25.md b/source/_daily_emails/2023-01-25.md new file mode 100644 index 000000000..b52228840 --- /dev/null +++ b/source/_daily_emails/2023-01-25.md @@ -0,0 +1,25 @@ +--- +title: > + To squash or not to squash +pubDate: 2023-01-25 +permalink: >- + archive/2023/01/25/to-squash-or-not-to-squash +tags: + - git +--- + +When reviewing a pull or merge request, tools like GitHub and GitHub offer the option to squash the commits before merging. + +If the request had twenty commits, they'd be combined into a single commit before being merged. + +But should you do it? + +The answer will be "it depends" based on the project or team, but I'm personally not a fan of squashing commits. + +Even though I commit small changes often, I put quite a bit of effort into [crafting commits and writing detailed commit messages](https://www.oliverdavies.uk/archive/2023/01/24/small-commits-and-good-commit-messges) 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. + +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. + +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 [git bisect](https://www.oliverdavies.uk/archive/2023/01/23/debugging-with-git-bisect) would no longer work and a single commit couldn't be simply reverted if it contained a bug. + +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. diff --git a/source/_daily_emails/2023-02-07.md b/source/_daily_emails/2023-02-07.md new file mode 100644 index 000000000..43772624a --- /dev/null +++ b/source/_daily_emails/2023-02-07.md @@ -0,0 +1,19 @@ +--- +title: > + Astro as a static site generator +pubDate: 2023-02-07 +permalink: >- + archive/2023/02/07/astro-as-a-static-site-generator +tags: + - astro +--- + +Since first setting it first during Simon Vrachliotis' workshops, I've started evaluating [Astro](https://astro.build) as an option for building static websites alongside PHP options like Sculpin and Jigsaw, and used it to rebuild [my personal website](https://www.oliverdavies.uk). + +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. + +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. + +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. + +As well as my personal website, I've been using Astro for some other mini-projects including [building Bootstrap components with Tailwind](https://www.oliverdavies.uk/archive/2023/01/22/building-bootstrap-css-examples-with-tailwind), and I'm using it for the updated examples for my Tailwind CSS talk at nor(DEV):con in a couple of weeks time. diff --git a/source/_daily_emails/2023-02-08.md b/source/_daily_emails/2023-02-08.md new file mode 100644 index 000000000..30ad51b86 --- /dev/null +++ b/source/_daily_emails/2023-02-08.md @@ -0,0 +1,15 @@ +--- +title: > + Fetching external API data with Astro +pubDate: 2023-02-08 +permalink: >- + archive/2023/02/08/fetching-api-data-with-astro +tags: + - astro +--- + +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. + +Astro's [Data Fetching documentation](https://docs.astro.build/en/guides/data-fetching) shows how to do this using the global `fetch` function. This is the same approach that I've been using to build [a page of my open-source projects](https://github.com/opdavies/oliverdavies.uk/blob/39314de34ce22b14cf85f816e4469cc4d6fb822c/website/src/pages/open-source.astro). I'm still working on it, but it fetches project information from both Drupal.org and GitHub and displays them on a page. + +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. diff --git a/source/_daily_emails/2023-02-09.md b/source/_daily_emails/2023-02-09.md new file mode 100644 index 000000000..37ef8af57 --- /dev/null +++ b/source/_daily_emails/2023-02-09.md @@ -0,0 +1,35 @@ +--- +title: > + Creating API endpoints with Astro +pubDate: 2023-02-09 +permalink: >- + archive/2023/02/09/creating-api-endpoints-with-astro +tags: + - astro +--- + +As well as [fetching API data](https://www.oliverdavies.uk/archive/2023/02/08/fetching-api-data-with-astro), you can also use Astro to generate your own API endpoints. + +This is an example of an endpoint that I recently created as part of a demo application: + +```javascript +// trains.json.ts + +import data from "@/data.json"; +import type { APIRoute } from "astro"; +import type { Train } from "@/types"; + +export const get: APIRoute = () => { + return { + body: JSON.stringify(data.trains as Train[]), + }; +}; +``` + +The train data is imported from a JSON file, and Astro's `APIRoute` is responsible for setting the appropriate response headers. + +For server-side rendered applications, you can also have endpoints for `post`, `del` and `all`, though for this example, I only needed to support GET requests. + +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. + +And, as the example application that consumes the data is also written with Astro, having them both using the same solution has advantages too. diff --git a/source/_daily_emails/2023-02-16.md b/source/_daily_emails/2023-02-16.md new file mode 100644 index 000000000..c3bda7c5e --- /dev/null +++ b/source/_daily_emails/2023-02-16.md @@ -0,0 +1,20 @@ +--- +title: > + Tailwind CSS at the Bristol Software Development Meetup +pubDate: 2023-02-16 +permalink: >- + archive/2023/02/16/tailwind-css-at-the-bristol-software-development-meetup +tags: + - public-speaking + - tailwind-css +--- + +Tonight I was lucky to speak at the first [Bristol Software Development Meetup event](https://www.meetup.com/south-wales-tech/events/291092930), organised by South Wales Tech. + +Following a great talk from Tom Vaughan, I gave an updated version of my [Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css) talk. + +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. + +I was also able to show my recent [Tailwind versions of Bootstrap components](https://bootstrap-with-tailwind.oliverdavies.uk) as a demonstration at the end of the talk. + +I'm glad to have had the opportunity to test out the updated version before [Norfolk Developers conference](https://nordevcon.com) next week and I'm looking forward to attending more South Wales Tech events in Swansea and Bristol in the future. diff --git a/source/_daily_emails/2023-02-17.md b/source/_daily_emails/2023-02-17.md new file mode 100644 index 000000000..abae15b77 --- /dev/null +++ b/source/_daily_emails/2023-02-17.md @@ -0,0 +1,19 @@ +--- +title: > + Upgrading my Drupal example project to Drupal 10 +pubDate: 2023-02-17 +permalink: >- + archive/2023/02/17/upgrading-my-drupal-example-project-to-drupal-10 +tags: + - docker + - drupal + - open-source +--- + +Today I upgraded my [Drupal Docker example](https://github.com/opdavies/docker-examples/tree/main/drupal) to Drupal 10. + +Admittedly, it's a simple project, but upgrading from Drupal 9 to 10 was a straightforward process. + +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 `composer.json` file and run the `composer update` command. + +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. diff --git a/source/_daily_emails/2023-02-18.md b/source/_daily_emails/2023-02-18.md new file mode 100644 index 000000000..92957c2d8 --- /dev/null +++ b/source/_daily_emails/2023-02-18.md @@ -0,0 +1,18 @@ +--- +title: > + Creating a Drupal 10 compatible version of Override Node Options +pubDate: 2023-02-18 +permalink: >- + archive/2023/02/18/drupal-10-version-of-override-node-options +tags: + - drupal + - open-source +--- + +Today, I reviewed [the issue and merge request](https://www.drupal.org/project/override_node_options/issues/3269901) to make the [Override Node Options](https://www.drupal.org/project/override_node_options) module compatible with Drupal 10. + +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. + +As well as the automated tests, I've done some manual testing with the patch applied on both Drupal 9.5 and 10. + +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. diff --git a/source/_daily_emails/2023-02-19.md b/source/_daily_emails/2023-02-19.md new file mode 100644 index 000000000..b6eb965de --- /dev/null +++ b/source/_daily_emails/2023-02-19.md @@ -0,0 +1,17 @@ +--- +title: > + Clients dont care which design pattern you use +pubDate: 2023-02-19 +permalink: >- + archive/2023/02/19/clients-dont-care-which-design-pattern-you-use +--- + +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. + +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? + +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? + +Can you ship a simple MVP sooner, and refactor to use design patterns later? + +Instead of focusing on technologies, tools and strategies, focus on the benefits and business value they can offer. diff --git a/source/_daily_emails/2023-02-20.md b/source/_daily_emails/2023-02-20.md new file mode 100644 index 000000000..d98ed0d81 --- /dev/null +++ b/source/_daily_emails/2023-02-20.md @@ -0,0 +1,56 @@ +--- +title: > + Tailwind: why I prefer to extract HTML components +pubDate: 2023-02-20 +permalink: >- + archive/2023/02/20/tailwind-why-i-prefer-to-extract-html-components +tags: + - tailwind-css +--- + +Tailwind offers the @apply directive that you can use to extract components in your CSS by applying the styles the classes would have added. + +For example: + +```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)); +} +``` + +Whilst this works and reduced duplication, I prefer to handle this within my HTML instead. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-03-01.md b/source/_daily_emails/2023-03-01.md new file mode 100644 index 000000000..1103d288f --- /dev/null +++ b/source/_daily_emails/2023-03-01.md @@ -0,0 +1,18 @@ +--- +title: > + Tailwind CSS at the Norfolk Developer Conference +pubDate: 2023-03-01 +permalink: >- + archive/2023/03/01/tailwind-css-at-the-norfolk-developer-conference +tags: + - speaking + - tailwind-css +--- + +Last week, I was at the Norfolk Developer's Conference, aka `nor(DEV):con` - my first in-person conference since DrupalCamp London in February 2020. + +I've been excited about this conference since I received the acceptance email in November, inviting me to give my [Taking Flight with Tailwind CSS](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css) talk. + +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. + +My next talk will be at the PHP London meetup next month (subject TBC) as I continue working towards my hundredth presentation. diff --git a/source/_daily_emails/2023-03-02.md b/source/_daily_emails/2023-03-02.md new file mode 100644 index 000000000..09c70959d --- /dev/null +++ b/source/_daily_emails/2023-03-02.md @@ -0,0 +1,14 @@ +--- +title: > + Busy working on client projects +pubDate: 2023-03-02 +permalink: >- + archive/2023/03/02/busy-working-on-client-projects +tags: [] +--- + +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. + +This has affected me sending out these emails every day and I missed a few days last month. + +I'll do better! diff --git a/source/_daily_emails/2023-03-03.md b/source/_daily_emails/2023-03-03.md new file mode 100644 index 000000000..75fe290f5 --- /dev/null +++ b/source/_daily_emails/2023-03-03.md @@ -0,0 +1,20 @@ +--- +title: > + Adding a LocalGov Drupal example +pubDate: 2023-03-03 +permalink: >- + archive/2023/03/03/adding-a-localgov-drupal-example +tags: + - drupal + - localgov-drupal +--- + +After [previously looking at the LocalGov Drupal distribution](https://www.oliverdavies.uk/archive/2022/10/24/looking-at-localgov-drupal), today I added a LocalGov Drupal example to my [Docker Examples repository](https://github.com/opdavies/docker-examples/tree/main/drupal-localgov). + +Based on the Drupal 10 example, the LocalGov Drupal example used Composer's `create-project` command to scaffold the project plus some additional configuration files such as the `Dockerfile`, `docker-compose.yaml` and a `justfile`. + +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. + +I have some issues for examples and enhancements to add within [the repository's issue queue](https://github.com/opdavies/docker-examples/issues) and would welcome any suggestions or questions. + +For LocalGov itself, I hope to find more opportunities to use and contribute to it in the future. diff --git a/source/_daily_emails/2023-03-04.md b/source/_daily_emails/2023-03-04.md new file mode 100644 index 000000000..3cda53fcb --- /dev/null +++ b/source/_daily_emails/2023-03-04.md @@ -0,0 +1,19 @@ +--- +title: > + Why I built a tool to generate configuration files +pubDate: 2023-03-04 +permalink: >- + archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files +--- + +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 `justfile` for running tasks, and for PHP projects, I need configuration files for tools like PHPStan, PHPCS and PHPUnit. + +The majority of those files are the same with some slight configuration for each project - such as whether it uses `web` or `docroot`, or which paths are checked with static analysis or for coding standards issues. + +I've given a talk called [Working with Workspace](https://www.oliverdavies.uk/talks/working-with-workspace) - 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. + +I use a `justfile` to execute tasks and commands but needed to write my own tool to generate the configuration files. + +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. + +As well as being faster to set up a project, like a [LocalGov Drupal Docker example](https://github.com/opdavies/docker-examples/tree/main/drupal-localgov), 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. diff --git a/source/_daily_emails/2023-03-05.md b/source/_daily_emails/2023-03-05.md new file mode 100644 index 000000000..de0091c42 --- /dev/null +++ b/source/_daily_emails/2023-03-05.md @@ -0,0 +1,18 @@ +--- +title: > + Mentoring for School of Code +pubDate: 2023-03-05 +permalink: >- + archive/2023/03/05/mentoring-for-school-of-code +tags: [] +--- + +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 [School of Code](https://www.schoolofcode.co.uk). + +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. + +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. + +This week is the mentor kick-off session, with the new cohort starting next week. + +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. diff --git a/source/_daily_emails/2023-03-08.md b/source/_daily_emails/2023-03-08.md new file mode 100644 index 000000000..d37a58605 --- /dev/null +++ b/source/_daily_emails/2023-03-08.md @@ -0,0 +1,19 @@ +--- +title: > + Automating infrastructure with IaC +pubDate: 2023-03-08 +permalink: >- + archive/2023/03/08/automating-infrastructure-with-iac +tags: + - devops +--- + +Are you responsible for creating and maintaining resources like GitHub repositories, DigitalOcean servers, Amazon S3 buckets and Cloudfront distributions or DNS records in Cloudflare? + +Do you do that through the various web UIs? + +I'd recommend looking into infrastructure as code tools such as Ansible, Terraform and Pulumi. + +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. + +Infrastructure as code (IaC) tools are something that I use when working with infrastructure, whether it's for a client project or [a talk demo](https://github.com/opdavies/rebuilding-acquia/blob/4efe94398f4d8715d22ca677756beb36017d4e74/main.tf) (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). diff --git a/source/_daily_emails/2023-03-09.md b/source/_daily_emails/2023-03-09.md new file mode 100644 index 000000000..109d9e3ff --- /dev/null +++ b/source/_daily_emails/2023-03-09.md @@ -0,0 +1,18 @@ +--- +title: > + In what language should I write my automation? +pubDate: 2023-03-09 +permalink: >- + archive/2023/03/09/in-what-language-should-i-write-my-automation +# tags: +# - a +# - b +--- + +Of the three tools I mentioned in yesterday's email - Ansible, Terraform and Pulumi - I mostly use Pulumi these days for writing automation code. + +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. + +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. + +If you prefer those other languages, why not give Pulumi a try with it? diff --git a/source/_daily_emails/2023-03-13.md b/source/_daily_emails/2023-03-13.md new file mode 100644 index 000000000..12c2a3750 --- /dev/null +++ b/source/_daily_emails/2023-03-13.md @@ -0,0 +1,16 @@ +--- +title: > + What problem are we trying to solve? +pubDate: 2023-03-13 +permalink: >- + archive/2023/03/13/what-problem-am-i-trying-to-solve +tags: [] +--- + +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. + +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. + +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. + +If there's no problem to solve, what's the reason for doing the work? diff --git a/source/_daily_emails/2023-03-14.md b/source/_daily_emails/2023-03-14.md new file mode 100644 index 000000000..71195c5e2 --- /dev/null +++ b/source/_daily_emails/2023-03-14.md @@ -0,0 +1,23 @@ +--- +title: > + Automating all the things +pubDate: 2023-03-14 +permalink: >- + archive/2023/03/14/automating-all-the-things +tags: + - automation +--- + +As a solo Developer and Consultant, I rely a lot on automation to get my tasks done. + +I use tools like [Pulumi, Ansible and Terraform](https://www.oliverdavies.uk/archive/2023/03/09/in-what-language-should-i-write-my-automation) to automate creating and configuring infrastructure - recently creating new client GitHub repositories using a standard configuration with Pulumi. + +I use Nix and Home Manager to automate my local development environment, install packages I need and create files like `.gitconfig` for my needs. These are reusable and stored in my [dotfiles](https://github.com/opdavies/dotfiles) repository. + +For projects, I use tools like Docker, Docker Compose and Nix flakes for consistency. + +[I wrote a tool for generating configuration files for each project](https://www.oliverdavies.uk/archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files) - 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. + +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. + +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. diff --git a/source/_daily_emails/2023-03-15.md b/source/_daily_emails/2023-03-15.md new file mode 100644 index 000000000..8a024aba3 --- /dev/null +++ b/source/_daily_emails/2023-03-15.md @@ -0,0 +1,19 @@ +--- +title: > + The benefits of automation +pubDate: 2023-03-15 +permalink: >- + archive/2023/03/15/the-benefits-of-automation +tags: + - automation +--- + +I've been working on a project with a client, using [Fractal](https://fractal.build) 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. + +I recently added `node` support to my [build configuration file generator](https://www.oliverdavies.uk/archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files) and used that to generate and use a consistent set of configuration files for a Fractal project. + +I've used Terraform in [some codebases](https://github.com/opdavies/rebuilding-acquia) 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. + +I use a `justfile` 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. + +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. diff --git a/source/_daily_emails/2023-03-21.md b/source/_daily_emails/2023-03-21.md new file mode 100644 index 000000000..f5e180f2e --- /dev/null +++ b/source/_daily_emails/2023-03-21.md @@ -0,0 +1,19 @@ +--- +title: > + There isn't a standard "Tailwind-looking" site +pubDate: 2023-03-21 +permalink: >- + archive/2023/03/21/there-isnt-a-tailwind-looking-site +tags: + - tailwind-css +--- + +When looking at some websites, you can tell that it was built using a certain CSS framework. + +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 ___. + +As Tailwind includes no components (other than the `container`) 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. + +There are some [examples of UIs that I've rebuilt](https://www.oliverdavies.uk/blog/uis-ive-rebuilt-tailwind-css) and some websites that I show in my [Taking Flight with Tailwind CSS talk](https://www.oliverdavies.uk/talks/taking-flight-with-tailwind-css). + +If you take a look, you'll see what I mean. diff --git a/source/_daily_emails/2023-03-22.md b/source/_daily_emails/2023-03-22.md new file mode 100644 index 000000000..9de7c6b50 --- /dev/null +++ b/source/_daily_emails/2023-03-22.md @@ -0,0 +1,20 @@ +--- +title: > + With utility styles, your CSS stops growing +pubDate: 2023-03-22 +permalink: >- + archive/2023/03/22/with-utility-styles-your-css-stops-growing +tags: + - css + - tailwind-css +--- + +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. + +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. + +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. + +With utility styles and frameworks like Tailwind CSS, this happens a lot less or sometimes not at all. + +If you need to use a class like `flex` or `grid` 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. diff --git a/source/_daily_emails/2023-03-27.md b/source/_daily_emails/2023-03-27.md new file mode 100644 index 000000000..f791d51d2 --- /dev/null +++ b/source/_daily_emails/2023-03-27.md @@ -0,0 +1,20 @@ +--- +title: > + Software development is about solving problems and adding value +pubDate: 2023-03-27 +permalink: >- + archive/2023/03/27/software-development-solving-problems-and-adding-value +# tags: +# - a +# - b +--- + +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. + +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. + +I've also said when speaking with a client this week that development is about adding business value. + +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. + +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. diff --git a/source/_daily_emails/2023-04-07.md b/source/_daily_emails/2023-04-07.md new file mode 100644 index 000000000..0278e1e10 --- /dev/null +++ b/source/_daily_emails/2023-04-07.md @@ -0,0 +1,17 @@ +--- +title: > + Speaking at PHP London +pubDate: 2023-04-07 +permalink: >- + archive/2023/04/07/speaking-at-php-london +tags: + - speaking +--- + +After a trip away with the family earlier this week, I was happy to speak at the PHP London meetup yesterday evening. + +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! + +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. + +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. diff --git a/source/_daily_emails/2023-04-08.md b/source/_daily_emails/2023-04-08.md new file mode 100644 index 000000000..e7e83e42a --- /dev/null +++ b/source/_daily_emails/2023-04-08.md @@ -0,0 +1,21 @@ +--- +title: > + Why I use tmux +pubDate: 2023-04-08 +permalink: >- + archive/2023/04/08/why-i-use-tmux +tags: + - tmux +--- + +tmux is a "terminal multiplexer" - a program that makes one terminal window into many. + +I use the terminal a lot and am often switching between codebase so this is very useful for me. + +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. + +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. + +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. + +Being able to organise my workspace in this way has become a big part blogof my development workflow and my productivity. diff --git a/source/_daily_emails/2023-04-09.md b/source/_daily_emails/2023-04-09.md new file mode 100644 index 000000000..b9e80ffad --- /dev/null +++ b/source/_daily_emails/2023-04-09.md @@ -0,0 +1,22 @@ +--- +title: > + Nix, NixOS, Home Manager, and WSL2 +pubDate: 2023-04-09 +permalink: >- + archive/2023/04/09/nix-nixos-home-manager-and-wsl2 +tags: + - linux + - nix + - nixos + - wsl2 +--- + +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. + +My current daily driver laptop is a Tuxedo InfinityBook that I've installed NixOS on. + +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 `nixpkgs` repository and can still install and manage them, but also does a lot more including managing hardware. + +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 `.gitconfig` and linking them to the required destination. + +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. diff --git a/source/_daily_emails/2023-04-10.md b/source/_daily_emails/2023-04-10.md new file mode 100644 index 000000000..bc08612e4 --- /dev/null +++ b/source/_daily_emails/2023-04-10.md @@ -0,0 +1,23 @@ +--- +title: > + How I use Neovim for writing PHP +pubDate: 2023-04-10 +permalink: >- + archive/2023/04/10/how-i-use-neovim-for-writing-php +tags: + - neovim + - php + - vim +--- + +Since [July 2021](https://www.oliverdavies.uk/blog/going-full-vim), I've used Neovim full-time for my development work and writing. + +Whilst Vim and Neovim are minimal by default, its functionality can be extended by adding plugins. + +I use nvim-lspconfig along with Intelephpense and Phpactor to add code actions and functionality like "go to definition" for PHP code. + +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. + +I use nvim-dap and nvim-dap-ui to leverage the debug adapter protocol to do step debugging with Xdebug. + +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. diff --git a/source/_daily_emails/2023-04-11.md b/source/_daily_emails/2023-04-11.md new file mode 100644 index 000000000..d6cbe14a7 --- /dev/null +++ b/source/_daily_emails/2023-04-11.md @@ -0,0 +1,57 @@ +--- +title: > + just vs make +pubDate: 2023-04-11 +permalink: >- + archive/2023/04/11/just-vs-make +tags: + - devops + - just + - make + - linux +--- + +`just` compared to `make` is something that was asked during my PHP London talk, and whilst they are similar, `just` has differences for me that explains why I use it: + +## Tabs or spaces + +A Makefile needs to use tabs. Justfiles are more flexible and work with tabs or any number of spaces. + +## .PHONY + +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 `make`, this is redundant and adds visual noise. + +## Passing arguments + +This is how a `composer` target looks like in a Makefile: + +```make +composer: + docker compose exec php composer +``` + +With this, I'd expect to be able to pass arguments to it - e.g. `make composer info drupal/core`. + +But, instead of seeing the expected output, I get an error: `make: *** No rule to make target 'info'.  Stop.`. + +This is what I'd need to do to pass arguments to the `composer` target: + +```make +composer: + docker compose exec php composer $(COMPOSER_ARGS) +``` + +Now I can run `make composer COMPOSER_ARGS="info drupal/core"` and see what I was expecting but the syntax isn't what I'd want. + +`just`, on the other hand, allows for defining parameters to its recipes: + +```yaml +composer *args: +  docker compose exec php composer {{ args }} +``` + +Here, I can create as many named parameters as needed and use them in the recipe with the syntax that I wanted - `just composer info drupal/core`. + +I can think of a few others but this is is the main reason why I moved from `make` and later adopted `just`. + +`just`, 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 `make`. diff --git a/source/_daily_emails/2023-04-12.md b/source/_daily_emails/2023-04-12.md new file mode 100644 index 000000000..7c717dd69 --- /dev/null +++ b/source/_daily_emails/2023-04-12.md @@ -0,0 +1,48 @@ +--- +title: > + Cleaner PHP code with promoted constructor properties +pubDate: 2023-04-12 +permalink: >- + archive/2023/04/12/cleaner-php-code-with-promoted-constructor-properties +tags: + - php +--- + +One of my favorite features that was introducted in PHP 8 was promoted constructor properties. + +If I'm passing arguments into a constructor, I can declare a visibility and it will be promoted to a property on the class. + +Here's an example of a value of a data transfer object that accepts a sort code and account number as strings: + +```php +class AccountDetails { + + public function __construct( + public string $accountNumber, + public string $sortCode, + ) {} + +} +``` + +Without promoted constructor properties, I'd need to create the properties and assign them manually, and I'd have this: + +```php +class AccountDetails { + + public string $accountNumber; + + public string $sortCode; + + public function __construct( + string $accountNumber, + string $sortCode, + ) { + $this->accountNumber = $accountNumber; + $this->sortCode = $sortCode; + } + +} +``` + +Whilst text editors and IDEs can create the properties automatically, I prefer this as it's less code, more readable and easier to understand. diff --git a/source/_daily_emails/2023-04-13.md b/source/_daily_emails/2023-04-13.md new file mode 100644 index 000000000..35034e35f --- /dev/null +++ b/source/_daily_emails/2023-04-13.md @@ -0,0 +1,35 @@ +--- +title: > + Immutable read-only properties in PHP 8.1 +pubDate: 2023-04-13 +permalink: >- + archive/2023/04/13/immutable-read-only-properties-in-php-8-1 +tags: + - php +--- + +Continuing with yesterday's data transfer object (DTO) example, something that can be done since PHP 8.1 is to make properties read-only: + +```php +class AccountDetails { + + public function __construct( + public readonly string $accountNumber, + public readonly string $sortCode, + ) {} + +} +``` + +This means the public properties can be read and used without the need for getter methods, but cannot be overridden - making the DTO immutable. + +Without `readonly`, a DTO can be created and the property values can be changed: + +```php +$accountDetails = new AccountDetails('12345678', '00-00-00'); +$accountDetails->accountNumber = 'banana'; +``` + +With `readonly` set, you'd get a fatal error instead: + +> Fatal error: Uncaught Error: Cannot modify readonly property AccountDetails::$accountNumber in /home/opdavies/tmp/example.php:13 diff --git a/source/_daily_emails/2023-04-14.md b/source/_daily_emails/2023-04-14.md new file mode 100644 index 000000000..17ec544a2 --- /dev/null +++ b/source/_daily_emails/2023-04-14.md @@ -0,0 +1,37 @@ +--- +title: > + Data transfer objects and value objects +pubDate: 2023-04-14 +permalink: >- + archive/2023/04/14/data-transfer-objects-and-value-objects +tags: [] +--- + +In the last few emails, we've seen a data transfer object called `AccountDetails` that stores the account number and sort code for a bank account. + +A data transfer object only stores data but we could also use a value object that can do more tasks, like validating the values. + +For example, we could validate that the account number is the correct length and the sort code is the correct format: + +```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'); + } + } + +} +``` + +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. diff --git a/source/_daily_emails/2023-04-15.md b/source/_daily_emails/2023-04-15.md new file mode 100644 index 000000000..b459898b0 --- /dev/null +++ b/source/_daily_emails/2023-04-15.md @@ -0,0 +1,27 @@ +--- +title: > + Automatically running commands with nodemon +pubDate: 2023-04-15 +permalink: >- + archive/2023/04/15/automatically-running-commands-with-nodemon +tags: [] +--- + +Instead of running the same commands over and over again, some of the command-line tools that I use have a `watch` mode and will automatically re-run when files are changed, however, not all do. + +Instead of doing this manually, I can achieve the same thing though using a tool called `nodemon` - a script monitor for node projects, but it can work with non-node projects too. + +Here's an example where I'm automatically re-running my PHPUnit tests using a `just test` recipe each time a file within my custom modules directory changes: + +``` +nodemon \ + --watch web/modules/custom \ + --ext '*' \ + --exec "just test --stop-on-failure --colors=always" +``` + +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. + +This watches all files and run all of the tests, but I can filter either if I need to. + +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. diff --git a/source/_daily_emails/2023-04-16.md b/source/_daily_emails/2023-04-16.md new file mode 100644 index 000000000..6399192d0 --- /dev/null +++ b/source/_daily_emails/2023-04-16.md @@ -0,0 +1,39 @@ +--- +title: > + Refactoring with readonly classes in PHP 8.2 +pubDate: 2023-04-16 +permalink: >- + archive/2023/04/16/refactoring-with-readonly-classes-in-php-8-2 +tags: + - php +--- + +Marian Kostadinov ([stochnagara on Twitter](https://twitter.com/stochnagara)) replied to Friday's email about DTOs and value objects to tell me about `readonly` classes, which can be done in PHP 8.2. + +Looking at the previous class: + +```php +class AccountDetails { + + public function __construct( + public readonly string $accountNumber, + public readonly string $sortCode, + ) {} + +} +``` + +Instead of setting each property as `readonly`, the whole class can instead be marked as `readonly`: + +```php +readonly class AccountDetails { + + public function __construct( + public string $accountNumber, + public string $sortCode, + ) {} + +} +``` + +Thanks for the suggestion, Marian! diff --git a/source/_daily_emails/2023-04-17.md b/source/_daily_emails/2023-04-17.md new file mode 100644 index 000000000..20a3d9a35 --- /dev/null +++ b/source/_daily_emails/2023-04-17.md @@ -0,0 +1,26 @@ +--- +title: > + Introducing feature flags to "build-configs" +pubDate: 2023-04-17 +permalink: >- + archive/2023/04/17/introducing-feature-flags-to-build-configs +tags: [] +--- + +Yesterday, I wanted to make a breaking change to my [build-configs project](https://www.oliverdavies.uk/archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files) - changing the default database credentials that are used by Docker Compose. + +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. + +## What did I do? + +To avoid this issue and needing to update all of my projects at once, I added a feature flag to the `build.yaml` file so I can opt-in to this feature on a per-project basis. + +If a project, like my [Drupal](https://github.com/opdavies/docker-example-drupal) and [LocalGov Drupal](https://github.com/opdavies/docker-example-drupal-localgov) Docker examples, are opted in, its files will get the new credentials. If not, it will continue to use the original ones. + +[In this commit](https://github.com/opdavies/docker-example-drupal/commit/3f496168d5c32f9706970519023b431ee02c4b19), you'll see where I enabled the feature flag and committed the resulting change. + +## What does this achieve? + +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. + +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. diff --git a/source/_daily_emails/2023-04-18.md b/source/_daily_emails/2023-04-18.md new file mode 100644 index 000000000..26292af6c --- /dev/null +++ b/source/_daily_emails/2023-04-18.md @@ -0,0 +1,23 @@ +--- +title: > + Consistency is key +pubDate: 2023-04-18 +permalink: >- + archive/2023/04/18/consistency-is-key +tags: + - automation + - devops + - docker +--- + +A side effect of [using a tool to generate build configuration files](https://www.oliverdavies.uk/archive/2023/03/04/why-i-built-a-tool-to-generate-configuration-files) with templates is the consistency that it introduces. + +The majority of my projects use a PHP-FPM or PHP CLI container. In my Docker Compose file, the service was mostly named `php` but sometimes it was `php-fpm`. In the templated file, it's always named `php`. + +Some projects would use `mysql` or `mariadb` for the database service and `nginx` or `caddy` depending on which server was being used. These are now always `database` and `web` respectively. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-04-19.md b/source/_daily_emails/2023-04-19.md new file mode 100644 index 000000000..e43592ec6 --- /dev/null +++ b/source/_daily_emails/2023-04-19.md @@ -0,0 +1,40 @@ +--- +title: > + Camel-case or snake-case for Drupal code? +pubDate: 2023-04-19 +permalink: >- + archive/2023/04/19/camel-case-or-snake-case-for-drupal-code +tags: + - drupal + - php +--- + +For some time, [Drupal's PHP coding standards](https://www.drupal.org/docs/develop/standards/php/php-coding-standards#s-functions-and-variables) allows for writing variables in either snake-case (e.g. `$my_variable`) or lower camel-case (`e.g. $myVariable`). + +It originally only allowed for snake-case variable names but once it accepted both, I switched to camel-case as my default. + +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). + +I'd have had code like this with a mixture of both: + +```php +class MyClass { + + private EntityTypeManagerInterface $entityTypeManager; + + public function __construct(EntityTypeManagerInterface $entity_type_manager) { + $this->entityTypeManager = $entity_type_manager; + } + +} +``` + +Or even more simply: + +```php +$entity_type_manager = \Drupal::entityTypeManager(); +``` + +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. + +Plus, I get to use new PHP features like [promoted constructor properties](https://www.oliverdavies.uk/archive/2023/04/12/cleaner-php-code-with-promoted-constructor-properties) if everything is named in the same format. diff --git a/source/_daily_emails/2023-04-20.md b/source/_daily_emails/2023-04-20.md new file mode 100644 index 000000000..b0e3a23f8 --- /dev/null +++ b/source/_daily_emails/2023-04-20.md @@ -0,0 +1,35 @@ +--- +title: > + Micro-refactorings +pubDate: 2023-04-20 +permalink: >- + archive/2023/04/20/micro-refactorings +tags: + - refactoring + - technical-debt + - programming +--- + +Today, I saw a [LinkedIn post by Peter Morlion](https://www.linkedin.com/posts/petermorlion_refactoring-technicaldebt-softwaredevelopment-activity-7054378097051095040-I545), 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. + +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. + +## What's the issue? + +I agree with what Peter says and also encourage people to make small refactors to the code they're working on and follow the "[Boy Scout rule](https://www.oliverdavies.uk/archive/2022/12/22/the-boy-scout-rule)". + +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. + +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. + +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. + +## What do I prefer to do? + +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. + +Instead of asynchronous code review, I prefer to pair- or mob-program or to rely on automation with CI/CD pipelines. + +If the commit before my change is passing the pipeline checks, and they're still passing after my change, they're good to deploy. + +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. diff --git a/source/_daily_emails/2023-04-21.md b/source/_daily_emails/2023-04-21.md new file mode 100644 index 000000000..d218f08a2 --- /dev/null +++ b/source/_daily_emails/2023-04-21.md @@ -0,0 +1,20 @@ +--- +title: > + Making my Drupal module template Drupal 10 compatible +pubDate: 2023-04-21 +permalink: >- + archive/2023/04/21/making-my-drupal-module-template-drupal-10-compatible +tags: + - drupal + - php +--- + +Today, I made my [Drupal module template](https://github.com/opdavies/drupal-module-template) compatible with Drupal 10. + +Because Drupal 10 is developed from Drupal 9, the changes between the two and the changes required are minimal. + +In this case, I only needed to change the `core_version_requirement` in `drupal_module_template.info.yml` from `^9` to `^9 || ^10` - meaning the template works for both Drupal 9 and 10, so there's no need for different versions. + +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. + +Updating to new major Drupal versions is much easier than it used to be! diff --git a/source/_daily_emails/2023-04-22.md b/source/_daily_emails/2023-04-22.md new file mode 100644 index 000000000..ba59e6dfa --- /dev/null +++ b/source/_daily_emails/2023-04-22.md @@ -0,0 +1,20 @@ +--- +title: > + Configuration files as a service +pubDate: 2023-04-22 +permalink: >- + archive/2023/04/22/build-configs-as-a-service +tags: + - development + - devops + - drupal + - php +--- + +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. + +I can provide an initial Drupal project skeleton built using `build-configs`, and for a recurring monthly amount, ongoing updates and unlimited support via Slack. + +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. + +See https://www.oliverdavies.uk/build-configs for more information and, as a list subscriber, use the code `dailyconfigs` to get an early-bird discount. diff --git a/source/_daily_emails/2023-04-23.md b/source/_daily_emails/2023-04-23.md new file mode 100644 index 000000000..7c2698db5 --- /dev/null +++ b/source/_daily_emails/2023-04-23.md @@ -0,0 +1,28 @@ +--- +title: > + Laravel Pipelines +pubDate: 2023-04-23 +permalink: >- + archive/2023/04/23/laravel-pipelines +tags: + - php + - laravel +--- + +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. + +This is an example from the new documentation: + +```php +$user = Pipeline::send($user) + ->through([ + GenerateProfilePhoto::class, + ActivateSubscription::class, + SendWelcomeEmail::class, + ]) + ->then(fn (User $user) => $user); +``` + +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. + +As someone who doesn't use Laravel often but does use standalone components - like `illuminate/collections` - in other PHP projects, I'm interested to see how I can use this via `illuminate/pipeline` to refactor some of my existing code. diff --git a/source/_daily_emails/2023-04-24.md b/source/_daily_emails/2023-04-24.md new file mode 100644 index 000000000..14eeb7696 --- /dev/null +++ b/source/_daily_emails/2023-04-24.md @@ -0,0 +1,33 @@ +--- +title: > + CI pipelines should start locally +pubDate: 2023-04-24 +permalink: >- + archive/2023/04/24/ci-pipelines-should-start-locally +tags: + - development + - devops + - git +--- + +This week, Solomon Hykes (@solomonstre on Twitter) said: + +> 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. + +## What does this mean? + +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. + +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. + +## My preferred solution + +My approach for this is using Git hooks - specifically on a pre-push event. + +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. + +They're easy to enable using a command like `git config core.hooksPath .githooks` (assuming the scripts are in a directory called `.githooks`), 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. + +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. + +[Here is Solomon's original tweet](https://twitter.com/solomonstre/status/1649118014594502656). diff --git a/source/_daily_emails/2023-04-25.md b/source/_daily_emails/2023-04-25.md new file mode 100644 index 000000000..cecb1d07f --- /dev/null +++ b/source/_daily_emails/2023-04-25.md @@ -0,0 +1,21 @@ +--- +title: > + Shortening the feedback loop even more +pubDate: 2023-04-25 +permalink: >- + archive/2023/04/25/shortening-the-feedback-loop-even-more +tags: + - development + - devops + - neovim +--- + +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. + +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. + +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. + +I also have another plugin - `null-ls.nvim` - that adds errors from command-line tools to Neovim's diagnostics list. + +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. diff --git a/source/_daily_emails/2023-04-26.md b/source/_daily_emails/2023-04-26.md new file mode 100644 index 000000000..45e9d18a0 --- /dev/null +++ b/source/_daily_emails/2023-04-26.md @@ -0,0 +1,56 @@ +--- +title: > + Structure a new test by writing comments first +pubDate: 2023-04-26 +permalink: >- + archive/2023/04/26/tdd-structure-a-new-test-by-writing-comments-first +tags: + - automated-testing + - test-driven-development +--- + +Test cases are usually split into two or three sections - "Arrange, Act, Assert" or "Given, When, Then". + +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. + +Then you perform an action on the subject under test and, finally, assert that the system is in the desired state. + +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. + +## Option 1 + +To help me get started, I'll sometimes write a test like this with placeholders to separate the test into its separate stages: + +```php +/** @test */ +function should_activate_a_pending_user(): void { + // Arrange. + + // Act. + + // Assert. +} +``` + +This makes me think about the different stages and what each might need to contain. + +## Option 2 + +Or I might write it out in the "Given, When, Then" format: + +```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'. +} +``` + +This takes a little longer to write but feels more familiar if you're used to a behavioural testing framework like Behat. + +Either way, sometimes, I'll remove the comments once I've written the code around them or leave them to provide additional context. diff --git a/source/_daily_emails/2023-04-27.md b/source/_daily_emails/2023-04-27.md new file mode 100644 index 000000000..0b8bfafd0 --- /dev/null +++ b/source/_daily_emails/2023-04-27.md @@ -0,0 +1,22 @@ +--- +title: > + Write the test backwards +pubDate: 2023-04-27 +permalink: >- + archive/2023/04/27/tdd-write-the-test-backwards +tags: + - automated-testing + - test-driven-development +--- + +When writing a test, something that I like to do is start by writing the first assertion first, and then work backwards. + +My first assertion might be `self::assertTrue($result)`. + +If I ran this test, it would fail because of the undefined `$result` variable - but it's clear to me what I need next by asking, "Where does `$result` come from?". + +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?". + +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. + +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. diff --git a/source/_daily_emails/2023-04-30.md b/source/_daily_emails/2023-04-30.md new file mode 100644 index 000000000..6696001ec --- /dev/null +++ b/source/_daily_emails/2023-04-30.md @@ -0,0 +1,15 @@ +--- +title: > + Will we see Drupal 7.100? +pubDate: 2023-04-30 +permalink: >- + archive/2023/04/30/will-we-see-drupal-7-100 +tags: + - drupal +--- + +Drupal 7, first released in January 2011, is now on version 7.97. + +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. + +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. diff --git a/source/_daily_emails/2023-05-01.md b/source/_daily_emails/2023-05-01.md new file mode 100644 index 000000000..96f723c1e --- /dev/null +++ b/source/_daily_emails/2023-05-01.md @@ -0,0 +1,31 @@ +--- +title: > + Should Drupal 7 support be extended again? +pubDate: 2023-05-01 +permalink: >- + archive/2023/05/01/should-drupal-7-support-be-extended-again +tags: + - drupal + - php + - phpc +--- + +Drupal 7, which was released in 2011, was originally supposed to be end-of-life in November 2022. + +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. + +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. + +There are still over 425,000 active Drupal 7 websites according to - almost 100,000 fewer than Feburary 2022. That's still a lot of websites! + +Should support be extended again or should Drupal 7 be marked as end-of-life and unsupported? + +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. + +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. + +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. + +Hit reply and let me know what you think. + +P.S. Are you still using Drupal 7 and don’t know what’s involved to upgrade to Drupal 10? Book a [Drupal 7 upgrade consultation call](https://www.oliverdavies.uk/call). diff --git a/source/_daily_emails/2023-05-02.md b/source/_daily_emails/2023-05-02.md new file mode 100644 index 000000000..1c6f7e5ef --- /dev/null +++ b/source/_daily_emails/2023-05-02.md @@ -0,0 +1,25 @@ +--- +title: > + Does it depend on who you ask? +pubDate: 2023-05-02 +permalink: >- + archive/2023/05/02/does-it-depend-on-who-you-ask +tags: + - drupal + - php + - phpc +--- + +The answer to "[Should Drupal 7 support be extended again?](https://www.oliverdavies.uk/archive/2023/05/01/should-drupal-7-support-be-extended-again)" might depend on who you ask. + +If you ask a Developer or agency, the answer would likely be that it shouldn't be extended again, and D7 should be sunsetted. + +Clients and end-users who haven't yet upgraded would likely say it should be extended. + +But if it's extended - and maybe again next year and the next - where's the incentive to upgrade? + +Some people won't upgrade regardless and will continue until their site breaks. + +That would be messy (and costly) to fix, though! + +P.S. Are you still using Drupal 7 and don’t know what’s involved to upgrade to Drupal 10? Book a [Drupal 7 upgrade consultation call](https://www.oliverdavies.uk/call). diff --git a/source/_daily_emails/2023-05-03.md b/source/_daily_emails/2023-05-03.md new file mode 100644 index 000000000..9515f09d8 --- /dev/null +++ b/source/_daily_emails/2023-05-03.md @@ -0,0 +1,25 @@ +--- +title: > + Just because core is supported... +pubDate: 2023-05-03 +permalink: >- + archive/2023/05/03/just-because-core-is-supported +tags: + - drupal + - php + - phpc +--- + +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. + +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. + +Whilst it isn't marked as unsupported, it isn't being updated either. + +I recently explained to a client that their site uses a module last released in 2014. It’s buggy, but there’s no newer version to use and issues in the queue are no longer being fixed or triaged. + +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. + +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. + +Meanwhile, Drupal 7 core is still supported, at least for now. diff --git a/source/_daily_emails/2023-05-04.md b/source/_daily_emails/2023-05-04.md new file mode 100644 index 000000000..e2d392827 --- /dev/null +++ b/source/_daily_emails/2023-05-04.md @@ -0,0 +1,21 @@ +--- +title: > + Speaking at the Symfony UK meetup in London +pubDate: 2023-05-04 +permalink: >- + archive/2023/05/04/speaking-at-the-symfony-uk-meetup-london +tags: + - speaking + - mob-programming + - php + - phpc + - symfony +--- + +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. + +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. + +If you're interested and in London on the 11th of May, [find out more and register](https://www.meetup.com/symfony/events/293153957). + +Also, Happy Star Wars Day! diff --git a/source/_daily_emails/2023-05-05.md b/source/_daily_emails/2023-05-05.md new file mode 100644 index 000000000..a062aaa3a --- /dev/null +++ b/source/_daily_emails/2023-05-05.md @@ -0,0 +1,19 @@ +--- +title: > + Getting to green +pubDate: 2023-05-05 +permalink: >- + archive/2023/05/05/getting-to-green +tags: + - automated-testing + - testing + - test-driven development +--- + +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. + +Even if that means returning a hard-coded value. + +Once the test passes, it or the code it's testing can be refactored. + +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. diff --git a/source/_daily_emails/2023-05-06.md b/source/_daily_emails/2023-05-06.md new file mode 100644 index 000000000..613ff8ffe --- /dev/null +++ b/source/_daily_emails/2023-05-06.md @@ -0,0 +1,21 @@ +--- +title: > + Why it's important to see the test fail +pubDate: 2023-05-06 +permalink: >- + archive/2023/05/06/why-its-important-to-see-the-test-fail +tags: + - automated-testing + - test-driven-development +--- + +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. + +If the functionality already exists, do you need another test for it? + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-05-07.md b/source/_daily_emails/2023-05-07.md new file mode 100644 index 000000000..d5eb4f176 --- /dev/null +++ b/source/_daily_emails/2023-05-07.md @@ -0,0 +1,20 @@ +--- +title: > + You don't need to think about what to do next +pubDate: 2023-05-07 +permalink: >- + archive/2023/05/07/you-dont-need-to-think-about-what-to-do-next +tags: + - automated-testing + - test-driven-development +--- + +When practising test-driven development, you don't need to think about what to do next. + +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. + +It could be a failing assertion, an undefined variable or function, or a yet-to-be-implemented service. + +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. + +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. diff --git a/source/_daily_emails/2023-05-08.md b/source/_daily_emails/2023-05-08.md new file mode 100644 index 000000000..c58e19453 --- /dev/null +++ b/source/_daily_emails/2023-05-08.md @@ -0,0 +1,16 @@ +--- +title: > + Only write enough code to get a failing test +pubDate: 2023-05-08 +permalink: >- + archive/2023/05/08/only-write-enough-code-to-get-a-failing-test +tags: + - automated-testing + - test-driven-development +--- + +Instead of writing a whole test and then attempting to make it pass, only write enough code to get the test to fail. + +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. + +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. diff --git a/source/_daily_emails/2023-05-09.md b/source/_daily_emails/2023-05-09.md new file mode 100644 index 000000000..3f3dcd1cb --- /dev/null +++ b/source/_daily_emails/2023-05-09.md @@ -0,0 +1,20 @@ +--- +title: > + The single responsibility principle +pubDate: 2023-05-09 +permalink: >- + archive/2023/05/09/the-single-responsibility-principle +tags: [] +--- + +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. + +I've already implemented this for other node types but needed to do the same for this node type. + +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. + +To do this, I needed to add a custom block and form, update the `AutocompleteController`, create a new instance of a `NodeQuery` class (a custom class within the custom module), register it as a service and update the `SearchQueryFactory` class. + +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. + +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. diff --git a/source/_daily_emails/2023-05-10.md b/source/_daily_emails/2023-05-10.md new file mode 100644 index 000000000..3a201cc77 --- /dev/null +++ b/source/_daily_emails/2023-05-10.md @@ -0,0 +1,18 @@ +--- +title: > + Tailwind CSS makes change easier +pubDate: 2023-05-10 +permalink: >- + archive/2023/05/10/tailwind-css-makes-change-easier +tags: + - css + - tailwind-css +--- + +CSS usually has a global scope which can make change risky. + +How do you know that changing CSS in a global stylesheet to fix a bug won't cause more elsewhere? + +Tailwind CSS and utility classes change CSS to a local scope. + +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. diff --git a/source/_daily_emails/2023-05-11.md b/source/_daily_emails/2023-05-11.md new file mode 100644 index 000000000..1ce45d479 --- /dev/null +++ b/source/_daily_emails/2023-05-11.md @@ -0,0 +1,18 @@ +--- +title: > + Why I like pair and mob programming +pubDate: 2023-05-11 +permalink: >- + archive/2023/05/11/why-i-like-pair-and-mob-programming +tags: + - pair-programming + - mob-programming +--- + +When working as part of a team, I like to do pair or mob programming as much as possible. + +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. + +Working in pairs or a mob is a great opportunity to onboard new team members, train and mentor, and share tips and tricks. + +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. diff --git a/source/_daily_emails/2023-05-12.md b/source/_daily_emails/2023-05-12.md new file mode 100644 index 000000000..a386d4dd2 --- /dev/null +++ b/source/_daily_emails/2023-05-12.md @@ -0,0 +1,18 @@ +--- +title: > + Always listen to the mob +pubDate: 2023-05-12 +permalink: >- + archive/2023/05/12/always-listen-to-the-mob +tags: + - pair-programming + - mob-programming +--- + +Something I'm aware of when working in a pair or mob is to always listen to input from other team members. + +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. + +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. + +Together, you will come up with the best solution - even if it's different from what you had in mind to begin with. diff --git a/source/_daily_emails/2023-05-13.md b/source/_daily_emails/2023-05-13.md new file mode 100644 index 000000000..06d4bbb26 --- /dev/null +++ b/source/_daily_emails/2023-05-13.md @@ -0,0 +1,19 @@ +--- +title: > + When You Do Things Right, People Won't Be Sure You've Done Anything at All +pubDate: 2023-05-13 +permalink: >- + archive/2023/05/13/when-you-do-things-right +tags: + - software-development +--- + +I think this quote from Futurama also applies well to software development: + +> When You Do Things Right, People Won’t Be Sure You’ve Done Anything at All + +Today I did multiple releases to production websites. There were no outages or downtime, or messages from clients or colleagues. + +Processes were followed, and everything worked as it should. As far as everyone's concerned, everything still "just works". + +So, did I do anything at all? diff --git a/source/_daily_emails/2023-05-14.md b/source/_daily_emails/2023-05-14.md new file mode 100644 index 000000000..e42418235 --- /dev/null +++ b/source/_daily_emails/2023-05-14.md @@ -0,0 +1,17 @@ +--- +title: > + Releasing small changes often is less risky +pubDate: 2023-05-14 +permalink: >- + archive/2023/05/14/releasing-small-changes-often-is-less-risky +tags: + - software-development +--- + +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. + +If there is an issue after a large release, diagnosing and fixing it can take longer than a smaller release with fewer changes. + +You might have to revert and roll back to the previous release instead of being able to push a fix for a small change. + +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. diff --git a/source/_daily_emails/2023-05-15.md b/source/_daily_emails/2023-05-15.md new file mode 100644 index 000000000..bd008b204 --- /dev/null +++ b/source/_daily_emails/2023-05-15.md @@ -0,0 +1,29 @@ +--- +title: > + Is the Drupal release cycle too fast? +pubDate: 2023-05-15 +permalink: >- + archive/2023/05/15/is-the-drupal-release-cycle-too-fast +tags: + - drupal + - php + - phpc +--- + +Compared to Drupal 7, [which is almost at version 100](https://oliverdavies.dev/archive/2023/04/30/will-we-see-drupal-7-100), the release cycle from Drupal 9 onwards has been quite different. + +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. + +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. + +But is it too quick, as someone asked on Twitter? + +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. + +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 `core_version_requirement` key to include the new version. + +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. + +The same applies to any custom code within website projects, not just contributed modules and themes. + +The more often you maintain and update what you have; the easier it will be. diff --git a/source/_daily_emails/2023-05-16.md b/source/_daily_emails/2023-05-16.md new file mode 100644 index 000000000..0746538d1 --- /dev/null +++ b/source/_daily_emails/2023-05-16.md @@ -0,0 +1,19 @@ +--- +title: > + Mastering your tools improves productivity +pubDate: 2023-05-16 +permalink: >- + archive/2023/05/16/mastering-your-tools-improves-productivity +tags: + - software-development +--- + +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. + +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. + +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. + +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. + +As someone said in a video recently, "you invest time now to buy back time later". diff --git a/source/_daily_emails/2023-05-17.md b/source/_daily_emails/2023-05-17.md new file mode 100644 index 000000000..74a767550 --- /dev/null +++ b/source/_daily_emails/2023-05-17.md @@ -0,0 +1,34 @@ +--- +title: > + What is deprecated code? +pubDate: 2023-05-17 +permalink: >- + archive/2023/05/17/what-is-deprecated-code +tags: + - php + - drupal + - software-development +--- + +Deprecating code is a way of identifying code that will be removed in a future major version. + +For example, the `drupal_set_message()` function was deprecated in Drupal 8.5 and removed in Drupal 9 as the `messenger` service replaced it. + +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: + +```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->addMessage($message, $type, $repeat); + } + + return $messenger->all(); +} +``` + +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 `drupal_set_message()` just needed to be updated to use the new Messenger service. + +No large rewrite needed! diff --git a/source/_daily_emails/2023-05-18.md b/source/_daily_emails/2023-05-18.md new file mode 100644 index 000000000..b322ad209 --- /dev/null +++ b/source/_daily_emails/2023-05-18.md @@ -0,0 +1,17 @@ +--- +title: > + Why is backward compatibility important? +pubDate: 2023-05-18 +permalink: >- + archive/2023/05/18/why-is-backward-compatibility-important +tags: + - software-development +--- + +In yesterday's email, I mentioned that deprecating code allows it to be backwards compatible - but what does that mean? + +If I were to remove a function like `drupal_set_message()` that is used code elsewhere in an application, the code would no longer work and would break. + +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"). + +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. diff --git a/source/_daily_emails/2023-05-19.md b/source/_daily_emails/2023-05-19.md new file mode 100644 index 000000000..1bdfebad2 --- /dev/null +++ b/source/_daily_emails/2023-05-19.md @@ -0,0 +1,19 @@ +--- +title: > + Semantic versioning +pubDate: 2023-05-19 +permalink: >- + archive/2023/05/19/semantic-versioning +tags: + - software-development +--- + +The version number of a release is a key indicator of whether it’s compatible with existing code. + +Semantic versioning is a popular approach used by Drupal core, and many contributed modules, themes and distributions. + +It uses version numbers like 1.0.0 to show the major, minor and patch versions. + +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’s safe to update. + +If the first number changes, e.g. 2.0.0, the release is not backwards compatible and contains breaking changes that you’ll need to review and update your code accordingly. diff --git a/source/_daily_emails/2023-05-20.md b/source/_daily_emails/2023-05-20.md new file mode 100644 index 000000000..5d66338f2 --- /dev/null +++ b/source/_daily_emails/2023-05-20.md @@ -0,0 +1,19 @@ +--- +title: > + A minor breaking change +pubDate: 2023-05-20 +permalink: >- + archive/2023/05/20/a-minor-breaking-change +tags: + - software-development +--- + +Today, in the repository of an open-source project, I saw an issue comment saying, "This is a minor breaking change.". + +It detailed what was removed and suggested an alternative. + +I don't know how you define a "minor" breaking change. + +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? + +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. diff --git a/source/_daily_emails/2023-05-21.md b/source/_daily_emails/2023-05-21.md new file mode 100644 index 000000000..98bced6af --- /dev/null +++ b/source/_daily_emails/2023-05-21.md @@ -0,0 +1,19 @@ +--- +title: > + Drupal 9: almost end-of-life already +pubDate: 2023-05-21 +permalink: >- + archive/2023/05/21/drupal-9-almost-end-of-life-already +tags: + - drupal + - php + - phpc +--- + +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. + +This is because of its dependency on Symfony 4, which is ending its security support in November. + +Drupal 10 was released in December 2022 and will be the main version until Drupal 11 is released in 2024. + +Luckily, major upgrades of Drupal are much easier these days, with no large code rewrite or data migration required. diff --git a/source/_daily_emails/2023-06-05.md b/source/_daily_emails/2023-06-05.md new file mode 100644 index 000000000..d319977f1 --- /dev/null +++ b/source/_daily_emails/2023-06-05.md @@ -0,0 +1,19 @@ +--- +title: > + How long should a feature flag live? +pubDate: 2023-06-05 +permalink: >- + archive/2023/06/05/how-long-should-a-feature-flag-live +tags: + - software-development + - software-engineering + - feature-flags +--- + +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. + +Being able to release changes incrementally lowers the risk compared to releasing a large change all at once. + +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. + +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. diff --git a/source/_daily_emails/2023-06-06.md b/source/_daily_emails/2023-06-06.md new file mode 100644 index 000000000..5b07f60fb --- /dev/null +++ b/source/_daily_emails/2023-06-06.md @@ -0,0 +1,19 @@ +--- +title: > + Drupal 7 end-of-life extended +pubDate: 2023-06-06 +permalink: >- + archive/2023/06/06/drupal-7-end-of-life-extended +tags: + - drupal + - php + - phpc +--- + +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. + +Whilst there's no official announcement yet, it seems this is the final extension and will be when support ends. + +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. + +If you're still on Drupal 7 and need to learn more about upgrading to Drupal 10, [book an advisory call](https://www.oliverdavies.uk/call) or [an upgrade roadmap](https://www.oliverdavies.uk/drupal7) for your Drupal 7 project. diff --git a/source/_daily_emails/2023-06-07.md b/source/_daily_emails/2023-06-07.md new file mode 100644 index 000000000..be143977a --- /dev/null +++ b/source/_daily_emails/2023-06-07.md @@ -0,0 +1,27 @@ +--- +title: > + What does the Drupal 7 EOL extension mean to you? +pubDate: 2023-06-07 +permalink: >- + archive/2023/06/07/what-does-the-drupal-7-eol-extension-mean-to-you +tags: + - drupal + - drupal-7 + - php +--- + +Following the announcement at DrupalCon, the official announcement has been released regarding Drupal 7's end-of-life extension: + +> Today, we are officially announcing that Drupal 7 will reach its end of life on January 5, 2025. +> +> With this final extension, the Drupal Security Team is also adjusting the level of support provided. +> +> This will be the final extension. + +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? + +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? + +Is it different knowing it’s the final extension compared to the previous time when it wasn’t known if it would be extended again? + +If you're stuck on Drupal 7 or staying on it into 2024 or 2025, what's stopping you from upgrading? diff --git a/source/_daily_emails/2023-06-08.md b/source/_daily_emails/2023-06-08.md new file mode 100644 index 000000000..5eea8c479 --- /dev/null +++ b/source/_daily_emails/2023-06-08.md @@ -0,0 +1,18 @@ +--- +title: > + Write less Drupal code +pubDate: 2023-06-08 +permalink: >- + archive/2023/06/08/write-less-drupal-code +tags: + - drupal + - php +--- + +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. + +These could be in open-sourced packages installed from Packagist or kept within the same repository. + +Having less Drupal-specific code keeps modules smaller and easier to maintain and upgrade. + +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. diff --git a/source/_daily_emails/2023-06-09.md b/source/_daily_emails/2023-06-09.md new file mode 100644 index 000000000..8b5bc95c9 --- /dev/null +++ b/source/_daily_emails/2023-06-09.md @@ -0,0 +1,20 @@ +--- +title: > + Drupal is built by people +pubDate: 2023-06-09 +permalink: >- + archive/2023/06/09/drupal-is-built-by-people +tags: + - drupal + - php +--- + +A quote I heard from DrupalCon, made by my former colleague Tim Lehnen - CTO at the Drupal Association - when talking about contribution: + +> Contribution is what makes Drupal thrive. +> +> Drupal is built by people. +> +> No one entity, no one person builds Drupal. +> +> It's you who builds Drupal. diff --git a/source/_daily_emails/2023-06-10.md b/source/_daily_emails/2023-06-10.md new file mode 100644 index 000000000..c28ea50bb --- /dev/null +++ b/source/_daily_emails/2023-06-10.md @@ -0,0 +1,15 @@ +--- +title: > + How do you know when to remove a feature flag? +pubDate: 2023-06-10 +permalink: >- + archive/2023/06/10/how-do-you-know-when-to-remove-a-feature-flag +tags: + - feature-flags +--- + +But once a feature has been enabled, how do you know if you can remove its flag? + +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. + +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. diff --git a/source/_daily_emails/2023-06-11.md b/source/_daily_emails/2023-06-11.md new file mode 100644 index 000000000..10d492d00 --- /dev/null +++ b/source/_daily_emails/2023-06-11.md @@ -0,0 +1,14 @@ +--- +title: > + Failing fast +pubDate: 2023-06-11 +permalink: >- + archive/2023/06/11/failing-fast +tags: [] +--- + +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"? + +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. + +If it fails, your sunk cost is low as you've not invested much time, money or energy. diff --git a/source/_daily_emails/2023-06-12.md b/source/_daily_emails/2023-06-12.md new file mode 100644 index 000000000..aaea929b3 --- /dev/null +++ b/source/_daily_emails/2023-06-12.md @@ -0,0 +1,17 @@ +--- +title: > + Feature flags in a multi-tenancy application +pubDate: 2023-06-12 +permalink: >- + archive/2023/06/12/feature-flags-in-a-multi-tenancy-application +tags: + - feature-flags +--- + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-06-13.md b/source/_daily_emails/2023-06-13.md new file mode 100644 index 000000000..24bb49bd3 --- /dev/null +++ b/source/_daily_emails/2023-06-13.md @@ -0,0 +1,17 @@ +--- +title: > + Should you feature flag everything? +pubDate: 2023-06-13 +permalink: >- + archive/2023/06/13/should-you-feature-flag-everything +tags: + - feature-flags +--- + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-06-14.md b/source/_daily_emails/2023-06-14.md new file mode 100644 index 000000000..f4841f006 --- /dev/null +++ b/source/_daily_emails/2023-06-14.md @@ -0,0 +1,27 @@ +--- +title: > + What if there was no open-source software +pubDate: 2023-06-14 +permalink: >- + archive/2023/06/14/what-if-there-was-no-open-source-software +tags: + - open-source +--- + +I was listening to a podcast today, and the question was mentioned - "What if there was no open-source software?". + +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. + +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. + +There would be no reusable knowledge as Developers move to different companies as everything would be written in-house. + +There would be no communities and events like conferences and meetups for open-source technologies. + +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? + +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? + +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. + +If you use open-source software, please consider sponsoring, supporting or contributing to the projects you use and depend on. diff --git a/source/_daily_emails/2023-06-15.md b/source/_daily_emails/2023-06-15.md new file mode 100644 index 000000000..4ff00c6ba --- /dev/null +++ b/source/_daily_emails/2023-06-15.md @@ -0,0 +1,18 @@ +--- +title: > + Done is better than perfect +pubDate: 2023-06-15 +permalink: >- + archive/2023/06/15/done-is-better-than-perfect +tags: [] +--- + +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. + +Then, once this is done, I can pass through the code again and refactor it as needed. + +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. + +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. + +The main goal is to get the application working and providing value for its users. diff --git a/source/_daily_emails/2023-06-16.md b/source/_daily_emails/2023-06-16.md new file mode 100644 index 000000000..e8dac80fc --- /dev/null +++ b/source/_daily_emails/2023-06-16.md @@ -0,0 +1,20 @@ +--- +title: > + Make the change easy, then make the easy change +pubDate: 2023-06-16 +permalink: >- + archive/2023/06/16/make-the-easy-change +tags: [] +--- + +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..."? + +A quote by Kent Beck: + +> For each desired change, make the change easy (warning: this may be hard), then make the easy change + +If you can refactor the code and make it easier to implement your required change, do so. + +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. + +Then, go ahead and make the required change - add the feature or fix the bug - which should now be easy. diff --git a/source/_daily_emails/2023-06-17.md b/source/_daily_emails/2023-06-17.md new file mode 100644 index 000000000..67b4277b2 --- /dev/null +++ b/source/_daily_emails/2023-06-17.md @@ -0,0 +1,26 @@ +--- +title: > + Avoid Git merge hell with trunk-based development +pubDate: 2023-06-17 +permalink: >- + archive/2023/06/17/avoid-git-merge-hell-with-trunk-based-development +tags: + - git + - trunk-based-development +--- + +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 `main` or `develop`. + +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. + +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. + +## Trunk-based development + +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. + +As there are no feature branches, there are no merge conflicts when merging into mainline. + +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. + +It also stops me from breaking my environment during client demos! diff --git a/source/_daily_emails/2023-06-18.md b/source/_daily_emails/2023-06-18.md new file mode 100644 index 000000000..a124a007c --- /dev/null +++ b/source/_daily_emails/2023-06-18.md @@ -0,0 +1,28 @@ +--- +title: > + Are you really doing CI/CD? +pubDate: 2023-06-18 +permalink: >- + archive/2023/06/18/are-you-doing-ci-cd +tags: + - continuous-integration + - continuous-delivery + - continuous-deployment +--- + +Does your team really do CI/CD (continuous integration and delivery)? + +I recently watched a recording of a talk from another daily emailer, [Jonathan Hall](https://jhall.io), who started by asking the audience to raise their hands and keep them raised if... + +* They did a release to production in the last week. +* They did a release to production yesterday. +* They do not have a permanent branch called `develop`. +* They do not have a special "hotfix" procedure. +* Every Developer on their team merged work into `main` yesterday. +* They have no pull requests more than 24 hours old. + +## CI/CD is about process + +This is an excellent way to highlight that CI/CD is about processes, not technologies. + +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. diff --git a/source/_daily_emails/2023-06-19.md b/source/_daily_emails/2023-06-19.md new file mode 100644 index 000000000..dd848d2e0 --- /dev/null +++ b/source/_daily_emails/2023-06-19.md @@ -0,0 +1,38 @@ +--- +title: > + Should you upgrade from Drupal 7 to Drupal 10? +pubDate: 2023-06-19 +permalink: >- + archive/2023/06/19/should-you-upgrade-from-drupal-7-to-drupal-10 +tags: + - drupal + - drupal-7 +--- + +If you're stuck on Drupal 7, why should you upgrade to Drupal 10 instead of moving to another platform? + +## Familarity + +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. + +And whilst there have been differences since Drupal 8, creating modules and themes should seem familiar too with similar concepts such as `.info` files (now `.info.yml` files), hooks, preprocess functions and templates. + +## Code reuse + +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. + +## Built-in migration tools + +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. + +## New versions of existing modules + +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. + +## Conclusion + +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. + +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. + +If you have a reason, reply to let me know, and I'll post another list. diff --git a/source/_daily_emails/2023-06-20.md b/source/_daily_emails/2023-06-20.md new file mode 100644 index 000000000..0622562d8 --- /dev/null +++ b/source/_daily_emails/2023-06-20.md @@ -0,0 +1,29 @@ +--- +title: > + Should you deploy on a Friday? +pubDate: 2023-06-20 +permalink: >- + archive/2023/06/20/should-you-deploy-on-a-friday +tags: + - deployments +--- + +There's a common saying about not deploying changes on a Friday to prevent outages or issues before the weekend. + +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. + +## When did you last deploy? + +The longer it's been since the last deployment, the risker each deployment is. + +If there are weeks or months of changes, it will be risky regardless of which day it is. + +If your last deployment was an afternoon, deploying a small change the following morning will be low risk, even on a Thursday and Friday. + +## Conclusion + +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. + +The issue isn't when you're deploying. You likely need to do so more often. + +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. diff --git a/source/_daily_emails/2023-06-21.md b/source/_daily_emails/2023-06-21.md new file mode 100644 index 000000000..ae5e543d4 --- /dev/null +++ b/source/_daily_emails/2023-06-21.md @@ -0,0 +1,18 @@ +--- +title: > + Deployments or releases +pubDate: 2023-06-21 +permalink: >- + archive/2023/06/21/deployments-or-releases +tags: + - deployments + - releases +--- + +"Deployments" and "releases" are often used interchangeably but mean different things. + +A deployment moves a change from one place to another, such as some updated code from a staging environment to production. + +A release is when the change made is available to users. + +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. diff --git a/source/_daily_emails/2023-06-22.md b/source/_daily_emails/2023-06-22.md new file mode 100644 index 000000000..b90da02d5 --- /dev/null +++ b/source/_daily_emails/2023-06-22.md @@ -0,0 +1,14 @@ +--- +title: > + It's only a bad situation if you fail to learn from it +pubDate: 2023-06-22 +permalink: >- + archive/2023/06/22/fail-to-lear +tags: [] +--- + +I heard this on a non-tech podcast but it applies to tech too: + +> It's only a bad situation if you fail to learn from it + +Whether its a missed deadline, a failed deployment, a production outage or pushing a bug to production, there are opportunities to learn and improve. diff --git a/source/_daily_emails/2023-06-23.md b/source/_daily_emails/2023-06-23.md new file mode 100644 index 000000000..48993d1c4 --- /dev/null +++ b/source/_daily_emails/2023-06-23.md @@ -0,0 +1,39 @@ +--- +title: > + Why keep a Changelog? +pubDate: 2023-06-23 +permalink: >- + archive/2023/06/23/why-keep-a-changelog +tags: + - changelog +--- + + +## What is a Changelog? + +A Changelog is a file that documents changes made to a codebase. + +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. + +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. + +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. + + +## How is it structured? + +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! + +I like to follow a format called [Keep a Changelog](https://keepachangelog.com). + +The headings link to a diff so you can see all of the commits and changes made to the code, and there's an `Unreleased` section that shows commits that have yet to be tagged and released. + +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. + +## When should it be updated? + +I recommend continually updating the Changelog rather than leaving it to just before a deployment. It's quick to add it to the `Unreleased` section as part of the commit and update the headings later. + +## Can I see an example? + +Sure. See the one I added to the [National Rail Enquiries feed parser library](https://github.com/opdavies/national-rail-enquiries-feed-parser/blob/main/CHANGELOG.md) I've been working on or the [Tailwind CSS starter kit theme for Drupal](https://git.drupalcode.org/project/tailwindcss/-/blob/5.x/CHANGELOG.md). diff --git a/source/_daily_emails/2023-06-24.md b/source/_daily_emails/2023-06-24.md new file mode 100644 index 000000000..43c008852 --- /dev/null +++ b/source/_daily_emails/2023-06-24.md @@ -0,0 +1,24 @@ +--- +title: > + Credited on 200 fixed issues on Drupal.org +pubDate: 2023-06-24 +permalink: >- + archive/2023/06/24/credited-on-200-fixed-issues +tags: + - drupal + - open-source +--- + +While writing yesterday's email, I saw this on my Drupal.org profile (https://www.drupal.org/u/opdavies): + +> Credited on 200 fixed issues + +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". + +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. + +It also includes contrib projects others maintain, such as the Feature Toggle module and Drupal Commerce, and distributions like Commerce Kickstart and Open Atrium. + +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. + +I've been allocating more open-source time recently, so expect the number of contributions on Drupal.org and GitHub to continue. diff --git a/source/_daily_emails/2023-06-25.md b/source/_daily_emails/2023-06-25.md new file mode 100644 index 000000000..9ca8d39dc --- /dev/null +++ b/source/_daily_emails/2023-06-25.md @@ -0,0 +1,16 @@ +--- +title: > + Do you need permission to do Test-Driven Development? +pubDate: 2023-06-25 +permalink: >- + archive/2023/06/25/do-you-need-permission-test-driven-development +tags: + - automated-testing + - test-driven-development +--- + +Something I've been asked before is "Do you need permission to write automated tests or do Test-Driven Development?". + +A response I heard recently was "Does a surgeon ask if they can wash their hands before operating?". + +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. diff --git a/source/_daily_emails/2023-06-26.md b/source/_daily_emails/2023-06-26.md new file mode 100644 index 000000000..b9e79f53f --- /dev/null +++ b/source/_daily_emails/2023-06-26.md @@ -0,0 +1,17 @@ +--- +title: > + Is any code without tests legacy code? +pubDate: 2023-06-26 +permalink: >- + archive/2023/06/26/is-any-code-without-tests-legacy +tags: + - automated-testing +--- + +While I can't find the original quote, I've heard numerous people describe any code without automated tests as legacy. + +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. + +This is true for code that doesn't have accompanying automated tests, regardless of when it was written. + +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. diff --git a/source/_daily_emails/2023-06-27.md b/source/_daily_emails/2023-06-27.md new file mode 100644 index 000000000..47d199e57 --- /dev/null +++ b/source/_daily_emails/2023-06-27.md @@ -0,0 +1,20 @@ +--- +title: > + A CI pipeline is like an additional team member +pubDate: 2023-06-27 +permalink: >- + archive/2023/06/27/ci-pipeline-additional-team-member +tags: + - continuous-integration + - pipelines +--- + +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. + +If those checks all pass, they automatically deploy the changes and make them live or update a pre-production environment. + +## Here's the thing + +A CI pipeline can do that. Automatically. For every commit and change to your codebase. + +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. diff --git a/source/_daily_emails/2023-06-28.md b/source/_daily_emails/2023-06-28.md new file mode 100644 index 000000000..1458e696b --- /dev/null +++ b/source/_daily_emails/2023-06-28.md @@ -0,0 +1,20 @@ +--- +title: > + There's no value in a broken CI pipeline +pubDate: 2023-06-28 +permalink: >- + archive/2023/06/28/theres-no-value-in-a-broken-ci-pipeline +tags: + - continuous-integration + - pipelines +--- + +The value in a CI pipeline is when its commands and checks are running successfully, and the pipeline is passing. + +And then keeping it passing. + +If the pipeline fails, it loses all of its value. + +Passing should be its default state, and effort should be made to ensure it continues to pass. + +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. diff --git a/source/_daily_emails/2023-06-29.md b/source/_daily_emails/2023-06-29.md new file mode 100644 index 000000000..bddf45c86 --- /dev/null +++ b/source/_daily_emails/2023-06-29.md @@ -0,0 +1,24 @@ +--- +title: > + Tests won't tell you if your code works +pubDate: 2023-06-29 +permalink: >- + archive/2023/06/29/tests-wont-tell-you-if-your-code-works +tags: + - automated-testing + - test-driven-development +--- + +Having a passing test suite or CI pipeline doesn't tell you if your appliction works. + +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. + +There could be untested code that isn't covered at all. + +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. + +## Here's the thing + +Instead of telling you that your application works by passing, the test suite tells you something is broken when it fails. + +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. diff --git a/source/_daily_emails/2023-06-30.md b/source/_daily_emails/2023-06-30.md new file mode 100644 index 000000000..1f35661e3 --- /dev/null +++ b/source/_daily_emails/2023-06-30.md @@ -0,0 +1,28 @@ +--- +title: > + How did you learn automated testing? +pubDate: 2023-06-30 +permalink: >- + archive/2023/06/30/how-did-you-learn-automated-testing +tags: + - automated-testing + - test-driven-development +--- + +I started to learn about automated testing in 2012 when I took over maintainership of the Drupal module, Override Node Options. + +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. + +Later, I started to learn about test-driven development and how to develop and design software by writing the tests first. + +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. + +Once I understood how to write tests and do TDD, I took any opportunity to practice it, whether on projects or coding katas. + +At one point, I was writing module code during work hours and writing tests for it during the evening. + +## What about you? + +How did you learn automated testing or test-driven development? Reply to this email and let me know. + +Bonus points if it was at one of my conference talks or workshops! diff --git a/source/_daily_emails/2023-07-01.md b/source/_daily_emails/2023-07-01.md new file mode 100644 index 000000000..1f1f44f09 --- /dev/null +++ b/source/_daily_emails/2023-07-01.md @@ -0,0 +1,30 @@ +--- +title: > + Once you start writing tests, you can't stop +pubDate: 2023-07-01 +permalink: >- + archive/2023/07/01/once-you-start-writing-tests-you-cant-stop +tags: + - automated-testing + - test-driven-development +--- + +Once you start testing/TDD, you can't go back + +Once you start writing automated tests or doing test-driven development, you can't go back to not doing it. + +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. + +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. + +Also, because it passes a manual test, there's no guarantee it won't break unexpectedly in the future. + +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. + +## Here's the thing + +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. + +It's easier to create a test that proves a bug exists and shows it'safixed because the test passes. + +Once you have these things, you can't stop and go back to not having tests. diff --git a/source/_daily_emails/2023-07-02.md b/source/_daily_emails/2023-07-02.md new file mode 100644 index 000000000..0b7cf020d --- /dev/null +++ b/source/_daily_emails/2023-07-02.md @@ -0,0 +1,51 @@ +--- +title: > + Docker or Nix? +pubDate: 2023-07-02 +permalink: >- + archive/2023/07/02/docker-or-nix +tags: + - docker + - nix +--- + +I've been a Nix user for about a year, starting with its package manager on my previously installed Linux distribution. + +I started to use Home Manager for my user configuration and dotfiles and later switched to the NixOS operating system. + +## Using Nix for software development + +I've also been using Nix Flakes for per-project configuration. + +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. + +Here is an example Flake for a PHP CLI application: + +```nix +{ +  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + +  outputs = inputs@{ flake-parts, ... }: +    flake-parts.lib.mkFlake { inherit inputs; } { +      systems = [ "x86_64-linux" ]; + +      perSystem = { config, self', inputs', pkgs, system, ... }: { +        devShells = { +          default = pkgs.mkShell { +            buildInputs = with pkgs; [ php82 php82Packages.composer ]; +          }; +        }; +      }; +    }; +} +``` + +It declares that PHP 8.2 and Composer are available, even if I have different versions installed globally. + +## Will Nix replace Docker? + +Nix and Flakes have replaced Docker for me on some projects. + +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. + +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. diff --git a/source/_daily_emails/2023-07-03.md b/source/_daily_emails/2023-07-03.md new file mode 100644 index 000000000..df4046305 --- /dev/null +++ b/source/_daily_emails/2023-07-03.md @@ -0,0 +1,43 @@ +--- +title: > + Why write custom assertions in your tests? +pubDate: 2023-07-03 +permalink: >- + archive/2023/07/03/why-write-custom-assertions-in-your-tests +tags: + - automated-testing +--- + +I'm refactoring some code on a client project - creating a Repository class to centralise some logic before implementing the next feature. + +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.). + +## Adding a custom assertion + +I'm using PHPUnit's native assertions to check it returns a Collection (I regularly include the `illuminate/collections` library from Laravel in other projects) and that each item is an instance of a `NodeInterface`, but there isn't an assertion to check each node is of the correct type. + +My initial implementation was to loop over each node and use `assertSame` on its bundle before refactoring to create an array of unique bundle names and comparing it to my expected names: + +```php +self::assertSame( + expected: [$nodeType], + actual: $haystack + ->map(fn (NodeInterface $item): string => $item->bundle()) + ->unique() + ->toArray(), +); +``` + +## Why write a custom assertion? + +Whilst this works, it likely won't be clear in the future what it's testing. + +My initial thought was to add a comment describing it, but then I decided to wrap it in a custom assertion - `assertContainsOnlyNodesOfType` - a private static function within my test class that wraps the native assertions. + +This approach makes the test more readable now and in the future and more domain-focused by giving it a descriptive name. + +It can be easily reused within the same test case or elsewhere. + +Although I only perform one assertion in this case, I can combine multiple assertions and perform any other required steps. + +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. diff --git a/source/_daily_emails/2023-07-04.md b/source/_daily_emails/2023-07-04.md new file mode 100644 index 000000000..2907808a0 --- /dev/null +++ b/source/_daily_emails/2023-07-04.md @@ -0,0 +1,24 @@ +--- +title: > + Think smaller with TDD +pubDate: 2023-07-04 +permalink: >- + archive/2023/07/04/think-smaller-with-tdd +tags: + - automated-testing + - test-driven-development +--- + +I've recently added several custom search blocks and pages to a client project. + +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. + +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. + +## Thinking small + +This could seem like a large and daunting task, but with test-driven development, I can break everything into smaller, more manageable tasks. + +My objective is either to write the next failing test and then get it to pass or to refactor what I've written. + +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. diff --git a/source/_daily_emails/2023-07-05.md b/source/_daily_emails/2023-07-05.md new file mode 100644 index 000000000..cb4f94f32 --- /dev/null +++ b/source/_daily_emails/2023-07-05.md @@ -0,0 +1,46 @@ +--- +title: > + Services vs Actions +pubDate: 2023-07-05 +permalink: >- + archive/2023/07/05/services-vs-actions +tags: + - software-development + - software-architecture +--- + +When creating a custom module, where do you put your business logic? + +You want to keep classes like Controllers and Commands simple and move any reusable logic into separate files. + +Usually, this means 'Service' classes, but another approach I like is to use 'Action' classes. + +## What is an Action class? + +An Action is a PHP class representing a single action that must be performed. + +It usually contains a single method with a descriptive name summarising the task, such as `GetAccessToken`. + +This differs from a generic service like `ApiService` with multiple methods like `getAccessToken()`. + +## Using Action classes + +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. + +If you need multiple implementations, multiple actions can implement the same Interface and make them swappable, such as having `GetAccessToken` and `GetAndCacheAccessToken` implement the same `GetsAccessToken` interface. + +That also enables using design patterns like Decorators with Actions. + +## Why I like Actions + +I like more readable and meaningful class names and prefer working with multiple simpler classes than those with fewer complex ones. + +I like leveraging design patterns I'm used to, such as the Decorator pattern, by having common interfaces and contracts. + +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. + +## What about you? + +Do you use Action classes in your code, or do you use Services or something else? + +Reply to this email and let me know. diff --git a/source/_daily_emails/2023-07-06.md b/source/_daily_emails/2023-07-06.md new file mode 100644 index 000000000..0c6e1f570 --- /dev/null +++ b/source/_daily_emails/2023-07-06.md @@ -0,0 +1,36 @@ +--- +title: > + Automated testing is more than just unit testing +pubDate: 2023-07-06 +permalink: >- + archive/2023/07/06/automated-testing-is-more-than-just-unit-testing +tags: + - automated-testing + - test-driven-development +--- + +When I speak to people about automated testing or hear others speak about it, it's often confused with unit testing. + +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". + +But automated testing includes much more. + +## Other types of tests + +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. + +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. + +## What else is there? + +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. + +Pest PHP has an architecture plugin. + +There are dedicated front-end testing frameworks like Cypress for UI testing. + +Other quality tools like static analysis can also be considered testing tools. + +## Want to learn more? + +If you want to learn more about automated testing in Drupal, [I have a talk about that](https://www.oliverdavies.uk/talks/tdd-test-driven-drupal). diff --git a/source/_daily_emails/2023-07-15.md b/source/_daily_emails/2023-07-15.md new file mode 100644 index 000000000..5ff711a7d --- /dev/null +++ b/source/_daily_emails/2023-07-15.md @@ -0,0 +1,22 @@ +--- +title: > + Test-driven development makes you more productive +pubDate: 2023-07-15 +permalink: >- + archive/2023/07/15/test-driven-development-makes-you-more-productive +tags: + - automated-testing + - test-driven-development +--- + +I think that test-driven development (TDD) makes you productive. + +Firstly, you save time by not needing to switch from your code to a terminal or browser to test it. + +But, just as importantly, TDD reduces procrastination. It's much clearer to see what the next steps are. + +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. + +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. + +I think that achieving small tasks with short feedback loops using test-driven development makes it much easier to remain productive and focussed. diff --git a/source/_daily_emails/2023-07-16.md b/source/_daily_emails/2023-07-16.md new file mode 100644 index 000000000..480cbe78b --- /dev/null +++ b/source/_daily_emails/2023-07-16.md @@ -0,0 +1,25 @@ +--- +title: > + When writing a failing test, you're designing your code +pubDate: 2023-07-16 +permalink: >- + archive/2023/07/16/when-writing-a-failing-test-youre-designing-your-code +tags: + - automated-testing + - test-driven-development +--- + +When doing test-driven development, you start by writing a failing test and then write the code to make it pass. + +This is the design phase where you ask questions and decide how you want the code to work. + +* Are you going to use a global function or a method on a class? +* Will you create a new class or add a method to an existing class? +* What will it be called? +* Will you use a named method or make the class invokable like a single-method Controller or Action? +* Will it accept any parameters? +* If so, what will the parameters be, what will they be named, and will they take any default values? +* Will it return a value? +* Should it throw an Exception? + +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. diff --git a/source/_daily_emails/2023-07-17.md b/source/_daily_emails/2023-07-17.md new file mode 100644 index 000000000..16434e2c9 --- /dev/null +++ b/source/_daily_emails/2023-07-17.md @@ -0,0 +1,30 @@ +--- +title: > + Too many choices? +pubDate: 2023-07-17 +permalink: >- + archive/2023/07/17/too-many-choices +tags: + - automation + - terraform +--- + +I've recently considered moving my infrastructure automation code from Pulumi to Terraform. + +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. + +As a Developer, this seems appealing, but it poses an important question - which programming language should you use? + +I've written and re-written Pulumi code in TypeScript and Python and experimented with Go to see which feels best for me. + +If one of these were my primary language, it would be a no-brainer. + +## Here's the thing + +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. + +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. + +It's like taking my children to a restaurant. + +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. diff --git a/source/_daily_emails/2023-07-18.md b/source/_daily_emails/2023-07-18.md new file mode 100644 index 000000000..a3b67afde --- /dev/null +++ b/source/_daily_emails/2023-07-18.md @@ -0,0 +1,22 @@ +--- +title: > + TDD as a concept is simple, but TDD is difficult +pubDate: 2023-07-18 +permalink: >- + archive/2023/07/18/tdd-as-a-concept-is-simple-but-tdd-is-difficult +tags: + - automated-testing + - test-driven-development +--- + +Test-driven development as a concept is easy. + +Before you write any code, you write a failing test and then write enough code to get it to pass. + +But implementing test-driven development is harder. + +As well as overcoming the initial reluctance to write the tests first, it takes time to learn how to use it well. + +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. + +As with many things, practice and perseverance are key. diff --git a/source/_daily_emails/2023-07-19.md b/source/_daily_emails/2023-07-19.md new file mode 100644 index 000000000..274d98ac3 --- /dev/null +++ b/source/_daily_emails/2023-07-19.md @@ -0,0 +1,14 @@ +--- +title: > + TDD is like clicker training +pubDate: 2023-07-19 +permalink: >- + archive/2023/07/19/tdd-is-like-clicker-training +tags: + - automated-testing + - test-driven-development +--- + +During a webinar I watched recently, someone described test-driven-development as clicker training for Developers. + +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. diff --git a/source/_daily_emails/2023-07-20.md b/source/_daily_emails/2023-07-20.md new file mode 100644 index 000000000..0be8a0657 --- /dev/null +++ b/source/_daily_emails/2023-07-20.md @@ -0,0 +1,20 @@ +--- +title: > + Tests as communication +pubDate: 2023-07-20 +permalink: >- + archive/2023/07/20/tests-as-communication +tags: + - automated-testing + - test-driven-development +--- + +Automated tests aren't just checks to verify your software is working. + +They're a communication tool that shows people working on the code how it's supposed to be used. + +It's a form of documentation. + +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. + +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. diff --git a/source/_daily_emails/2023-07-21.md b/source/_daily_emails/2023-07-21.md new file mode 100644 index 000000000..8b48265a2 --- /dev/null +++ b/source/_daily_emails/2023-07-21.md @@ -0,0 +1,18 @@ +--- +title: > + Comments as communication +pubDate: 2023-07-21 +permalink: >- + archive/2023/07/21/comments-as-communication +tags: [] +--- + +I often hear that code should be "self-documenting". + +Instead of writing a comment, you should create a function or class with that name instead. + +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. + +If a comment just says `Returns true` or `Sends an email`, 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. + +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. diff --git a/source/_daily_emails/2023-07-22.md b/source/_daily_emails/2023-07-22.md new file mode 100644 index 000000000..1a415870d --- /dev/null +++ b/source/_daily_emails/2023-07-22.md @@ -0,0 +1,16 @@ +--- +title: > + More code, more problems +pubDate: 2023-07-22 +permalink: >- + archive/2023/07/22/more-code-more-problems +tags: [] +--- + +The more code you have, the more potential problems you have. + +More code means more opportunities for bugs in your software. + +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. + +If you can keep your amount of code to a minimum and reduce the maintenance overhead, you are less likely to experience issues. diff --git a/source/_daily_emails/2023-07-23.md b/source/_daily_emails/2023-07-23.md new file mode 100644 index 000000000..b3b66e2c7 --- /dev/null +++ b/source/_daily_emails/2023-07-23.md @@ -0,0 +1,16 @@ +--- +title: > + Tomorrow is easier if today's code is simpler +pubDate: 2023-07-23 +permalink: >- + archive/2023/07/23/tomorrow-is-easier-if-todays-code-is-simpler +tags: [] +--- + +If you write simple code, it is quicker and easier to read, extend and change. + +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. + +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. + +It will also likely be easier to debug with tools like Xdebug and PHPStan or upgrade with tools like Rector. diff --git a/source/_daily_emails/2023-07-24.md b/source/_daily_emails/2023-07-24.md new file mode 100644 index 000000000..5470204d1 --- /dev/null +++ b/source/_daily_emails/2023-07-24.md @@ -0,0 +1,30 @@ +--- +title: > + Testing is all about confidence +pubDate: 2023-07-24 +permalink: >- + archive/2023/07/24/testing-is-all-about-confidence +tags: + - automated-testing + - test-driven-development +--- + +Testing - manual or automated - is about building confidence. + +If we deploy this change or release this feature, are we confident it will work as expected and not cause regressions elsewhere? + +What if someone asked you on a scale between one and ten? + +From an automated perspective, have you written enough tests for the feature to be confident it works? + +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? + +Do the tests have enough assertions, and have you covered enough use cases and scenarios? + +## Here's the thing + +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. + +For me, it's about the answer to the question: + +If we deploy this change, how confident are you that it will work as expected? diff --git a/source/_daily_emails/2023-07-25.md b/source/_daily_emails/2023-07-25.md new file mode 100644 index 000000000..f2fdf7cb3 --- /dev/null +++ b/source/_daily_emails/2023-07-25.md @@ -0,0 +1,40 @@ +--- +title: > + Working backwards +pubDate: 2023-07-25 +permalink: >- + archive/2023/07/25/working-backwards +tags: [] +--- + +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. + +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. + +## Where did I start? + +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. + +I'd have started with the code to import the translated strings if I hadn't already done this in an earlier spike. + +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. + +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. + +I also have a working end-to-end test, and I can send a file and get the response I need. + +What if I'd written all the code and discovered something wouldn't work? + +## What next? + +Now, I can work backwards and start to make the content dynamic. + +I can introduce more authentic and complicated data, remove the hard-coded test data, and check that things still work. + +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. + +With the main pieces of the puzzle in place, I can continue building and filling in the others. + +Once I have a complete feature with all the pieces in place, I can refactor as needed. + +I still have the same finished puzzle - I just built it in a different order. diff --git a/source/_daily_emails/2023-07-26.md b/source/_daily_emails/2023-07-26.md new file mode 100644 index 000000000..ac05bd156 --- /dev/null +++ b/source/_daily_emails/2023-07-26.md @@ -0,0 +1,19 @@ +--- +title: > + Prove the concept +pubDate: 2023-07-26 +permalink: >- + archive/2023/07/26/prove-the-concept +tags: + - software-development +--- + +When starting a new task, find the simplest way to prove the concept. + +Investigate upfront and evaluate potential approaches. + +What's the smallest or quickest thing you could do to validate an idea? + +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. + +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. diff --git a/source/_daily_emails/2023-07-27.md b/source/_daily_emails/2023-07-27.md new file mode 100644 index 000000000..6a0b1f83e --- /dev/null +++ b/source/_daily_emails/2023-07-27.md @@ -0,0 +1,23 @@ +--- +title: > + Stick to conventions +pubDate: 2023-07-27 +permalink: >- + archive/2023/07/27/stick-to-conventions +tags: + - software-development +--- + +If you're performing a task as there's already a convention on how to do it, stick to it. + +If the codebase follows a particular coding standard, use it. + +If a project uses repository classes instead of interacting directly with a database, do that with your code too. + +If you use a framework with a service container and uses dependency injection, do that instead of manually creating classes. + +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. + +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. + +If you don't follow a convention, it will be harder for you or others to work on it in the future. diff --git a/source/_daily_emails/2023-07-28.md b/source/_daily_emails/2023-07-28.md new file mode 100644 index 000000000..49c222415 --- /dev/null +++ b/source/_daily_emails/2023-07-28.md @@ -0,0 +1,23 @@ +--- +title: > + Don't write generic commit messages +pubDate: 2023-07-28 +permalink: >- + archive/2023/07/28/generic-commit-messages +tags: + - git +--- + +This week, I reviewed a client's Drupal 9 website and investigated the steps needed to upgrade to Drupal 10. + +Looking at the Git log to see the commits for a module, I see `Week 20 development` as the latest commit message. + +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. + +This should have been several commits, each performing a clear and separate task. + +Updating the dependencies should be its own commit, and changes to the custom modules and theme should be separate commits. + +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. + +That would have been more useful for me whilst looking through the logs than `Week 20 development`. diff --git a/source/_daily_emails/2023-07-29.md b/source/_daily_emails/2023-07-29.md new file mode 100644 index 000000000..45c86581f --- /dev/null +++ b/source/_daily_emails/2023-07-29.md @@ -0,0 +1,25 @@ +--- +title: > + Should I wait to upgrade from Drupal 7? +pubDate: 2023-07-29 +permalink: >- + archive/2023/07/29/should-i-wait-to-upgrade-from-drupal-7 +tags: + - drupal + - drupal-7 + - php +--- + +It was announced at DrupalCon that Drupal 7 support was being extended one final time until January 2025. + +But if you have a Drupal 7 website, does that mean you should wait to start upgrading it? + +I recommend starting the process as soon as possible. + +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. + +In that case, those modules will have no new features, bug fixes or security updates, although Drupal core support has been extended. + +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. + +If you're stuck on Drupal 7, book an [upgrade consultation call](https://www.oliverdavies.uk/call) with me or purchase an [upgrade roadmap for your project](https://www.oliverdavies.uk/drupal7) and I'll get you unstuck. diff --git a/source/_daily_emails/2023-07-30.md b/source/_daily_emails/2023-07-30.md new file mode 100644 index 000000000..6fd0a24cc --- /dev/null +++ b/source/_daily_emails/2023-07-30.md @@ -0,0 +1,26 @@ +--- +title: > + Commit often, deploy often +pubDate: 2023-07-30 +permalink: >- + archive/2023/07/30/commit-often-deploy-often +tags: + - git + - deployments +--- + +This is a follow-up to Friday's email on generic commit messages. + +In it, I discussed seeing commit messages like `Week 20 development` in project codebases and why you should write specific commit messages for each change. + +The other thing is, if you only commit once a week, you can only deploy once a week. + +That's assuming that, on this project, the changes were committed and pushed weekly. It could have been fortnightly, monthly, or longer. + +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. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-07-31.md b/source/_daily_emails/2023-07-31.md new file mode 100644 index 000000000..b7b0e6522 --- /dev/null +++ b/source/_daily_emails/2023-07-31.md @@ -0,0 +1,26 @@ +--- +title: > + Upgrading from Drupal 9 is easier +pubDate: 2023-07-31 +permalink: >- + archive/2023/07/31/upgrading-from-drupal-9-is-easier +tags: + - drupal + - php +--- + +Upgrading from Drupal 7 to 8, 9 or 10 is a large task. + +You must create a new empty site, migrate your configuration and data, manually recreate anything else and rewrite any custom modules and themes. + +Since Drupal 8, things have been different. + +You can upgrade your site in place. + +No large code rewrite or data migration. + +Many contributed modules support multiple major Drupal versions simultaneously, so they may not need upgrading. + +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. + +The same applies to upgrading from Drupal 9 to 10, which will be the same for Drupal 11 next year. diff --git a/source/_daily_emails/2023-08-01.md b/source/_daily_emails/2023-08-01.md new file mode 100644 index 000000000..b7f5ba76c --- /dev/null +++ b/source/_daily_emails/2023-08-01.md @@ -0,0 +1,40 @@ +--- +title: > + Maintaining a module used on 35,000 Drupal websites +pubDate: 2023-08-01 +permalink: >- + archive/2023/08/01/maintaining-a-module-used-on-35000-drupal-websites +tags: + - drupal + - open-source +--- + +Note: The numbers within this post are taken from my [Test-Driven Drupal talk](https://www.oliverdavies.uk/talks/tdd-test-driven-drupal), in which I also talk about this. + +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. + +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. + +The most recent statistics show the module is currently used on 34,981 websites and is consistently around 35,000. + +## What does that mean? + +The module is considered feature complete, but I'm not ruling out any new additions. + +The main thing is ensuring that any changes don't break 35,000 websites! + +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. + +## This has worked well + +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. + +More recently, a colleague and I refactored the module and split each override into its own class, making adding and maintaining overrides easier. + +Because the tests were still passing, we knew our refactor was successful and not causing regressions. + +## Here's the thing + +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. + +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. diff --git a/source/_daily_emails/2023-08-02.md b/source/_daily_emails/2023-08-02.md new file mode 100644 index 000000000..0092e7c74 --- /dev/null +++ b/source/_daily_emails/2023-08-02.md @@ -0,0 +1,17 @@ +--- +title: > + A crash course into automated testing with Drupal +pubDate: 2023-08-02 +permalink: >- + archive/2023/08/02/a-crash-course-into-drupal-testing +tags: + - drupal + - automated-testing + - test-driven-development +--- + +Next week, I'll be presenting a lightning talk at the North West Drupal user group (NWDUG)'s August meetup. + +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. + +It's an online event, so if you'd like to see this and other lightning talks on the 8th of August, RSVP at . diff --git a/source/_daily_emails/2023-08-03.md b/source/_daily_emails/2023-08-03.md new file mode 100644 index 000000000..50ee4147b --- /dev/null +++ b/source/_daily_emails/2023-08-03.md @@ -0,0 +1,19 @@ +--- +title: > + What problem are we trying to solve? +pubDate: 2023-08-03 +permalink: >- + archive/2023/08/03/what-problem-are-we-trying-to-solve +tags: + - drupal +--- + +The Override Node Options module that I said yesterday is used on 35,000 websites isn't a complicated module. + +It doesn't add a lot of features. + +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". + +The problem being solved is allowing users to set node options, like the created date or published status, in a secure way. + +If it wasn't solving a problem, it wouldn't be used on 35,000 Drupal websites. diff --git a/source/_daily_emails/2023-08-04.md b/source/_daily_emails/2023-08-04.md new file mode 100644 index 000000000..5fea20ab9 --- /dev/null +++ b/source/_daily_emails/2023-08-04.md @@ -0,0 +1,27 @@ +--- +title: > + Laravel Prompts and framework-agnostic tools +pubDate: 2023-08-04 +permalink: >- + archive/2023/08/04/laravel-prompts +tags: + - php + - laravel + - open-source +--- + +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. + +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. + +## Laravel Prompts + +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. + +This means I can potentially use it with Drupal and Drush or Symfony Console applications, too, such as my build configuration file generator. + +## Here's the thing + +I like tools I can use across multiple technologies and prefer framework-agnostic tools to specific ones. + +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. diff --git a/source/_daily_emails/2023-08-05.md b/source/_daily_emails/2023-08-05.md new file mode 100644 index 000000000..e4a4b94c1 --- /dev/null +++ b/source/_daily_emails/2023-08-05.md @@ -0,0 +1,20 @@ +--- +title: > + Use Drupal to own your content +pubDate: 2023-08-05 +permalink: >- + archive/2023/08/05/use-drupal-to-own-your-content +tags: + - drupal + - open-source +--- + +I recently saw a social media website taking over users' handles - renaming them so they can have the original. + +There were similar issues a few years ago when a website put a paywall in front of articles written by its users. + +I've written articles and tutorials for companies I've worked at that no longer exist as the companies have been acquired. + +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. + +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. diff --git a/source/_daily_emails/2023-08-06.md b/source/_daily_emails/2023-08-06.md new file mode 100644 index 000000000..3f4394349 --- /dev/null +++ b/source/_daily_emails/2023-08-06.md @@ -0,0 +1,16 @@ +--- +title: > + YAGNI +pubDate: 2023-08-06 +permalink: >- + archive/2023/08/06/yagni +tags: [] +--- + +During a recent coding dojo session, we spoke about YAGNI - i.e. "You aren't going to need it". + +In this situation, we discussed how many numbers we should support passing to a method in a calculator application. + +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. + +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. diff --git a/source/_daily_emails/2023-08-07.md b/source/_daily_emails/2023-08-07.md new file mode 100644 index 000000000..2283a1931 --- /dev/null +++ b/source/_daily_emails/2023-08-07.md @@ -0,0 +1,27 @@ +--- +title: > + Tests make upgrades less risky +pubDate: 2023-08-07 +permalink: >- + archive/2023/08/07/tests-make-upgrades-less-risky +tags: + - automated-testing + - test-driven-development + - drupal +--- + +I recently reviewed a client's Drupal 9 website to gather information about upgrading it to Drupal 10. + +The site has a number of custom modules. They all require changes to make them Drupal 10-compatible - some are a `core_version_requirement` update, and some are more complex. + +None of these modules have automated tests. + +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. + +But I can't. + +I'd need to test each module beforehand to understand what it does manually and again after making the changes. + +This is more time-consuming, riskier, and easier for me to introduce regressions or new bugs. + +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. diff --git a/source/_daily_emails/2023-08-08.md b/source/_daily_emails/2023-08-08.md new file mode 100644 index 000000000..931486509 --- /dev/null +++ b/source/_daily_emails/2023-08-08.md @@ -0,0 +1,22 @@ +--- +title: > + 8 years of dotfiles +pubDate: 2023-08-08 +permalink: >- + archive/2023/08/08/8-years-of-dotfiles +tags: + - dotfiles + - open-source +--- + +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. + +Afterwards, I realised the first commit to [my personal dotfiles repository](https://github.com/opdavies/dotfiles) was over eight years ago, in July 2015. + +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. + +In 2021, I switched my `.vimrc` configuration file to an `init.vim` 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. + +My complete NixOS and Home Manager configurations are within my `dotfiles` repository, and the configuration for tools, including Neovim, tmux and Git. + +I wonder what the repository will look like in another eight years... diff --git a/source/_daily_emails/2023-08-09.md b/source/_daily_emails/2023-08-09.md new file mode 100644 index 000000000..dd8c96686 --- /dev/null +++ b/source/_daily_emails/2023-08-09.md @@ -0,0 +1,17 @@ +--- +title: > + Vim is my lightsaber +pubDate: 2023-08-09 +permalink: >- + archive/2023/08/09/vim-is-my-lightsaber +tags: + - vim +--- + +"Vim is my lightsaber" is the final chapter of Jess Archer's Neovim course on Laracasts. + +In this summary, Jess explains that some Star Wars characters have lightsabers customised to their preferences and fighting style. + +Vim is her lightsaber - her personalised tool to develop software. It works how she wants it to, with the features she needs. + +I've written before about mastering your tools and thought this was a nice spin on it. diff --git a/source/_daily_emails/2023-08-10.md b/source/_daily_emails/2023-08-10.md new file mode 100644 index 000000000..79b09dfbb --- /dev/null +++ b/source/_daily_emails/2023-08-10.md @@ -0,0 +1,16 @@ +--- +title: > + Testing, fixed prices and bug-free guarantees +pubDate: 2023-08-10 +permalink: >- + archive/2023/08/10/testing-fixed-prices-and-bug-free-guarantees +tags: + - automated-testing + - test-driven-development +--- + +After my lightning talk for NWDUG on automated testing with Drupal, the question was asked how to find time for testing. + +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. + +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. diff --git a/source/_daily_emails/2023-08-11.md b/source/_daily_emails/2023-08-11.md new file mode 100644 index 000000000..805342077 --- /dev/null +++ b/source/_daily_emails/2023-08-11.md @@ -0,0 +1,22 @@ +--- +title: > + Everyone tests their code +pubDate: 2023-08-11 +permalink: >- + archive/2023/08/11/everyone-tests-their-code +tags: + - automated-testing + - test-driven-development +--- + +No one writes code, commits it and pushes it to production without checking it works. + +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. + +This takes time, you need to switch contexts, and the test is only valid for that time. + +There's no guarantee it will still work in the future. + +Automated testing, however, means you can write your code and run the tests without leaving your IDE or text editor. + +The tests can also be run in the future to ensure the functionality works without needing to re-test it manually. diff --git a/source/_daily_emails/2023-08-12.md b/source/_daily_emails/2023-08-12.md new file mode 100644 index 000000000..fd49d067c --- /dev/null +++ b/source/_daily_emails/2023-08-12.md @@ -0,0 +1,20 @@ +--- +title: > + Does not writing tests actually save time? +pubDate: 2023-08-12 +permalink: >- + archive/2023/08/12/does-not-writing-tests-actually-save-time +tags: + - automated-testing + - test-driven-development +--- + +One of the most common responses to why people don't write tests is, "We don't have time". + +So, people don't write tests to save time. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-08-13.md b/source/_daily_emails/2023-08-13.md new file mode 100644 index 000000000..0bf4b70d9 --- /dev/null +++ b/source/_daily_emails/2023-08-13.md @@ -0,0 +1,18 @@ +--- +title: > + Don't estimate separately for testing +pubDate: 2023-08-13 +permalink: >- + archive/2023/08/13/dont-estimate-separately-for-testing +tags: + - automated-testing + - test-driven-development +--- + +A common issue I see for people introducing automated testing is estimating the testing and implementation of a task separately. + +Something like, "It'll take x to do the work and x to write the tests for it". + +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. + +If you provide one estimate for both, this can't happen. diff --git a/source/_daily_emails/2023-08-14.md b/source/_daily_emails/2023-08-14.md new file mode 100644 index 000000000..87c71f1ab --- /dev/null +++ b/source/_daily_emails/2023-08-14.md @@ -0,0 +1,27 @@ +--- +title: > + Why keep a dotfiles repository +pubDate: 2023-08-14 +permalink: >- + archive/2023/08/14/why-keep-a-dotfiles-repository +tags: + - dotfiles +--- + +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. + +But why do this? + +It makes it easy to share the same configuration across multiple computers, such as personal and work or different setups for clients. + +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. + +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. + +I can experiment with settings and programs and then revert them again if I want to. + +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. + +I can review it in the future in case I need it again or want to re-evaluate it. + +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. diff --git a/source/_daily_emails/2023-08-15.md b/source/_daily_emails/2023-08-15.md new file mode 100644 index 000000000..7a37d2808 --- /dev/null +++ b/source/_daily_emails/2023-08-15.md @@ -0,0 +1,24 @@ +--- +title: > + Writing test and implementation code are the same task +pubDate: 2023-08-15 +permalink: >- + archive/2023/08/15/writing-test-and-implementation-code-are-the-same-task +tags: + - automated-testing + - test-driven-development +--- + +In Sunday's email, I said not to estimate separately for testing and implementation. + +But you can't do this anyway if you're doing test-driven development. + +With TDD, you aren't writing all of your tests and all of the implementation code or vice versa. + +You're continuously switching back and forth, starting by writing a failing test and then enough implementation code for it to pass. + +Then you write more test code, whether expanding the same test or writing a new one until you have a new failure. + +You get it to pass, refactor, and repeat the process until the task is complete. + +It's all part of the same task and the same estimate. diff --git a/source/_daily_emails/2023-08-16.md b/source/_daily_emails/2023-08-16.md new file mode 100644 index 000000000..16a72a476 --- /dev/null +++ b/source/_daily_emails/2023-08-16.md @@ -0,0 +1,32 @@ +--- +title: > + Writing tests in your own time +pubDate: 2023-08-16 +permalink: >- + archive/2023/08/16/writing-tests-in-your-own-time +tags: + - automated-testing + - test-driven-development +--- + +This is how I first started writing automated tests. + +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. + +I wanted to give myself a less pressured opportunity to learn and experiment with different options and approaches. + +So, when creating custom modules, I wrote the implementation code during billable work hours and the tests during the evening on my own time. + +I was investing time in learning a new skill and one that I knew would pay dividends. + +## How did it go? + +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. + +One time, though, I found a bug I'd written that day. I think it was an incorrect permission name I'd typed. + +I was able to fix it before it was submitted for quality assurance checks and client testing. + +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. + +After that, for me, there was no going back. diff --git a/source/_daily_emails/2023-08-17.md b/source/_daily_emails/2023-08-17.md new file mode 100644 index 000000000..06782ecdd --- /dev/null +++ b/source/_daily_emails/2023-08-17.md @@ -0,0 +1,29 @@ +--- +title: > + Writing custom assertions in your tests +pubDate: 2023-08-17 +permalink: >- + archive/2023/08/17/writing-custom-assertions-in-your-tests +tags: + - automated-testing + - test-driven-development +--- + +Writing custom assertions is a great way to clean up your test code. + +Here's an example from one of my client Drupal projects: + +```php +private static function assertProductVariationHasPrice(ProductVariationInterface $productVariation, string $expectedPrice): void { + self::assertSame( + actual: $productVariation->getPrice()->getNumber(), + expected: $expectedPrice, + ); +} +``` + +This one wraps a single assertion, but they could also include multiple assertions or additional steps. + +## Here's the thing + +A custom assertion is a simple function but it makes the test code more readable and less repetitive. diff --git a/source/_daily_emails/2023-08-18.md b/source/_daily_emails/2023-08-18.md new file mode 100644 index 000000000..f76f5041a --- /dev/null +++ b/source/_daily_emails/2023-08-18.md @@ -0,0 +1,28 @@ +--- +title: > + Types vs tests +pubDate: 2023-08-18 +permalink: >- + archive/2023/08/18/types-vs-tests +tags: + - automated-testing + - test-driven-development + - static-analysis +--- + +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.". + +The results were: + +- Types - 50.9% +- Tests - 49.1% + +I was surprised by this. + +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. + +I can also perform checks and throw errors or Exceptions if something isn't what I'd expect. + +## Here's the thing + +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. diff --git a/source/_daily_emails/2023-08-19.md b/source/_daily_emails/2023-08-19.md new file mode 100644 index 000000000..43ef1a775 --- /dev/null +++ b/source/_daily_emails/2023-08-19.md @@ -0,0 +1,43 @@ +--- +title: > + Asserting all the things +pubDate: 2023-08-19 +permalink: >- + archive/2023/08/19/asserting-all-the-things +tags: + - php +--- + +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. + +In PHP, this is done by throwing an Exception if a condition is met. + +For example: + +```php +if (!is_array(false)) { + throw new \Exception('Not an array'); +} +``` + +There's also the `assert` construct which, since PHP 8.0, throws an Exception by default: + +```php +assert(is_array(false)); +``` + +You can also use an assertion library, such as `webmozart/assert` or `beberlei/assert` which provide assertions and guard methods: + +```php +use Webmozart\Assert\Assert; + +Assert::isArray(false); +``` + +Similarly, if the condition fails, it throws an Exception that can be caught elsewhere. + +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. + +## Here's the thing + +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. diff --git a/source/_daily_emails/2023-08-20.md b/source/_daily_emails/2023-08-20.md new file mode 100644 index 000000000..071edf419 --- /dev/null +++ b/source/_daily_emails/2023-08-20.md @@ -0,0 +1,57 @@ +--- +title: > + PHP types and assertions +pubDate: 2023-08-20 +permalink: >- + archive/2023/08/20/php-types-and-assertions +tags: + - php +--- + +Following yesterday's email about input validation, guard clauses and assertion libraries, these can be used to compliment PHP's native types and checking. + +For example: + +```php +function createJourney(string $from, string $to, int $duration): void { + var_dump($from, $to, $duration); +} +``` + +In this code, each parameter has a type, but there's no validation on the values. + +If I run this: + +```plain +createJourney('', '', -10); +``` + +I would get this output: + +```plain +string(0) "" +string(0) "" +int(-10) +``` + +This is probably not what you want. + +I expect `$to` and `$from` to be not empty and the duration to be greater than zero. + +## Here's the thing + +I can use an assertion library or throw my own Exceptions if the values pass the type checks but aren't what I need. + +For example: + +```php +function createJourney(string $from, string $to, int $duration): void { + Assert::stringNotEmpty($from); + Assert::stringNotEmpty($to); + Assert::positiveInteger($duration); + + var_dump($from, $to, $duration); +} +``` + +Now, if an empty string or negative duration is passed - in my implementation or test code - an Exception will be thrown. diff --git a/source/_daily_emails/2023-08-21.md b/source/_daily_emails/2023-08-21.md new file mode 100644 index 000000000..df5529a9d --- /dev/null +++ b/source/_daily_emails/2023-08-21.md @@ -0,0 +1,27 @@ +--- +title: > + Which part of the CI pipeline has the most value? +pubDate: 2023-08-21 +permalink: >- + archive/2023/08/21/which-part-of-the-ci-pipeline-has-the-most-value +tags: + - continuous-integration + - automated-testing + - static-analysis +--- + +The main part of my CI pipeline tasks are running the automated tests, coding standards checks and static analysis. + +But which of these are the most valuable? + +I used to run the coding standards check first as it was the quickest, followed by static analysis and the automated tests. + +If a task were going to fail, it would fail quickly. + +But is that the objective of the CI pipeline? + +Whilst it needs to be quick, the main reason to run these is to ensure things work as expected. + +Recently, I changed my pipelines to run the tests first, as these verify the code's behaviour. + +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. diff --git a/source/_daily_emails/2023-08-22.md b/source/_daily_emails/2023-08-22.md new file mode 100644 index 000000000..4f1c55081 --- /dev/null +++ b/source/_daily_emails/2023-08-22.md @@ -0,0 +1,32 @@ +--- +title: > + Deployments with your CI pipeline +pubDate: 2023-08-22 +permalink: >- + archive/2023/08/22/deployments-with-your-ci-pipeline +tags: + - continuous-integration + - pipelines +--- + +You have a CI pipeline in your project. + +Every time you push a commit, the CI pipeline runs and performs its checks. + +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. + +Everything passes. + +## What next? + +If the pipeline passes, your change is deployable. + +So, why not extend the pipeline to deploy the change once the checks pass? + +If the checks don't pass, don't deploy. + +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. + +Instead of waiting for someone to do this manually, remove a step and automate it within the pipeline. + +The sooner it's deployed, the sooner it provides value for your application's users. diff --git a/source/_daily_emails/2023-08-23.md b/source/_daily_emails/2023-08-23.md new file mode 100644 index 000000000..45686ae20 --- /dev/null +++ b/source/_daily_emails/2023-08-23.md @@ -0,0 +1,19 @@ +--- +title: > + Don't use third-party services directly +pubDate: 2023-08-23 +permalink: >- + archive/2023/08/23/dont-use-third-party-services-directly +tags: + - automated-testing +--- + +If you need to integrate your application with a third-party service, don't integrate it directly - even if it has an SDK. + +Doing so locks you into a single implementation and a single vendor. + +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. + +If you need to switch to a different provider or add multiple options, you can without changing the existing code. + +It also makes it easier to test as you can write a fake implementation and use it for testing. diff --git a/source/_daily_emails/2023-08-24.md b/source/_daily_emails/2023-08-24.md new file mode 100644 index 000000000..437ffe2c7 --- /dev/null +++ b/source/_daily_emails/2023-08-24.md @@ -0,0 +1,24 @@ +--- +title: > + Testing multiple implementations with contract tests +pubDate: 2023-08-24 +permalink: >- + archive/2023/08/24/testing-multiple-implementations-with-contract-tests +tags: + - automated-testing + - test-driven-development +--- + +If you have multiple implementations of a service, as I [mentioned in yesterday's email](https://www.oliverdavies.uk/archive/2023/08/23/dont-use-third-party-services-directly), you need to ensure they all provide the same functionality. + +You need to be able to run the same tests against each implementation and have them pass. + +## How do you do this? + +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. + +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. + +If one implementation doesn't return the same result as the others, its test will fail. + +If you add a new implementation, you create a new test class, use the trait and get the tests to pass. diff --git a/source/_daily_emails/2023-08-25.md b/source/_daily_emails/2023-08-25.md new file mode 100644 index 000000000..6423d061c --- /dev/null +++ b/source/_daily_emails/2023-08-25.md @@ -0,0 +1,18 @@ +--- +title: > + Start with a vague test +pubDate: 2023-08-25 +permalink: >- + archive/2023/08/25/start-with-a-vague-test +tags: + - automated-testing + - test-driven-development +--- + +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. + +It may not be clear straight away what you're trying to test. + +Once you get the ball rolling and you write more, it will usually become clear. + +Then you can go back and rename the test method to something more specific. diff --git a/source/_daily_emails/2023-08-26.md b/source/_daily_emails/2023-08-26.md new file mode 100644 index 000000000..7cd169d6b --- /dev/null +++ b/source/_daily_emails/2023-08-26.md @@ -0,0 +1,20 @@ +--- +title: > + Work in small chunks +pubDate: 2023-08-26 +permalink: >- + archive/2023/08/26/work-in-small-chunks +tags: + - automated-testing + - test-driven-development +--- + +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. + +Instead, work in small bite-sized iterations and focus on getting the test to pass as quickly as possible. + +You don't want to be stuck in a failing state for longer than you need to. + +Run the tests often, write the simplest code possible and don't write any code that isn't driven by a failing test. + +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. diff --git a/source/_daily_emails/2023-08-27.md b/source/_daily_emails/2023-08-27.md new file mode 100644 index 000000000..285448350 --- /dev/null +++ b/source/_daily_emails/2023-08-27.md @@ -0,0 +1,25 @@ +--- +title: > + Pull requests are great for open-source, but not for teams +pubDate: 2023-08-27 +permalink: >- + archive/2023/08/27/pull-requests-are-great-for-open-source +tags: + - code-review + - git + - trunk-based-development +--- + +Code review with pull and merge requests is great for open-source but not for development teams or soloists. + +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. + +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. + +It takes time for code to be reviewed, which means it takes longer for the change to be released to users. + +If you're a soloist, are you going to submit a request for you to review your own code? + +If you don't need to do code review on your team, do you need to create feature or topic branches? + +I'd suggest sticking to one canonical branch and doing trunk-based development instead. diff --git a/source/_daily_emails/2023-08-28.md b/source/_daily_emails/2023-08-28.md new file mode 100644 index 000000000..f502718d2 --- /dev/null +++ b/source/_daily_emails/2023-08-28.md @@ -0,0 +1,21 @@ +--- +title: > + Pair and mob programming are continuous code review +pubDate: 2023-08-28 +permalink: >- + archive/2023/08/28/pair-and-mob-programming-are-continuous-code-review +tags: + - code-review + - pair-programming + - mob-programming +--- + +Instead of a single Developer working individually on a task and submitting it for a code review once complete, try pair or mob programming. + +As well as extra benefits, such as knowledge sharing and shared responsibility for the code, it's continuously reviewed and improved during the session. + +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. + +So, why wait until the task is complete and the code is harder to change to review it? + +Why not have it reviewed as it's written? diff --git a/source/_daily_emails/2023-08-29.md b/source/_daily_emails/2023-08-29.md new file mode 100644 index 000000000..65afaee75 --- /dev/null +++ b/source/_daily_emails/2023-08-29.md @@ -0,0 +1,34 @@ +--- +title: > + CI pipelines are an automated code review +pubDate: 2023-08-29 +permalink: >- + archive/2023/08/29/ci-pipelines-are-an-automated-code-review +tags: + - code-review + - ci-pipelines +--- + +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. + +If the request isn't approved by (usually) two people, it won't be merged. + +Instead of focusing on the problem that needed to be solved and how I'd done it, many reviews focused on the small details. + +Do the lines have the correct number of spaces before them? + +Do the comments end with a full stop? + +Do the lines wrap at the correct point, and are your variable names in the right case? + +Essentially, does the code comply with the agreed coding standards? + +## Here's the thing + +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. + +These checks can be automated using CI pipelines or Git hooks to run tools like PHPCS to review and sometimes fix coding standards issues. + +Automating these checks means the Developers can focus on what they should be reviewing. + +How are they solving the problem, not how many spaces is the code indented by. diff --git a/source/_daily_emails/2023-08-30.md b/source/_daily_emails/2023-08-30.md new file mode 100644 index 000000000..e52357cf5 --- /dev/null +++ b/source/_daily_emails/2023-08-30.md @@ -0,0 +1,22 @@ +--- +title: > + TDD and "Unexpected errors" +pubDate: 2023-08-30 +permalink: >- + archive/2023/08/30/tdd-and-unexpected-errors +tags: + - automated-testing + - test-driven-development +--- + +When working on projects, it's common to see messages like "The website encountered an unexpected error. Please try again later.". + +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. + +The wording "unexpected error" has been intriguing to me, though. When do you expect an error? + +The best example I can think of for an expected error is when doing test-driven development. + +When doing TDD, you want to see an error to start as you start with a failing test. + +Then, you write the code to remove the error and get the test passing. diff --git a/source/_daily_emails/2023-08-31.md b/source/_daily_emails/2023-08-31.md new file mode 100644 index 000000000..12eb7ca73 --- /dev/null +++ b/source/_daily_emails/2023-08-31.md @@ -0,0 +1,16 @@ +--- +title: > + Code review discourages small refactorings +pubDate: 2023-08-31 +permalink: >- + archive/2023/08/31/code-review-discourages-small-refactorings +tags: + - code-reviews + - trunk-based-development +--- + +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? + +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? + +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? diff --git a/source/_daily_emails/2023-09-01.md b/source/_daily_emails/2023-09-01.md new file mode 100644 index 000000000..85ce3be36 --- /dev/null +++ b/source/_daily_emails/2023-09-01.md @@ -0,0 +1,28 @@ +--- +title: > + Non-blocking code reviews +pubDate: 2023-09-01 +permalink: >- + archive/2023/09/01/non-blocking-code-reviews +tags: + - ci-pipelines + - code-review +--- + +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. + +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. + +The ticket workflow could look like this: + +To Do -> Doing -> Merged -> Reviewed -> Tested -> Deployed + +Or: + +To Do -> Doing -> Merged -> Deployed -> Tested -> Reviewed + +The focus is getting the update to production, and the review is deferred. + +The same CI pipeline rules apply - it must be passing before the code can be deployed, so the same quality checks are run. + +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. diff --git a/source/_daily_emails/2023-09-02.md b/source/_daily_emails/2023-09-02.md new file mode 100644 index 000000000..4716cd956 --- /dev/null +++ b/source/_daily_emails/2023-09-02.md @@ -0,0 +1,31 @@ +--- +title: > + Planning first or reviewing last? +pubDate: 2023-09-02 +permalink: >- + archive/2023/09/02/planning-first-or-reviewing-last +tags: + - code-review + - pair-programming + - mob-programming +--- + +Code reviews are something that happens after the code has been written. + +Usually, a task is assigned to someone who completes it and makes the code available to their team members before it's merged. + +The problem is that if the implementation is wrong, it's already been written, which costs time and money. + +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. + +## Here's the thing + +Instead of reviewing the code after it's been written, invest more time into planning how the implementation should work upfront. + +What potential solutions exist, and which would work best in this situation? + +Write technical design documents and, if needed, create a small proof of concept. + +Do this as a team and decide on the approach before any code is written and time or effort is spent. + +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. diff --git a/source/_daily_emails/2023-09-03.md b/source/_daily_emails/2023-09-03.md new file mode 100644 index 000000000..f9daee60d --- /dev/null +++ b/source/_daily_emails/2023-09-03.md @@ -0,0 +1,18 @@ +--- +title: > + Including time for tests in estimates +pubDate: 2023-09-03 +permalink: >- + archive/2023/09/03/including-time-for-tests-in-estimates +tags: + - automated-testing + - test-driven-development + - software-development + - estimation +--- + +If you need to provide estimates for your tasks and intend to write tests, include the time for the tests within the estimate. + +Don't provide different estimates for testing and the implementation, or with tests and without tests - give one estimate that includes both. + +Writing tests and testable code will take longer to begin with, but practice makes perfect and will save time in the long run. diff --git a/source/_daily_emails/2023-09-04.md b/source/_daily_emails/2023-09-04.md new file mode 100644 index 000000000..9fd4033d8 --- /dev/null +++ b/source/_daily_emails/2023-09-04.md @@ -0,0 +1,22 @@ +--- +title: > + Charging more _not_ to write tests +pubDate: 2023-09-04 +permalink: >- + archive/2023/09/04/charging-more-not-to-write-tests +tags: + - automated-testing + - test-driven-development +--- + +Joel Clermont [replied to a previous email on Twitter](https://twitter.com/jclermont/status/1690872089878691840): + +> 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’d perceive as a benefit). Ended up not pursuing it, but was a fun idea at the time. + +It's an interesting idea. + +How much more would you charge not to write tests? + +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? + +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. diff --git a/source/_daily_emails/2023-09-05.md b/source/_daily_emails/2023-09-05.md new file mode 100644 index 000000000..b1964f48d --- /dev/null +++ b/source/_daily_emails/2023-09-05.md @@ -0,0 +1,24 @@ +--- +title: > + Spring clean before upgrading +pubDate: 2023-09-05 +permalink: >- + archive/2023/09/05/spring-clean-before-upgrading +tags: + - drupal + - software-upgrades +--- + +One of the first things I do when reviewing whether an application can be upgraded is to look for anything that can be removed. + +If it has modules that aren't used, uninstall and remove them. + +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. + +Remove any old themes that are no longer used. + +If you have content types, fields or views that aren't used, remove them, assuming you don't need the data. + +Remove unused routes, Controllers or other classes not used in custom modules, or any other unused custom code. + +Less moving parts means less to upgrade now and maintain in the future. diff --git a/source/_daily_emails/2023-09-06.md b/source/_daily_emails/2023-09-06.md new file mode 100644 index 000000000..3a9826127 --- /dev/null +++ b/source/_daily_emails/2023-09-06.md @@ -0,0 +1,25 @@ +--- +title: > + Verbosity over abstraction +pubDate: 2023-09-06 +permalink: >- + archive/2023/09/06/verbosity-over-abstraction +tags: + - software-development +--- + +Recently, a steamer said they "prefer verbosity over abstraction/confusion". + +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. + +It was clear to anyone working on that project what that service did, now and in the future. + +I prefer this to shorter, less-descriptive names. + +I hardly ever create a variable called `$x`, `$k` or `$v`. I only would if it was clear what it meant within its context. + +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. + +I prefer not to use PHP functions like `compact` and to write it out and avoid the abstraction and any confusion it could cause. + +I prefer code to be verbose, descriptive and easy to read, understand and change. diff --git a/source/_daily_emails/2023-09-07.md b/source/_daily_emails/2023-09-07.md new file mode 100644 index 000000000..046ed1d31 --- /dev/null +++ b/source/_daily_emails/2023-09-07.md @@ -0,0 +1,59 @@ +--- +title: > + What's the simplest test to begin with? +pubDate: 2023-09-07 +permalink: >- + archive/2023/09/07/what-s-the-simplest-test-to-begin-with +tags: + - software-development + - automated-testing + - test-driven-development + - php + - drupal +--- + +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. + +In the workshops I ran for DrupalCamp London and DrupalCamp NYC, I wanted to cover this first before writing any implementation code. + +Where do you put a test class, and what does it contain? + +How do you run the tests, and how can you make it pass or fail? + +## What we did + +To start, we wrote a test for existing functionality within Drupal core - anonymous users can visit the front page. + +This is the whole test: + +```php +drupalGet(''); + +    $this->assertResponse(Response::HTTP_OK); +  } + +} +``` + +This is a test someone can write, run and see the test pass. + +They can then experiment by changing the values to make the test fail in different ways. + +## What next? + +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. + +People were getting the idea by now, and we moved on to writing and testing some of our own code. diff --git a/source/_daily_emails/2023-09-08.md b/source/_daily_emails/2023-09-08.md new file mode 100644 index 000000000..a3a1dc81e --- /dev/null +++ b/source/_daily_emails/2023-09-08.md @@ -0,0 +1,24 @@ +--- +title: > + Do you proactively refactor your code? +pubDate: 2023-09-08 +permalink: >- + archive/2023/09/08/do-you-proactively-refactor-your-code +tags: + - software-development + - refactoring +--- + +Do you go back and proactively refactor code you've previously written? + +In my experience, once some code is working, it's usually not reviewed again and refactored, and any TODO comments are still there. + +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. + +Very rarely have I seen code be refactored to make it easier to read or change in the future. + +Do you proactively refactor code or wait until something forces it to happen? + +Do you not refactor code at all once it's been written? + +Reply to this email and let me know which and why. diff --git a/source/_daily_emails/2023-09-09.md b/source/_daily_emails/2023-09-09.md new file mode 100644 index 000000000..8ffd7634f --- /dev/null +++ b/source/_daily_emails/2023-09-09.md @@ -0,0 +1,26 @@ +--- +title: > + A lack of tests discourages refactoring +pubDate: 2023-09-09 +permalink: >- + archive/2023/09/09/a-lack-of-tests-discourages-refactoring +tags: + - automated-testing + - test-driven-development + - refactoring + - software-development +--- + +A common cause of not refactoring code is a lack of test coverage. + +Why change some code if it works? What if we break it whilst refactoring it and introduce a regression? + +If the code has accompanying automated tests, this can't happen. + +The tests should be passing before starting a refactor and should be passing once the refactor is complete. + +If the tests fail, the refactor was unsuccessful and should be reverted. + +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. + +Without tests, the code could be broken during the refactor, and we wouldn't know. diff --git a/source/_daily_emails/2023-09-10.md b/source/_daily_emails/2023-09-10.md new file mode 100644 index 000000000..da1490558 --- /dev/null +++ b/source/_daily_emails/2023-09-10.md @@ -0,0 +1,19 @@ +--- +title: > + Code is read more than it's written +pubDate: 2023-09-10 +permalink: >- + archive/2023/09/10/code-is-read-more-than-it-s-written +tags: + - software-development +--- + +A lot of code is written once by one person and not changed again. + +But it's read by multiple people at multiple times. + +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. + +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. + +If I need to review or work on the code in the future, I want to read and understand it easily. diff --git a/source/_daily_emails/2023-09-11.md b/source/_daily_emails/2023-09-11.md new file mode 100644 index 000000000..f75b4cc47 --- /dev/null +++ b/source/_daily_emails/2023-09-11.md @@ -0,0 +1,61 @@ +--- +title: > + Don't use "else" +pubDate: 2023-09-11 +permalink: >- + archive/2023/09/11/dont-use-else +tags: + - software-development + - clean-code +--- + + +A popular approach to writing clean code is to avoid the "else" keyword and, if possible, avoid nesting `if` statements within other `if` 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. + +## What should I do instead? + +Instead, you check for a condition; if that isn't met, you return early. +For example, here is some code I saw recently during a meetup talk: + +```php +$callingClass = $scope->getClassReflection()->getName(); + +if ($callingClass === TextMessageQueueProcessor::class) { +    return []; +} + +$type = $scope->getType($node->var); + +foreach ($type->getReferencedClasses() as $targetClass) { +    if ($targetClass === TextMessageSender::class) { +        return [ +            RuleErrorBuilder::message( +                sprintf( +                    "Can not call %s from %s", +                    $targetClass, +                    $callingClass +                ) +            )->build() +        ]; +    } +} + +return []; +``` + +There are no `else` statements. + +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. + +If the target class is one where the code shouldn't be called from, it returns immediately with the violation. + +Finally, if no violations were found within the referenced classes, it returns an empty array. + +## Here's the thing + +The code always returns an array of rule violations but does so as soon as possible at each point. + +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. + +Whilst there are some situations to use `else`, most of the time I've found that I can use an early return instead. diff --git a/source/_daily_emails/2023-09-12.md b/source/_daily_emails/2023-09-12.md new file mode 100644 index 000000000..8a4731b74 --- /dev/null +++ b/source/_daily_emails/2023-09-12.md @@ -0,0 +1,22 @@ +--- +title: > + Don't inject too many dependencies +pubDate: 2023-09-12 +permalink: >- + archive/2023/09/12/dont-inject-too-many-dependencies +tags: + - software-development + - clean-code +--- + +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. + +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. + +Having too many dependencies suggests that the class is doing too much and has too many responsibilities and that another class may be needed. + +## Here's the thing + +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). + +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? diff --git a/source/_daily_emails/2023-09-13.md b/source/_daily_emails/2023-09-13.md new file mode 100644 index 000000000..663219610 --- /dev/null +++ b/source/_daily_emails/2023-09-13.md @@ -0,0 +1,48 @@ +--- +title: > + Which type of test should I use? +pubDate: 2023-09-13 +permalink: >- + archive/2023/09/13/which-type-of-test-should-i-use +tags: + - drupal + - php + - automated-testing + - test-driven-development +--- + +Drupal offers a few different types of tests you can use, but how do you know which one to pick? + +This is how I decide based on what I need to test by asking these questions: + +## Do I need to test HTTP requests and responses? + +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? + +If so, use a `Functional` test like `BrowserTestBase`. + +## Do I need to test with JavaScript? + +`BrowserTestBase` doesn't include JavaScript, so use a `FunctionaJavaScript` test if needed. + +## Do I need to retrieve services from the service/Dependency Injection container? + +If I don't need to make HTTP requests but need access to the service container, I use a Kernel test such as `KernelTestBase`. + +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. + +There are different base classes, such as `EntityKernelTestBase`, that can be used depending on the situation to simplify the setup. + +## Can I test the code in isolation without the service container? + +If I can test the code without needing the service container and mock simple dependencies, then use a `Unit` test. + +These are very fast to run, but you can overuse mocks and sometimes test the mocks instead of the code you intended to test. + +## Here's the thing + +As well as the regular unit test type, Drupal offers various types of test that can be used depending on the situation. + +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. + +If you're just getting started with testing, they're probably the quickest to learn too. diff --git a/source/_daily_emails/2023-09-14.md b/source/_daily_emails/2023-09-14.md new file mode 100644 index 000000000..2d4a15486 --- /dev/null +++ b/source/_daily_emails/2023-09-14.md @@ -0,0 +1,25 @@ +--- +title: > + Outside-in or inside-out? +pubDate: 2023-09-14 +permalink: >- + archive/2023/09/14/outside-in-or-inside-out +tags: + - software-development + - automated-testing + - test-driven-development +--- + +[In yesterday's email][yesterday], I described the different types of tests available in Drupal and how to determine which test I should use. + +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. + +This is the outside-in approach to testing. + +The opposite is inside-out testing when you start with unit tests and have fewer functional tests. + +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. + +Which do you prefer? Reply and let me know. + +[yesterday]: https://www.oliverdavies.uk/archive/2023/09/13/which-type-of-test-should-i-use diff --git a/source/_daily_emails/2023-09-15.md b/source/_daily_emails/2023-09-15.md new file mode 100644 index 000000000..2a11d7484 --- /dev/null +++ b/source/_daily_emails/2023-09-15.md @@ -0,0 +1,53 @@ +--- +title: > + Types or no types +pubDate: 2023-09-15 +permalink: >- + archive/2023/09/15/types-or-no-types +tags: + - software-development + - types + - JavaScript + - TypeScript +--- + +Here are two versions of some example code I've recently been working on. + +One has types and uses TypeScript, the other is JavaScript and has no types. + +Which do you prefer and why? + +## TypeScript (with types) + +```js +add(...numbers: number[]): number { + return numbers.reduce((a: number, b: number) => a + b, 0); +} + +subtract(...numbers: number[]): number { + let total = numbers[0]; + + for (var i = 1, length = numbers.length; i < length; i++) { + total -= numbers[i]; + } + return total; +} +``` + +## JavaScript (no types) + +```js +add(...numbers){ + return numbers.reduce((a, b) => a + b, 0); +} + +subtract(...numbers) { + let total = numbers[0]; + + for (var i = 1, length = numbers.length; i < length; i++) { + total -= numbers[i]; + } + + return total; +} +``` diff --git a/source/_daily_emails/2023-09-16.md b/source/_daily_emails/2023-09-16.md new file mode 100644 index 000000000..67c1c19b0 --- /dev/null +++ b/source/_daily_emails/2023-09-16.md @@ -0,0 +1,60 @@ +--- +title: > + How not to break 36,000 websites +pubDate: 2023-09-16 +permalink: >- + archive/2023/09/16/how-not-to-break-36-000-websites +tags: + - drupal + - php + - automated-testing + - test-driven-development +--- + +I've maintained the Override Node Options module for Drupal since early 2012. + +I've maintained the Drupal 7 version and written new versions for Drupal 8 onwards. + +At the time of writing, the module is used on at least 36,244 active Drupal websites. + +I don't want to break 36,000 websites, and automated testing is my way of avoiding that. + +I have three examples of how automated testing helped me when working on this module. + +## Upgrading to Drupal 8 + +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. + +Then, I followed a test-driven development approach to get the test passing using the Drupal 7 code for reference. + +When the whole test suite was in place and passing, I knew there was feature parity between the two versions. + +## Resolving a large merge conflict + +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. + +However, the patch no longer applied to the code, which caused various merge conflicts. + +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. + +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. + +## Refactoring the code + +A few years ago, a colleague and I wanted to refactor the module code to make it more maintainable and easier to work on. + +Then, the module was used on around 30,000 websites, so this could have been risky. + +However, we had the test suite to ensure the functionality still worked and that our refactors were successful. + +If we broke something and introduced a regression, a test would fail, and we could fix it. + +Following the release containing the refactored code, there were no reported issues or regressions from the community. + +## Here's the thing + +Automated testing is about providing confidence. + +Confidence the software works as expected and is releasable, either to clients for custom software or consumers of open-source software. + +With a passing test suite, you can add and change code with confidence and without worrying about breaking it. diff --git a/source/_daily_emails/2023-09-17.md b/source/_daily_emails/2023-09-17.md new file mode 100644 index 000000000..53a434cea --- /dev/null +++ b/source/_daily_emails/2023-09-17.md @@ -0,0 +1,26 @@ +--- +title: > + How much refactoring should I be doing? +pubDate: 2023-09-17 +permalink: >- + archive/2023/09/17/how-much-refactoring-should-i-be-doing +tags: + - software-development + - test-driven-development + - automated-testing + - refactoring +--- + +I watched a webinar recently, and one of the panellists asked, "How much refactoring should I be doing?". + +The reply was, "More than you're doing now.". + +It was quite tongue-in-cheek, but I agree that, in general, code isn't refactored enough. + +One main reason is a fear of introducing regressions, and to avoid that, you need a good automated test suite. + +If you break the existing functionality whilst refactoring, you want the test suite to fail so you can identify and fix the regression. + +If the test suite passes, you can release the new code. + +How many tests and how much coverage do you need? There's no specfic answer - enough for you to be confident everything still works. diff --git a/source/_daily_emails/2023-09-18.md b/source/_daily_emails/2023-09-18.md new file mode 100644 index 000000000..69cf54a51 --- /dev/null +++ b/source/_daily_emails/2023-09-18.md @@ -0,0 +1,27 @@ +--- +title: > + Increasing test coverage with regression tests +pubDate: 2023-09-18 +permalink: >- + archive/2023/09/18/increasing-test-coverage-with-regression-tests +tags: + - software-development + - automated-testing + - test-driven-development +--- + +Automated test suites don't tell you everything works - they tell you what you've tested isn't broken. + +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. + +## What do we do? + +When you find a bug, try replicating it within an automated test before attempting to fix it. + +Once you have a failing test and can replicate the issue, go ahead and fix it. + +If the test passes, you know you've fixed the bug and solved the issue. + +## Here's the thing + +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. diff --git a/source/_daily_emails/2023-09-19.md b/source/_daily_emails/2023-09-19.md new file mode 100644 index 000000000..d35da4ad9 --- /dev/null +++ b/source/_daily_emails/2023-09-19.md @@ -0,0 +1,31 @@ +--- +title: > + Stop writing tests +pubDate: 2023-09-19 +permalink: >- + archive/2023/09/19/stop-writing-tests +tags: + - software-development + - test-driven-development + - automated-testing +--- + +A few years ago, I worked at an agency on a client project. + +We were writing automated tests and doing test-driven development. We were releasing features, and everything was going well. + +Mid-way through the project, we were told to stop writing tests as it was taking "too long". + +We did, and the number of bugs increased almost instantly. + +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. + +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. + +We started writing tests again later during that project, but the middle phase was the most stressful part, and the most bugs were created. + +## Here's the thing + +It's not just about how long it takes to write the tests. + +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. diff --git a/source/_daily_emails/2023-09-20.md b/source/_daily_emails/2023-09-20.md new file mode 100644 index 000000000..323708efe --- /dev/null +++ b/source/_daily_emails/2023-09-20.md @@ -0,0 +1,46 @@ +--- +title: > + Why I prefer types +pubDate: 2023-09-20 +permalink: >- + archive/2023/09/20/why-i-prefer-types +tags: + - software-development + - types + - javascript + - typescript +--- + +Whether it's PHP or JavaScript/TypeScript, I prefer type declarations in my code. + +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. + +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. + +Here's the code from my previous email on types from a few days ago, with and without the types declared: + +```js +add(...numbers) { + // ... +} + +subtract(...numbers) { + // ... +} + +add(...numbers: number[]): number { + // ... +} + +subtract(...numbers: number[]): number { + // ... +} +``` + +Without types, I can infer what the function accepts and returns, but that's based on my assumption, which could be incorrect. + +What if `numbers` was an array of strings of numbers - e.g. `['one', 'two', 'three']` - and what if instead of returning the result, it stored it in state to return from a different method like `equals()` or `calculate()`? + +With the type declarations included, I don't need to presume, infer or make best guesses. + +It's clear from just reading the code. diff --git a/source/_daily_emails/2023-09-21.md b/source/_daily_emails/2023-09-21.md new file mode 100644 index 000000000..64d5559c6 --- /dev/null +++ b/source/_daily_emails/2023-09-21.md @@ -0,0 +1,25 @@ +--- +title: > + Buggy software causes reputational damage +pubDate: 2023-09-21 +permalink: >- + archive/2023/09/21/buggy-software-causes-reputational-damage +tags: + - software-development + - automated-testing + - feature-flags + - continuous-integration + - continuous-delivery +--- + +As well as taking longer to fix than locally or in a failed CI pipeline, shipping buggy software to production causes reputational damage. + +If an application goes down or doesn't run as expected, it could get noticed by your customers, clients, or your clients' customers. + +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. + +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. + +Therefore, it's in everyone's interest to write high-quality and well-tested software. + +There will be fewer bugs, and by following practices such as feature flags and continuous integration and delivery, they can be fixed faster. diff --git a/source/_daily_emails/2023-09-22.md b/source/_daily_emails/2023-09-22.md new file mode 100644 index 000000000..c21cdc367 --- /dev/null +++ b/source/_daily_emails/2023-09-22.md @@ -0,0 +1,23 @@ +--- +title: > + Documentation and comments get stale. Tests don't. +pubDate: 2023-09-22 +permalink: >- + archive/2023/09/22/documentation-and-comments-get-stale +tags: + - software-development + - automated-testing + - static-analysis +--- + +I'm sure you've seen code comments that say the code will do something when, in fact, it does something different. + +Or documentation that has become outdated and stale and no longer correct. + +Automated tests and other tools, such as static analysis, are executable documentation, so they can't become stale. + +If the implementation code changes and no longer matches the tests, the tests will fail, and either the implementation or test can be updated. + +Then, if you need to refer to the test, as long as it's passing, you know what it shows is still applicable. + +The same can't be said for markdown files, Confluence pages, Word documents or other static documentation. diff --git a/source/_daily_emails/2023-09-23.md b/source/_daily_emails/2023-09-23.md new file mode 100644 index 000000000..55118e52f --- /dev/null +++ b/source/_daily_emails/2023-09-23.md @@ -0,0 +1,27 @@ +--- +title: > + Everyone tests their code, but not everyone writes automated tests +pubDate: 2023-09-23 +permalink: >- + archive/2023/09/23/not-everyone-writes-automated-tests +tags: + - software-development + - test-driven-development + - automated-testing +--- + +Everyone tests their code. + +No one writes code and ships it to production before testing it works. + +It's just that most Developers test their code manually. + +They write the code, switch to a browser or terminal, and run it. + +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. + +In this case, automated testing is a good option. + +Instead of filling in the form, have the tests do it for you. + +It will be quicker and more reliable than doing it manually. diff --git a/source/_daily_emails/2023-09-24.md b/source/_daily_emails/2023-09-24.md new file mode 100644 index 000000000..c9976d349 --- /dev/null +++ b/source/_daily_emails/2023-09-24.md @@ -0,0 +1,33 @@ +--- +title: > + Test to save your job +pubDate: 2023-09-24 +permalink: >- + archive/2023/09/24/test-to-save-your-job +tags: + - software-development + - automated-testing + - test-driven-development +--- + +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. + +Today's talk was by Matt Stauffer at one of the previous Laracon conferences. + +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". + +In this talk, Matt has a slide that goes further into this, titled "Test to save your job". + +## What Matt said + +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?" + +* What's most likely to break? +* What do I have the least control over? +* What are we about to refactor? +* What would make my clients stress out? +* What would make me stressed out? + +## What about you? + +Do you have any other ways to decide what code to test? Reply and let me know, as I'd love to know. diff --git a/source/_daily_emails/2023-09-25.md b/source/_daily_emails/2023-09-25.md new file mode 100644 index 000000000..c573d5cf2 --- /dev/null +++ b/source/_daily_emails/2023-09-25.md @@ -0,0 +1,27 @@ +--- +title: > + Should you use a staging environment? +pubDate: 2023-09-25 +permalink: >- + archive/2023/09/25/should-you-use-a-staging-environment +tags: + - software-development +--- + +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. + +**If I deploy this feature, will it break the website?** + +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. + +If they differ greatly, the staging environment offers no value. + +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. + +## Here's the thing + +The best situation I've experienced is where a sanitised snapshot was synced to all pre-production environments every night. + +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. + +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. diff --git a/source/_daily_emails/2023-09-26.md b/source/_daily_emails/2023-09-26.md new file mode 100644 index 000000000..9b86b120d --- /dev/null +++ b/source/_daily_emails/2023-09-26.md @@ -0,0 +1,36 @@ +--- +title: > + Which branch should be in which environment? +pubDate: 2023-09-26 +permalink: >- + archive/2023/09/26/which-branch-should-be-in-which-environment +tags: + - software-development + - git + - trunk-based-development + - feature-flags +--- + +A common question is which [Git] branch should be on which environment. + +Most projects I've worked on have two or more environments: production, staging (or test) and development. + +Earlier in my career, we used Git Flow heavily. A Git branching workflow based on having different branches - i.e. `develop`, `master` and any arbitrary short-lived feature, hotfix and release branches. + +These matched nicely with our three environments. + +Usually, the `develop` branch would be used in the development environment. The `master` branch would be on staging and a tagged release from `master` on production. + +## What about now? + +I prefer trunk-based development, where there is one long-lived branch to which everyone commits their changes. + +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. + +The mainline branch is used in all pre-production environments, such as staging and development. + +## What about differences between the environments? + +What if we need differences, such as a feature that must be enabled in a particular environment if the same code is on both? + +My go-to approach is feature flagging, and this approach is something I'll describe more in tomorrow's email. diff --git a/source/_daily_emails/2023-09-27.md b/source/_daily_emails/2023-09-27.md new file mode 100644 index 000000000..61353ffb6 --- /dev/null +++ b/source/_daily_emails/2023-09-27.md @@ -0,0 +1,28 @@ +--- +title: > + Separating environments with feature flags +pubDate: 2023-09-27 +permalink: >- + archive/2023/09/27/separating-environments-with-feature-flags +tags: + - software-development + - feature-flags +--- + +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. + +But if all environments have the same code, how can we have differences between them? + +What if we want a feature enabled on one environment and not the other? + +## Feature flags + +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. + +If a flag is enabled, execute the first block of code. Otherwise, execute the second. + +Now, you enable and disable the required feature flags for each environment. + +**The code is the same for all environments, but the enabled features and functionality are different.** + +Then, once the feature has been deployed and released in production, the feature flag can be removed. diff --git a/source/_daily_emails/2023-09-28.md b/source/_daily_emails/2023-09-28.md new file mode 100644 index 000000000..0b3143320 --- /dev/null +++ b/source/_daily_emails/2023-09-28.md @@ -0,0 +1,36 @@ +--- +title: > + Feature flags enable continuous integration +pubDate: 2023-09-28 +permalink: >- + archive/2023/09/28/feature-flags-enable-continuous-integration +tags: + - software-development + - git + - continuous-integration + - feature-flags +--- + +I was recently working on a feature over a few mob programming sessions. + +After the session, we implemented part of the feature but couldn't merge it as it wasn't complete. + +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). + +The commit prevented me from following continuous integration - where everyone commits and pushes their code a minimum of once daily. + +What if someone else wanted to look at that code between mob sessions? They couldn't, as it was only on my laptop. + +If I'd made a temporary branch, it would be outdated and behind other changes to our mainline branch. + +## Feature flags to the rescue + +As this commit was part of a larger change, it couldn't be merged, so we added a feature flag around it. + +The values were set to null and hidden by default, and populated by the new changes and displayed if the flag was enabled. + +## Here's the thing + +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. + +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. diff --git a/source/_daily_emails/2023-09-29.md b/source/_daily_emails/2023-09-29.md new file mode 100644 index 000000000..2095b65c4 --- /dev/null +++ b/source/_daily_emails/2023-09-29.md @@ -0,0 +1,36 @@ +--- +title: > + 92 changed files with 885 additions and 156 deletions +pubDate: 2023-09-29 +permalink: >- + archive/2023/09/29/92-changed-files-with-885-additions-and-156-deletions +tags: + - software-development + - automated-testing + - test-driven-development + - refactoring +--- + +Today, I refactored some code on a client's Drupal project I've been working on. + +This is what the commit says: + +> Showing 92 changed files with 885 additions and 156 deletions + +So, it's not a small refactor. + +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. + +The code is better, and the responsibilities of the modules are clearer. + +Whilst a large amount of those additions are adding test modules with test configuration, it's not a small refactor. + +## Here's the thing + +This is what it says at the bottom of the CI pipeline output: + +> OK (79 tests, 565 assertions) + +This is the same number of passing tests and assertions I had before I started the refactor, so I know the functionality still works. + +If I didn't have those tests, I wouldn't have done the refactor. diff --git a/source/_daily_emails/2023-09-30.md b/source/_daily_emails/2023-09-30.md new file mode 100644 index 000000000..532c5df12 --- /dev/null +++ b/source/_daily_emails/2023-09-30.md @@ -0,0 +1,34 @@ +--- +title: > + Automated testing offers repeatability +pubDate: 2023-09-30 +permalink: >- + archive/2023/09/30/automated-testing-offers-repeatability +tags: + - automated-testing + - test-driven-development +--- + +You work on feature or bug fix. + +It gets tested manually by you, a tester, and the person who requested the feature or reported the bug. + +It may get tested on multiple environments. + +It passes and it moved to production. + +But now it's live, it's not tested again. + +Although it works now, there's no guarantee it's not broken or regressed by subsequent changes. + +It's definitely not tested manually before every future release. + +## Here's the thing + +Automated testing offers repeatability. + +The tests pass, so the functionality works when you wrote it, and you can re-check it by re-running the test. + +The test suite can be run by Developers whilst working on other changes, before code review and before deployments. + +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. diff --git a/source/_daily_emails/2023-10-01.md b/source/_daily_emails/2023-10-01.md new file mode 100644 index 000000000..c444b9da5 --- /dev/null +++ b/source/_daily_emails/2023-10-01.md @@ -0,0 +1,26 @@ +--- +title: > + TDD: repeat and refactor +pubDate: 2023-10-01 +permalink: >- + archive/2023/10/01/tdd--repeat-and-refactor +tags: + - automated-testing + - software-development + - test-driven-development + - refactoring +--- + +With test-driven development, you start with a failing test and focus on getting it to pass. + +But what do you do once it's passing? + +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. + +Is there something you'd like to change within the implementation or test code? You can do that whilst the tests are passing. + +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. + +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. + +Then, once you've completed the refactoring, move back into the red/green phase with the next test failure. diff --git a/source/_daily_emails/2023-10-02.md b/source/_daily_emails/2023-10-02.md new file mode 100644 index 000000000..188b20171 --- /dev/null +++ b/source/_daily_emails/2023-10-02.md @@ -0,0 +1,37 @@ +--- +title: > + Only comment what needs to be commented +pubDate: 2023-10-02 +permalink: >- + archive/2023/10/02/only-comment-what-needs-to-be-commented +tags: + - software-development + - clean-code +--- + +"If you comment everything, people won't read them." + +"As soon as one comment is incorrect, the result will be ignored." + +These are two comments I heard recently referring to code comments. + +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. + +A solution to these is to only comment what needs to be commented. + +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. + +This is an example from an open source pull request: + +```php +/** + * An interface for field access override. + */ +interface FieldAccessOverrideInterface { +``` + +In my opinion, this doesn't add any value or additional context as it repeats what's already there. + +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. + +I think this is better than having comments everywhere, and I can focus on the ones that matter. diff --git a/source/_daily_emails/2023-10-03.md b/source/_daily_emails/2023-10-03.md new file mode 100644 index 000000000..ab7f4bc56 --- /dev/null +++ b/source/_daily_emails/2023-10-03.md @@ -0,0 +1,33 @@ +--- +title: > + There is no perfect solution +pubDate: 2023-10-03 +permalink: >- + archive/2023/10/03/there-is-no-perfect-solution +tags: + - software-development +--- + +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. + +Similarly, there isn't a perfect tool for every situation. + +You can use different tools and get the same outcome. + +In some of my early emails, I talked about `run` files and `just` - two ways to write project-specific commands or aliases that simplify complex commands or group multiple commands together. + +Both do the same thing, but each have pros and cons. + +`run` files are files written in Bash, which are more verbose but can run anywhere. + +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. + +I've had CI pipelines fail because they can't download just, and not because of anything in the application code. + +I like the simplicity of justfiles, though, and that the files are simpler. + +## Here's the thing + +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? + +There isn't a "one size fits all" solution that works for everyone all the time. diff --git a/source/_daily_emails/2023-10-04.md b/source/_daily_emails/2023-10-04.md new file mode 100644 index 000000000..868d3187f --- /dev/null +++ b/source/_daily_emails/2023-10-04.md @@ -0,0 +1,21 @@ +--- +title: > + The best solution is the one that gets the tests to pass +pubDate: 2023-10-04 +permalink: >- + archive/2023/10/04/the-best-solution-is-the-one-that-gets-the-tests-to-pass +tags: + - software-development + - automated-testing + - test-driven-development +--- + +As I said yesterday, there is no perfect solution or approach for every situation. + +However, when doing test-driven development, there is a best solution. + +The simplest thing that gets a failing test to pass. + +Whether it's hard-coding a return value or putting the initial logic in a Controller, that's the objective. + +Once the test is passing, you can refactor the code or continue writing tests, which will each have their own best solution. diff --git a/source/_daily_emails/2023-10-05.md b/source/_daily_emails/2023-10-05.md new file mode 100644 index 000000000..7b25a5d05 --- /dev/null +++ b/source/_daily_emails/2023-10-05.md @@ -0,0 +1,20 @@ +--- +title: > + Some solutions are good enough +pubDate: 2023-10-05 +permalink: >- + archive/2023/10/05/some-solutions-are-good-enough +tags: + - software-development + - technical-debt +--- + +Once you have a passing test and you're confident your code works as expected, what do you do next? + +Do you keep refactoring and changing it, or is it good enough? + +Do you need to extract additional classes and methods now, or as the test is passing, do you move on to the next task? + +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. + +Once it's shipped, because you have tests, you can confidently refactor it in the future. diff --git a/source/_daily_emails/2023-10-06.md b/source/_daily_emails/2023-10-06.md new file mode 100644 index 000000000..e3656bb1b --- /dev/null +++ b/source/_daily_emails/2023-10-06.md @@ -0,0 +1,19 @@ +--- +title: > + Software development is like going to the Dentist +pubDate: 2023-10-06 +permalink: >- + archive/2023/10/06/software-development-is-like-going-to-the-dentist +tags: + - software-development + - refactoring + - deployments +--- + +Working on software development tasks is like going to the Dentist. + +Releasing new features, bug fixes, dependency updates, and refactoring is better and less painful when done regularly. + +Doing these changes in small and regular batches is less risky than less frequent and larger releases. + +It's easier to identify the cause of any issues and correct course if things aren't going to plan. diff --git a/source/_daily_emails/2023-10-07.md b/source/_daily_emails/2023-10-07.md new file mode 100644 index 000000000..1e76e7b80 --- /dev/null +++ b/source/_daily_emails/2023-10-07.md @@ -0,0 +1,31 @@ +--- +title: > + A breakdown of tests from a current project +pubDate: 2023-10-07 +permalink: >- + archive/2023/10/07/a-breakdown-of-tests-from-a-current-project +tags: + - software-development + - automated-testing + - test-driven-development +--- + +I've just added the hundredth test to a client project I'm developing. + +I'm following [the outside-in approach](https://www.oliverdavies.uk/archive/2023/09/14/outside-in-or-inside-out), 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. + +Here's the breakdown of the different types of tests: + +* Functional - 57 tests, 180 assertions +* Kernel - 38 tests, 495 assertions +* Unit - 5 tests, 18 assertions + +The tests are run automatically in a CI pipeline by GitHub Actions and Docker and usually run in two or three minutes. + +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.S. Are you interested in automated testing and test-driven development? I'm speaking about it at DrupalCon Europe on the 17th of October! + +You can also pre-register for my free 7-day automated testing email course at https://opdavi.es/testing-email-course. diff --git a/source/_daily_emails/2023-10-08.md b/source/_daily_emails/2023-10-08.md new file mode 100644 index 000000000..0209b87bf --- /dev/null +++ b/source/_daily_emails/2023-10-08.md @@ -0,0 +1,25 @@ +--- +title: > + Is test-driven development difficult? +pubDate: 2023-10-08 +permalink: >- + archive/2023/10/08/is-test-driven-development-difficult +tags: + - software-development + - automated-testing + - test-driven-development + - continuous-integration + - trunk-based-development +--- + +I recently read a post where the writer said automated testing, test-driven development, continuous integration, trunk-based development, etc, are difficult. + +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. + +Continuous integration is pulling everyone else's code at least once daily and pushing yours to ensure it doesn't conflict. + +Test-driven development is writing failing tests before any implementation code and refactoring once it passes. + +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. + +Change can be the difficult part, not which brand you commit to, how often you push your code or when you write your tests. diff --git a/source/_daily_emails/2023-10-09.md b/source/_daily_emails/2023-10-09.md new file mode 100644 index 000000000..0923427a1 --- /dev/null +++ b/source/_daily_emails/2023-10-09.md @@ -0,0 +1,20 @@ +--- +title: > + Spotting new things in Drupal 10.1 +pubDate: 2023-10-09 +permalink: >- + archive/2023/10/09/spotting-new-things-in-drupal-10-1 +tags: + - php + - drupal +--- + +I've recently updated my [Drupal Docker example project][project] to Drupal 10.1.5 and have been spotting new things. + +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. + +Something I've loved since Drupal 8 is the constant new features and iterative improvements being added to Drupal core. + +I'm looking forward to finding more of these as I keep upgrading my Docker example project as well as others. + +[project]: https://github.com/opdavies/docker-example-drupal diff --git a/source/_daily_emails/2023-10-10.md b/source/_daily_emails/2023-10-10.md new file mode 100644 index 000000000..a22f3238c --- /dev/null +++ b/source/_daily_emails/2023-10-10.md @@ -0,0 +1,56 @@ +--- +title: > + Why use Composer to manage Drupal dependencies? +pubDate: 2023-10-10 +permalink: >- + archive/2023/10/10/why-use-composer-to-manage-drupal-dependencies +tags: + - software-development + - drupal + - php + - phpc + - composer +--- + +One of the initial negatives when Drupal 8 launched was introducing Composer, PHP's dependency manager, and how it could affect non-technical users. + +When I started doing Drupal, I downloaded the .tar.gz or .zip file of Drupal, extracted it, and placed it within my project. + +I did the same for any additional modules I needed. + +To update them, I needed to delete my files and repeat the process of downloading and replacing them. + +## Drush + +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. + +What if you needed to install a module like Pathauto, which has dependencies you also need to download and install? + +With Drush or downloading the files manually, you'd need to download the dependencies separately. + +## Composer + +Composer is a dependency manager, which means it can handle these dependencies for us. + +It looks at each project's `composer.json` file to find its dependencies and downloads them. + +For example, to install Pathauto, you run `composer require drupal/pathauto`. + +Within its output, you'll see this: + +```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) +``` + +As well as Pathauto, it's downloading its dependencies - ctools and pathauto. + +Instead of downloading three modules, we can do it with one command. + +In fact, we don't need to know what its dependencies are - Composer will do that. + +Also, updating the modules is just another simple command - `composer update`. + +While it may be intimidating to non-technical users, learning a few simple commands makes installing and updating modules much easier! diff --git a/source/_daily_emails/2023-10-11.md b/source/_daily_emails/2023-10-11.md new file mode 100644 index 000000000..32c6de8d5 --- /dev/null +++ b/source/_daily_emails/2023-10-11.md @@ -0,0 +1,25 @@ +--- +title: > + Do you need that module? +pubDate: 2023-10-11 +permalink: >- + archive/2023/10/11/do-you-need-that-module +tags: + - software-development + - drupal + - php +--- + +Drupal includes a lot of default functionality and additional core modules you can enable to extend it. + +There are also over 50,000 community-contributed modules you can download and add. + +But is it worth adding every module? + +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? + +Each module increases the number of updates you'll need to do to maintain the website. + +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? + +Some modules will be crucial to your website, others you can do without if you prefer a smaller maintenance overhead. diff --git a/source/_daily_emails/2023-10-12.md b/source/_daily_emails/2023-10-12.md new file mode 100644 index 000000000..12a981f9d --- /dev/null +++ b/source/_daily_emails/2023-10-12.md @@ -0,0 +1,22 @@ +--- +title: > + Business logic in template files? +pubDate: 2023-10-12 +permalink: >- + archive/2023/10/12/business-logic-in-template-files +tags: + - software-development + - drupal + - twig + - automated-testing +--- + +I've often heard and advocated for not "putting logic" in template files and having a separation of concerns. + +The templates should be as simple to read and change as possible, and any complicated logic should be moved elsewhere. + +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. + +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. + +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. diff --git a/source/_daily_emails/2023-10-13.md b/source/_daily_emails/2023-10-13.md new file mode 100644 index 000000000..298540e4a --- /dev/null +++ b/source/_daily_emails/2023-10-13.md @@ -0,0 +1,17 @@ +--- +title: > + Writing tests is an investment +pubDate: 2023-10-13 +permalink: >- + archive/2023/10/13/writing-tests-is-an-investment +tags: + - software-development + - automated-testing + - test-driven-development +--- + +It can take time to write automated tests and do test-driven development, but it is an investment in a project's future stability. + +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. + +Even though it takes time, it's time well spent. diff --git a/source/_daily_emails/2023-10-14.md b/source/_daily_emails/2023-10-14.md new file mode 100644 index 000000000..8844b9317 --- /dev/null +++ b/source/_daily_emails/2023-10-14.md @@ -0,0 +1,27 @@ +--- +title: > + Do you need to write tests for small or short-lived projects? +pubDate: 2023-10-14 +permalink: >- + archive/2023/10/14/do-you-need-to-write-tests-for-small-or-short-lived-projects +tags: + - software-development + - automated-testing + - test-driven-development +--- + +When does it make sense not to write automated tests? + +Tests prevent regressions in codebases that are changed and updated over time. + +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. + +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. + +Also, one of Drupal's key benefits is that you can build websites within the Drupal UI, without needing to write custom code. + +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. + +If you then need to add any custom code and functionality, you may want to add tests. + +Whilst there are some situations where not writing tests is reasonable, there are more reasons and situations when you should, compared to not. diff --git a/source/_daily_emails/2023-10-15.md b/source/_daily_emails/2023-10-15.md new file mode 100644 index 000000000..ca0175860 --- /dev/null +++ b/source/_daily_emails/2023-10-15.md @@ -0,0 +1,14 @@ +--- +title: > + Off to DrupalCon +pubDate: 2023-10-15 +permalink: >- + archive/2023/10/15/off-to-drupalcon +tags: + - drupal + - drupalcon +--- + +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. + +I'll be taking a short break from these emails to enjoy the conference, focus on my talk, and finish my free email course on automated testing in Drupal. diff --git a/source/_daily_emails/2023-10-23.md b/source/_daily_emails/2023-10-23.md new file mode 100644 index 000000000..7546239ec --- /dev/null +++ b/source/_daily_emails/2023-10-23.md @@ -0,0 +1,31 @@ +--- +title: > + When should you run your tests? +pubDate: 2023-10-23 +permalink: >- + archive/2023/10/23/when-should-run-your-tests +tags: + - software-development + - automated-testing + - test-driven-development +--- + +After my talk at DrupalCon, I was asked when you should run your tests. + +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. + +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. + +## What about CI pipelines? + +As well as running tests manually, I'd add them to a CI pipeline, such as GitHub Actions, GitLab CI or Bitbucket Pipelines. + +There, tasks can be run automatically each time a commit is pushed, so you don't need to rely on them being run manually. + +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. + +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. + +This answers the main "Does it work?" question, and allows the reviewer to focus on reviewing the code and suggesting improvements. + +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. diff --git a/source/_daily_emails/2023-10-24.md b/source/_daily_emails/2023-10-24.md new file mode 100644 index 000000000..7cf05a935 --- /dev/null +++ b/source/_daily_emails/2023-10-24.md @@ -0,0 +1,31 @@ +--- +title: > + How to test code you didn't write +pubDate: 2023-10-24 +permalink: >- + archive/2023/10/24/how-to-test-code-you-didnt-write +tags: + - software-development + - automated-testing + - test-driven-development +--- + +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. + +This is tricky. If you didn't write the code, how can you know all the scenarios you need to test? + +Presumably, there is some documentation, Jira tickets, user stories or acceptance criteria from when the code was written that will help you with this. + +Decide the most critical functionality to be tested and focus on that, as that will provide the most value. + +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. + +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. + +**One test is better than none.** + +If you need to add any new features or fixes, ensure they have their own tests to keep a consistent level of coverage. + +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. + +Start with the most important test first and continue to add more iteratively. diff --git a/source/_daily_emails/2023-10-25.md b/source/_daily_emails/2023-10-25.md new file mode 100644 index 000000000..344573032 --- /dev/null +++ b/source/_daily_emails/2023-10-25.md @@ -0,0 +1,29 @@ +--- +title: > + Automated tests prevent regressions when upgrading +pubDate: 2023-10-25 +permalink: >- + archive/2023/10/25/automated-tests-prevent-regressions-when-upgrading +tags: + - software-development + - php + - drupal + - automated-testing + - test-driven-development +--- + +With Drupal 9 almost being end-of-life and unsupported, I've recently been doing a lot of Drupal 9 to 10 upgrade work. + +As it's a major version update, there are breaking changes that mean you may need to change your code. + +Here's an example of an error caused by a breaking change: + +> 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(). + +To fix this, you need to call the `accessCheck()` method before executing a query and specify whether it should be checked. + +But how do you know if it should be checked? + +If you have automated tests that pass beforehand and still pass afterwards, you picked the correct option. + +If the test passes before and fails afterwards, you found the bug and can fix it immediately to ensure the functionality works as before. diff --git a/source/_daily_emails/2023-10-26.md b/source/_daily_emails/2023-10-26.md new file mode 100644 index 000000000..497a0a66c --- /dev/null +++ b/source/_daily_emails/2023-10-26.md @@ -0,0 +1,34 @@ +--- +title: > + Is decoupled Drupal still a thing? +pubDate: 2023-10-26 +permalink: >- + archive/2023/10/26/is-decoupled-drupal-still-a-thing +tags: + - software-development + - drupal + - decoupled-drupal + - vuejs +--- + +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. + +[I gave a conference talk][talk] about how to use Drupal as a backend application for a Vue.js frontend. + +Recently, though, I haven't heard much about it. + +Some previous advocates have moved back to the more traditional approach. + +Interestingly, though, I did hear quite a bit about it at DrupalCon and about Drupal and Next.js in particular. + +I want to try using Drupal with Astro in the future and see what the landscape is like now. + +## What about you? + +Do you use Drupal in a decoupled or headless way? If so, what do you use for the frontend? + +If not, or if you've moved back to a more traditional approach, why? + +Reply and let me know. + +[talk]: https://www.oliverdavies.uk/talks/decoupling-drupal-vuejs diff --git a/source/_daily_emails/2023-10-27.md b/source/_daily_emails/2023-10-27.md new file mode 100644 index 000000000..4735fe6de --- /dev/null +++ b/source/_daily_emails/2023-10-27.md @@ -0,0 +1,38 @@ +--- +title: > + Work with me and support the Drupal Association +pubDate: 2023-10-27 +permalink: >- + archive/2023/10/27/work-with-me-and-support-the-drupal-association +tags: + - drupal + - open-source + - php + - phpc +--- + +I used to work for the [Drupal Association][association] - the non-profit organisation that supports the Drupal project, organises DrupalCon, and maintains Drupal.org. + +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. + +At DrupalCon, one of the keynote speakers said, "The Drupal Association is a small but mighty team". + +On the [Association staff page][staff], there are 15 staff members listed, including only five people in the Engineering team. + +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. + +However, it's "free as in puppies". You can have the puppy for free, but it costs time and money to look after it. + +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. + +## Here's the thing + +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 [team coaching] service. + +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. + +**Work with me and support the Drupal Association.** + +[association]: https://www.drupal.org/association +[staff]: https://www.drupal.org/association/staff +[team coaching]: https://www.oliverdavies.uk/team-coaching diff --git a/source/_daily_emails/2023-10-28.md b/source/_daily_emails/2023-10-28.md new file mode 100644 index 000000000..4c79f7846 --- /dev/null +++ b/source/_daily_emails/2023-10-28.md @@ -0,0 +1,19 @@ +--- +title: > + Can you move faster without tests? +pubDate: 2023-10-28 +permalink: >- + archive/2023/10/28/can-you-move-faster-without-tests +tags: + - software-development + - automated-testing + - test-driven-development +--- + +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. + +But, once you start changing the code to add new features or fix bugs, things will begin to slow down. + +You'll have more to test and need to ensure you don't break the existing functionality as well as your new code works. + +Whilst it may be faster initially, skipping tests will cause problems later. diff --git a/source/_daily_emails/2023-10-29.md b/source/_daily_emails/2023-10-29.md new file mode 100644 index 000000000..ef3028ac2 --- /dev/null +++ b/source/_daily_emails/2023-10-29.md @@ -0,0 +1,22 @@ +--- +title: > + I can drive my car blindfolded, but is it a good idea? +pubDate: 2023-10-29 +permalink: >- + archive/2023/10/29/i-can-drive-my-car-blindfolded-but-is-it-a-good-idea +tags: + - software-development + - automated-testing + - test-driven-development +--- + +After sending [yesterday's email][yesterday], Dave Hall replied [with a LinkedIn comment][comment] I liked and wanted to share (done with permission): + +> 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. +> +> I tend to think of skipping automated tests in the same way. + +Just because you can do something, it doesn't mean you should. + +[comment]: https://www.linkedin.com/feed/update/urn:li:activity:7124401304315027456 +[yesterday]: https://www.oliverdavies.uk/archive/2023/10/28/can-you-move-faster-without-tests diff --git a/source/_daily_emails/2023-10-30.md b/source/_daily_emails/2023-10-30.md new file mode 100644 index 000000000..36135e1a8 --- /dev/null +++ b/source/_daily_emails/2023-10-30.md @@ -0,0 +1,25 @@ +--- +title: > + Is Drupal a CMS or a framework? +pubDate: 2023-10-30 +permalink: >- + archive/2023/10/30/is-drupal-a-cms-or-a-framework +tags: + - php + - phpc + - drupal +--- + +Drupal is typically called a CMS (content management system) - somewhere you add and edit the content for your website. + +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. + +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. + +But as well as a content management framework, Drupal could also be considered an application framework like Symfony or Laravel. + +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. + +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! + +Drupal offers much more than just managing content. diff --git a/source/_daily_emails/2023-10-31.md b/source/_daily_emails/2023-10-31.md new file mode 100644 index 000000000..ba6221254 --- /dev/null +++ b/source/_daily_emails/2023-10-31.md @@ -0,0 +1,33 @@ +--- +title: > + One official Drupal development environment? +pubDate: 2023-10-31 +permalink: >- + archive/2023/10/31/one-official-drupal-development-environment +tags: + - drupal + - php +--- + +Yesterday, I read [a post by Kevin Quillen][post] titled 'DDEV being considered as the "official" Drupal development environment'. + +I've been a DDEV user, and I've also used most, if not all, of the other popular Drupal development environments. + +These days, I use [my own Docker Compose-based setup][mine], 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. + +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. + +## Collaboration is key + +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. + +## But what about existing teams and projects? + +If your company or team already uses another option, you can continue to use it. + +If you have an existing solution, I don't think it will be removed or abandoned in the near future. + +But, for new Drupal users and teams, one official development environment would be a big plus. + +[mine]: https://www.oliverdavies.uk/archive/2022/08/21/2022-08-21 +[post]: https://kevinquillen.com/ddev-being-considered-official-drupal-development-environment diff --git a/source/_daily_emails/2023-11-01.md b/source/_daily_emails/2023-11-01.md new file mode 100644 index 000000000..d45ea432c --- /dev/null +++ b/source/_daily_emails/2023-11-01.md @@ -0,0 +1,26 @@ +--- +title: > + Drupal 9 is now end of life +pubDate: 2023-11-01 +permalink: >- + archive/2023/11/01/drupal-9-is-now-end-of-life +tags: + - drupal + - php +--- + +As of today, Drupal 9 is end-of-life and no longer supported. + +## Why? + +Drupal 9 relies on several other software projects, including Symfony, CKEditor, and Twig. + +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. + +## What do I do next? + +There will be no further releases of Drupal 9 so you need to upgrade. + +If you're stuck on Drupal 9, 8, or 7, get unstuck with a [Drupal upgrade roadmap][roadmap] and get directions how to upgrade to Drupal 10. + +[roadmap]: https://www.oliverdavies.uk/drupal-upgrade diff --git a/source/_daily_emails/2023-11-02.md b/source/_daily_emails/2023-11-02.md new file mode 100644 index 000000000..82d29ccd7 --- /dev/null +++ b/source/_daily_emails/2023-11-02.md @@ -0,0 +1,25 @@ +--- +title: > + Is code coverage an objective or guideline? +pubDate: 2023-11-02 +permalink: >- + archive/2023/11/02/is-code-coverage-an-objective-or-guideline +tags: + - software-development + - automated-testing + - test-driven-development +--- + +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. + +But is this an effective metric? + +In the same way as deleting failing tests to fix a pipeline, a code coverage amount can be faked. + +With this in mind, what if, instead of setting an objective such as 100% code coverage, you used it as a guideline? + +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? + +Would that be better than saying every line of code needs to be covered? + +Code coverage is something I'm thinking of using more, so I want to know what you think. diff --git a/source/_daily_emails/2023-11-03.md b/source/_daily_emails/2023-11-03.md new file mode 100644 index 000000000..c2d05208d --- /dev/null +++ b/source/_daily_emails/2023-11-03.md @@ -0,0 +1,28 @@ +--- +title: > + Why your company should contribute to open-source software +pubDate: 2023-11-03 +permalink: >- + archive/2023/11/03/why-your-company-should-contribute-to-open-source-software +tags: + - software-development + - open-source +--- + +I've always thought companies should contribute to open-source software. + +Whether it's financial or contributing time, if companies use free, open-source software (and especially if they're directly making money from it). + +Contributing to the software you use will improve the software, whether adding new features, fixing a bug, or contributing translations. + +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. + +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. + +## Here's the thing... + +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. + +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. + +If your company can contribute to open-source, I'd encourage them to do so and help support open-source software projects and communities. diff --git a/source/_daily_emails/2023-11-04.md b/source/_daily_emails/2023-11-04.md new file mode 100644 index 000000000..16eb0021d --- /dev/null +++ b/source/_daily_emails/2023-11-04.md @@ -0,0 +1,26 @@ +--- +title: > + Why you should contribute to open-source software +pubDate: 2023-11-04 +permalink: >- + archive/2023/11/04/why-you-should-contribute-to-open-source-software +tags: + - software-development + - open-source +--- + +[Yesterday's email][yesterday] explained why your company should contribute to open-source software, but why should you contribute as an individual? + +Most of the same reasons apply, such as gaining experience and improved knowledge from contributing. + +As an individual, you can build your own reputation and personal brand. + +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. + +This could lead to better career opportunities and potential projects. + +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. + +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. + +[yesterday]: https://www.oliverdavies.uk/archive/2023/11/03/why-your-company-should-contribute-to-open-source-software diff --git a/source/_daily_emails/2023-11-05.md b/source/_daily_emails/2023-11-05.md new file mode 100644 index 000000000..8c4f9e526 --- /dev/null +++ b/source/_daily_emails/2023-11-05.md @@ -0,0 +1,21 @@ +--- +title: > + I'm starting a podcast +pubDate: 2023-11-05 +permalink: >- + archive/2023/11/05/i-m-starting-a-podcast +tags: + - software-development + - podcast +--- + +This week, I'm starting my own podcast - [Beyond Blocks][podcast]. + +I'll be interviewing different people in every week, focussing on Drupal and related software development topics. + +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. + +If you'd like to be a guest, [get in touch][form] and let me know what you'd like to discuss. + +[form]: https://forms.gle/wdVqmEyQSWUx8cnm8 +[podcast]: https://www.oliverdavies.uk/podcast diff --git a/source/_daily_emails/2023-11-06.md b/source/_daily_emails/2023-11-06.md new file mode 100644 index 000000000..436e7e3ad --- /dev/null +++ b/source/_daily_emails/2023-11-06.md @@ -0,0 +1,24 @@ +--- +title: > + The first Beyond Blocks podcast episode is recorded +pubDate: 2023-11-06 +permalink: >- + archive/2023/11/06/the-first-beyond-blocks-podcast-episode-is-recorded +tags: + - software-development + - podcast + - drupal + - php +--- + +For my first time in the podcast host chair, I interviewed Matt Glaman - Principal Software Engineer at Acquia. + +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. + +We also talked briefly about PHPStan Drupal and drupal-check, which are some of Matt's other projects and contributions to the Drupal community. + +Thank you, Matt, for being the first guest on the Beyond Blocks podcast. + +I have other guests booked for this week, so the episode with Matt will be [published soon][podcast]. + +[podcast]: https://www.oliverdavies.uk/podcast diff --git a/source/_daily_emails/2023-11-07.md b/source/_daily_emails/2023-11-07.md new file mode 100644 index 000000000..2e021662e --- /dev/null +++ b/source/_daily_emails/2023-11-07.md @@ -0,0 +1,37 @@ +--- +title: > + It depends +pubDate: 2023-11-07 +permalink: >- + archive/2023/11/07/it-depends +tags: + - software-development +--- + +Usually, in software development, there isn't always a definitive black-and-white answer to a question or situation. + +Most of the time, the answer is "it depends". + +How you approach a problem depends on context. + +How long do you have? + +Are you working on the final version or a prototype or minimum-viable product? + +Should you use a contributed module or write one yourself? + +What if an existing module hasn't been updated for some time or doesn't have tests or other quality checks included? + +Do you write custom CSS or use a framework like Tailwind CSS or Bootstrap? + +Should this project be written in this framework or CMS, or would a different one be better suited? + +## Here's the thing... + +There are usually multiple approaches to achieve the same result. + +Decisions will depend on a combination of various factors. In a different situation, the answer could be different. + +This doesn't make any solution outright wrong. + +It was right given the situation. diff --git a/source/_daily_emails/2023-11-08.md b/source/_daily_emails/2023-11-08.md new file mode 100644 index 000000000..efe9aba6e --- /dev/null +++ b/source/_daily_emails/2023-11-08.md @@ -0,0 +1,28 @@ +--- +title: > + "Building Build Configs" at PHP South West +pubDate: 2023-11-08 +permalink: >- + archive/2023/11/08/building-build-configs +tags: + - software-development + - php + - public-speaking +--- + +This evening, I'm presenting a lightning talk at the PHP South West meetup in Bristol. + +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. + +Since creating it, I've used it for personal projects, projects for clients, and example projects on GitHub - such as [my Docker Example Drupal project][example]. + +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 [Drupal Commerce Kickstart example][commerce_example] at DrupalCon. + +[The slides are already online][slides] and I've created [an example video][video] where I go from nothing to a ready-to-work-on Drupal website in less than a minute! + +If you have any questions, hit reply and let me know! + +[commerce_example]: https://github.com/opdavies/docker-example-drupal-commerce-kickstart +[example]: https://github.com/opdavies/docker-example-drupal +[slides]: https://www.oliverdavies.uk/talks/building-build-configs +[video]: https://www.oliverdavies.uk/build-configs diff --git a/source/_daily_emails/2023-11-09.md b/source/_daily_emails/2023-11-09.md new file mode 100644 index 000000000..3927130d2 --- /dev/null +++ b/source/_daily_emails/2023-11-09.md @@ -0,0 +1,24 @@ +--- +title: > + README-driven development +pubDate: 2023-11-09 +permalink: >- + archive/2023/11/09/readme-driven-development +tags: + - software-development + - documentation +--- + +As well as test-driven development (TDD), I also like README-driven development - a.k.a. documentation-driven development. + +In short, you write the documentation first, followed by the code. + +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. + +This can also contain flowcharts, diagrams, example code snippets and anything else that would be useful. + +If you like, you could have a colleague review it in a pull/merge request before progressing. + +Once the README file is written and you're happy with its contents, you can start coding. + +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. diff --git a/source/_daily_emails/2023-11-10.md b/source/_daily_emails/2023-11-10.md new file mode 100644 index 000000000..0ae370848 --- /dev/null +++ b/source/_daily_emails/2023-11-10.md @@ -0,0 +1,23 @@ +--- +title: > + Retrofit with Matt Glaman +pubDate: 2023-11-10 +permalink: >- + archive/2023/11/10/retrofit-with-matt-glaman +tags: + - drupal + - php + - drupal-upgrades + - podcast + - beyond-blocks +--- + +Today, I released [the first episode of the "Beyond Blocks" podcast](https://www.oliverdavies.uk/podcast/1-retrofit). + +I spoke with Matt Glaman - Principal Software Engineer at Acquia and author of Retrofit. + +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. + +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. + +Future episodes will be [published online](https://www.oliverdavies.uk/podcast) 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. diff --git a/source/_daily_emails/2023-11-11.md b/source/_daily_emails/2023-11-11.md new file mode 100644 index 000000000..7d36712ce --- /dev/null +++ b/source/_daily_emails/2023-11-11.md @@ -0,0 +1,28 @@ +--- +title: > + Work in small batches +pubDate: 2023-11-11 +permalink: >- + archive/2023/11/11/work-in-small-batches +tags: + - software-development + - git + - continuous-integration + - continuous-delivery + - continuous-deployment + - trunk-based-development +--- + +Software should be designed, written, and deployed in small batches. + +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. + +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". + +Small batches mean faster feedback, more localised problems as there are fewer changes, and reduced risk and overhead. + +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. + +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. + +The full blog post is found at . diff --git a/source/_daily_emails/2023-11-12.md b/source/_daily_emails/2023-11-12.md new file mode 100644 index 000000000..cadd6fc45 --- /dev/null +++ b/source/_daily_emails/2023-11-12.md @@ -0,0 +1,33 @@ +--- +title: > + Drupal gives you so much out-of-the-box +pubDate: 2023-11-12 +permalink: >- + archive/2023/11/12/drupal-gives-you-so-much-out-of-the-box +tags: + - software-development + - drupal +--- + +When you download and install Drupal, you get so much functionality available out-of-the-box. + +For example: + +* Content creation and editing capabilities with a flexible content type +* A taxonomy system for categorising content. +* Tools for managing editorial workflows. +* User registration and authentication. +* A role-based permission system. +* Support for creating multilingual websites with translation tools. +* Caching mechanisms to optimise performance. +* Scalability features for handling high-traffic websites. +* Built-in search functionality. +* Robust security features, including input validation and output filtering. +* RESTful web services for building web applications and mobile apps. +* A flexible page and layout builder. + +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. + +You can add specific functionality by writing your own modules, and customise a project by creating a theme. + +It's a great choice for a new web project. diff --git a/source/_daily_emails/2023-11-13.md b/source/_daily_emails/2023-11-13.md new file mode 100644 index 000000000..8a6822c77 --- /dev/null +++ b/source/_daily_emails/2023-11-13.md @@ -0,0 +1,34 @@ +--- +title: > + PHPUnit does more than unit testing +pubDate: 2023-11-13 +permalink: >- + archive/2023/11/13/phpunit-does-more-than-unit-testing +tags: + - software-development + - automated-testing + - software-development + - test-driven-development + - phpunit + - php + - drupal + - symfony +--- + +As the name suggests, [PHPUnit][] is a unit testing framework for PHP. + +It's the defacto PHP testing framework used by the major PHP projects, such as Drupal, Symfony, Laravel. + +But unit testing isn't all that PHPUnit can do. + +These frameworks extend PHPUnit to give it more functionality. + +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. + +Symfony does the same with its web and kernel test cases. + +## Here's the thing + +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. + +[phpunit]: http://phpunit.de diff --git a/source/_daily_emails/2023-11-14.md b/source/_daily_emails/2023-11-14.md new file mode 100644 index 000000000..a124f35a9 --- /dev/null +++ b/source/_daily_emails/2023-11-14.md @@ -0,0 +1,26 @@ +--- +title: > + Why I prefer integration tests to unit tests +pubDate: 2023-11-14 +permalink: >- + archive/2023/11/14/why-i-prefer-integration-tests-to-unit-tests +tags: + - software-development + - automated-testing + - test-driven-development + - mocking +--- + +With unit tests, you need to mock __everything__. + +If what you're testing has a dependency, you need to create and use a mock version. + +If the mock has its own dependencies, you need to mock those, too. + +I've written unit tests with mocks and accidentally only tested the mocks instead of the functionality I intended. + +## Here's the thing + +With integration tests, you can use and test the real dependencies. + +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. diff --git a/source/_daily_emails/2023-11-15.md b/source/_daily_emails/2023-11-15.md new file mode 100644 index 000000000..0549dfc70 --- /dev/null +++ b/source/_daily_emails/2023-11-15.md @@ -0,0 +1,33 @@ +--- +title: > + Don't pre-optimise and over-customise +pubDate: 2023-11-15 +permalink: >- + archive/2023/11/15/dont-pre-optimise-and-over-customise +tags: + - software-development + - clean-code + - automated-testing + - test-driven-development +--- + +I've been re-watching a livestream series from a few years ago, showing a SaaS product being built. + +The series was created from two full-day live streams to create a minimum viable product (MVP) version of the application. + +Several times, things like this were said: + +* This will eventually need to be customisable. +* When we have multiple users, but now we only have one. +* Let's hard-code this for now and refactor it later. +* This isn't pixel-perfect, but let's move on. + +## Here's the thing + +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. + +If there's only one user, there's no need to write code to handle multiple users. + +Later, once the application is launched, that feature can be added. + +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. diff --git a/source/_daily_emails/2023-11-16.md b/source/_daily_emails/2023-11-16.md new file mode 100644 index 000000000..e6d5bc730 --- /dev/null +++ b/source/_daily_emails/2023-11-16.md @@ -0,0 +1,90 @@ +--- +title: > + Avoiding over-mocking +pubDate: 2023-11-16 +permalink: >- + archive/2023/11/16/avoiding-over-mocking +tags: + - software-development + - automated-testing + - test-driven-development +--- + +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. + +Here's an example (thanks, ChatGPT, for the code). + +## The Class to be tested (MyClass.php) + +```php +dependency->performAction(); + + return "Result: " . $result; + } +} +``` + +## Dependency Interface (DependencyInterface.php) + +```php +createMock(DependencyInterface::class); + + // Setting up the mock to return a specific value. + $dependencyMock->expects($this->once()) + ->method('performAction') + ->willReturn('Mocked result'); + + // Creating an instance of MyClass with the mock. + $myClass = new MyClass($dependencyMock); + + // Calling the method to be tested. + $result = $myClass->doSomething(); + + // Asserting that the result matches the expected value. + $this->assertEquals('Result: Mocked result', $result); + } + +} +``` + +## Here's the thing + +In this example, the test creates a mock for the `DependencyInterface` and sets up an expectation that the performAction method will be called once, returning a specific value. + +The test then calls the `doSomething` method on `MyClass` and asserts that the result is as expected. + +The issue with this test is that it's not testing the actual behaviour of `MyClass`. + +It's only testing that the mock is configured correctly. + +If the real implementation of `MyClass` has a bug, this test won't catch it. diff --git a/source/_daily_emails/2023-11-17.md b/source/_daily_emails/2023-11-17.md new file mode 100644 index 000000000..8d59b7cb0 --- /dev/null +++ b/source/_daily_emails/2023-11-17.md @@ -0,0 +1,19 @@ +--- +title: > + Drupal's Alternate Realities +pubDate: 2023-11-17 +permalink: >- + archive/2023/11/17/drupal-s-alternate-realities +tags: + - drupal + - php + - phpc + - beyond-blocks + - podcast +--- + +[This week's episode][episode] of the Beyond Blocks podcast is live, where I speak with Panagiotis Moutsopoulos (vensires on Drupal.org) - Drupal Backend Developer at E-Sepia. + +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. + +[episode]: https://www.oliverdavies.uk/podcast/2-alternate-realities diff --git a/source/_daily_emails/2023-11-18.md b/source/_daily_emails/2023-11-18.md new file mode 100644 index 000000000..7aaa83dcc --- /dev/null +++ b/source/_daily_emails/2023-11-18.md @@ -0,0 +1,48 @@ +--- +title: > + Writing good test names +pubDate: 2023-11-18 +permalink: >- + archive/2023/11/18/writing-good-test-names +tags: + - software-development + - test-driven-development + - automated-testing + - php + - phpunit +--- + +In PHPUnit, there are different ways to write test methods. + +The standard way is to use camel-case method names with a `test` prefix, for example: + +```php +public function testTheProjectNameShouldBeAString(): void +{ + // ... +} +``` + +Another popular way, particularly in some frameworks, is to use snake-case method names: + +```php +/** @test */ +public function the_project_name_should_be_a_string(): void +{ + // ... +} +``` + +This may be more readable but only works if the `@test` annotation is present. + +What if you need to add another annotation, such as `@dataProvider` to the test? Do you do multi-line docblocks everywhere, or mix and match single and multiple line docblocks depending on the test? + +## Here's the thing + +My preference switches between both ways of writing test methods. + +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. + +I avoid short and generic names like `testUpdate()`. + +People should be able to read the test name and understand what it does and what it's testing. diff --git a/source/_daily_emails/2023-11-19.md b/source/_daily_emails/2023-11-19.md new file mode 100644 index 000000000..3a661d19b --- /dev/null +++ b/source/_daily_emails/2023-11-19.md @@ -0,0 +1,26 @@ +--- +title: > + Why I've standardised on 'run' scripts +pubDate: 2023-11-19 +permalink: >- + archive/2023/11/19/why-ive-standardised-on-run-scripts +tags: + - software-development + - continuous-integration +--- + +In some of my first emails to this list, I wrote about `just` and `run` files. + +Both allow you to write project-specific aliases and commands. For example, instead of running `docker compose exec php phpunit`, you run `just test` or `run test`. + +While `just` uses a simple Makefile-like syntax, it requires its own program, so it needs to be installed. + +While I have it installed locally, I've had instances where CI pipelines have failed because they can't download and install `just` and not because of an error in my code. + +## Here's the thing + +A `run` script is a file of Bash functions. + +Because it's written in Bash, it runs anywhere without installing additional dependencies. + +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. diff --git a/source/_daily_emails/2023-11-20.md b/source/_daily_emails/2023-11-20.md new file mode 100644 index 000000000..b02b74f88 --- /dev/null +++ b/source/_daily_emails/2023-11-20.md @@ -0,0 +1,35 @@ +--- +title: > + What'll be in Drupal 11? +pubDate: 2023-11-20 +permalink: >- + archive/2023/11/20/whatll-be-in-drupal-11 +tags: + - drupal + - php + - phpc +--- + +Drupal 9 is end-of-life and no longer supported. + +Drupal 10 is the current stable version, and the development branch for Drupal 11 has just been started. + +But what will be in Drupal 11? + +Well, we don't know yet. + +Drupal's release schedule is based on fixed dates and not on features. + +Whatever is ready on the release date will be included. If something isn't ready, it'll be in a future version. + +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. + +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. + +## Here's the thing + +But, like Drupal 9 and 10, Drupal 11 won't mean a major rewrite to your code. + +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. + +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. diff --git a/source/_daily_emails/2023-11-21.md b/source/_daily_emails/2023-11-21.md new file mode 100644 index 000000000..71c40890c --- /dev/null +++ b/source/_daily_emails/2023-11-21.md @@ -0,0 +1,52 @@ +--- +title: > + Why I built "Build Configs" +pubDate: 2023-11-21 +permalink: >- + archive/2023/11/21/why-i-built-build-configs +tags: + - docker + - docker-compose + - php + - phpc + - drupal + - symfony +--- + +[Build Configs] is a tool I wrote and recently [gave a lightning talk about][talk] at the PHP South West meetup in Bristol, UK. + +It's a command-line tool that creates customised per-project configuration files from a set of reusable templates. + +It's a Symfony project using components such as Console, Validator, and Twig for templating. + +But why did I build it? + +## What was I doing before? + +When starting a new project, I'd copy configuration files from an existing project and alter them as needed. + +If a project uses a `docroot` directory instead of `web`, 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. + +## What was the issue with this? + +It took time to set up new projects, and there would be drift between them. + +I may have added a feature to one project, but it wouldn't exist in the one I was working on. + +If I needed to move a feature from one project to another, I needed to do it manually. + +## How does Build Configs solve the issue? + +Now, I have a canonical set of template files. + +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. + +I don't need to worry about drift between projects because they're all in sync and generated automatically. + +It's quicker to create and onboard projects using existing configurations instead of copying files and making manual changes. + +If you want to see an example, [watch this video][video] where I set up a new Drupal 10 project from nothing to running website in less than a minute. + +[build configs]: https://www.oliverdavies.uk/build-configs +[talk]: https://www.oliverdavies.uk/talks/building-build-configs +[video]: https://www.youtube.com/watch?v=LkhsdmxReUc diff --git a/source/_daily_emails/2023-11-22.md b/source/_daily_emails/2023-11-22.md new file mode 100644 index 000000000..2c2c51996 --- /dev/null +++ b/source/_daily_emails/2023-11-22.md @@ -0,0 +1,23 @@ +--- +title: > + Frequency reduces difficulty +pubDate: 2023-11-22 +permalink: >- + archive/2023/11/22/frequency-reduces-difficulty +tags: + - software-development + - agile + - continuous-delivery + - git + - trunk-based-development +--- + +"Frequency reduces difficulty" is a phrase I heard on a podcast today, though I have heard it before. + +It's a better way of saying, "If it hurts, do it more often". + +If software deployments and releases are large, risky, and contain bugs, break them into smaller, less-risky deployments and release them more often. + +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. + +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. diff --git a/source/_daily_emails/2023-11-23.md b/source/_daily_emails/2023-11-23.md new file mode 100644 index 000000000..ca64da906 --- /dev/null +++ b/source/_daily_emails/2023-11-23.md @@ -0,0 +1,50 @@ +--- +title: > + Partial mocking +pubDate: 2023-11-23 +permalink: >- + archive/2023/11/23/partial-mocking +tags: + - automated-testing + - test-driven-development + - drupal + - php + - phpunit + - phpc +--- + +Today, I wrote a test whilst fixing a bug in some legacy custom Drupal code. + +The code is for a custom block, which can be configured using user-defined settings - including a link URL. + +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. + +## My first attempt + +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. + +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. + +That failed quickly after having to enable various other custom modules due to dependencies and to add and configure unrelated configuration settings. + +## My second attempt + +My second attempt used kernel/integration tests, but as there's no `setParameter()` method on the route matcher I could use in the test, I'd need to rely on mocking. + +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. + +## The result + +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. + +Everything else remained the same. + +Then, I fixed the bug and used a data provider to provide different variables into the test so each use case was covered. + +## Here's the thing + +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. + +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. + +Whilst I'm aware of over-using mocks, this was an ideal situation to use them. diff --git a/source/_daily_emails/2023-11-24.md b/source/_daily_emails/2023-11-24.md new file mode 100644 index 000000000..f17e9c70a --- /dev/null +++ b/source/_daily_emails/2023-11-24.md @@ -0,0 +1,30 @@ +--- +title: > + Are conventional commits worth it? +pubDate: 2023-11-24 +permalink: >- + archive/2023/11/24/are-conventional-commits-worth-it +tags: + - software-development + - git +--- + +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 `feat`, `fix`, `chore`, `docs`, etc - and provide an optional scope before completing the subject line (the first line in the message). + +Then, it is encouraged to add a longer body to the message and provide any links and task IDs that the change relates to. + +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. + +I don't create automatic CHANGELOG files from the commit types. + +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). + +While I see value in writing descriptive commit messages, I'm unsure if I do to format the subject line in this way. + +## Here's the thing + +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. + +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? + +Which provides the most value when looking back at the Git log in the future? diff --git a/source/_daily_emails/2023-11-25.md b/source/_daily_emails/2023-11-25.md new file mode 100644 index 000000000..70ca6921a --- /dev/null +++ b/source/_daily_emails/2023-11-25.md @@ -0,0 +1,23 @@ +--- +title: > + Community engagement for non-technical Drupal enthusiasts +pubDate: 2023-11-25 +permalink: >- + archive/2023/11/25/community-engagement-for-non-technical-drupal-enthusiasts +tags: + - drupal + - drupalcon + - open-source + - contribution + - podcast +--- + +This week's guest on the Beyond Blocks podcast is Niklas Franke - Digital Marketing Manager at Factorial. + +Niklas was a fellow speaker at the recent DrupalCon conference in Lille - presenting multiple sessions, whilst Factorial were sponsors of the event. + +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. + +[Listen to the episode now][episode]. + +[episode]: https://www.oliverdavies.uk/podcast/3-non-technical-contribution diff --git a/source/_daily_emails/2023-11-26.md b/source/_daily_emails/2023-11-26.md new file mode 100644 index 000000000..002a24545 --- /dev/null +++ b/source/_daily_emails/2023-11-26.md @@ -0,0 +1,98 @@ +--- +title: > + To docblock or not to docblock +pubDate: 2023-11-26 +permalink: >- + archive/2023/11/26/to-docblock-or-not-to-docblock +tags: + - php + - phpstan + - static-analysis + - clean-code +--- + +## What are docblocks? + +Docblocks are comment blocks that describe a class or method and document its parameters and return types. + +Unfortunately, they're often overused and are outdated compared to the code they're describing, or repeat the same information again. + +For example, here's some PHP code: + +```php +function sayHello(string $name, array $options = ['shout' => false]): void { +     echo 'Hello, ' . $name; +} + +sayHello(''); +sayHello('Oliver', ['shout2' => true]); +sayHello('Oliver', ['shout' => 'banana']); +``` + +It's readable and understandable. + +It has types. + +We know that the name needs to be a string and that an array of options can be passed. + +This is how I like to write my code. In a clear and readable way with minimal comments. + +This code works, but there are issues with it. + +Do we want the name to potentially be an empty string? + +What if different options are passed in? + +## Step 1 + +If you use PHPStan (a PHP static analysis tool), you won't get any errors until you test against level 6. + +Then you'll get this error: + +> Function sayHello() has parameter $options with no value type specified in iterable type array. + +Now, we can use a docblock to provide more information to PHPStan to describe the structure of the `$options` array and that it has strings for keys and boolean values. + +```php +/** + * @param array $options + */ +``` + +Although it's not erroring, we can add the `$name` parameter and declare it as a `string`. + +```php +/** + * @param string $name + * @param array $options + */ +``` + +Now, the docblock adds some context and value but essentially repeats the defined types. + +## Step 2 + +We can do more with the docblock and tell PHPStan more about what we want the values to be. + +We don't want an empty string for a name and want the correct options and values. + +Let's change the docblock to this: + +```php +/** + * @param non-empty-string $name + * @param array{shout: bool} $options + */ +``` + +This specified the name cannot be an empty string and the shape of the options array. + +With this, we get these errors that weren't included before: + +* Parameter #1 $name of function sayHello expects non-empty-string, '' given. +* Parameter #2 $options of function sayHello expects array{shout: bool}, array{shout2: true} given. +* Parameter #2 $options of function sayHello expects array{shout: bool}, array{shout: 'banana'} given. + +## Here's the thing + +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. diff --git a/source/_daily_emails/2023-11-27.md b/source/_daily_emails/2023-11-27.md new file mode 100644 index 000000000..f4314166a --- /dev/null +++ b/source/_daily_emails/2023-11-27.md @@ -0,0 +1,99 @@ +--- +title: > + Finding the best test base +pubDate: 2023-11-27 +permalink: >- + archive/2023/11/27/finding-the-best-test-base +tags: + - software-development + - automated-testing + - test-driven-development + - php + - drupal +--- + +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. + +For example, if we have this test: + +```php +installEntitySchema(entity_type_id: 'node'); + $this->installEntitySchema(entity_type_id: 'user'); + } + + public function testExample(): void { + $user = $this->createUser(); + + $article = $this->createNode([ + 'title' => 'Test article', + 'uid' => $user, + ]); + + self::assertSame('1', $article->getOwnerId()); + } + +} +``` + +Both creation traits must be imported, the `node` and `user` modules must be enabled, and the entity tables must be installed. + +When writing a lot of tests, this can result in duplication and more complex tests that take longer to write. + +This can be simplified using `EntityKernelTestBase` instead of `KernelTestBase`: + +```php +createUser(); + + $article = $this->createNode([ + 'title' => 'Test article', + 'uid' => $user, + ]); + + self::assertSame('1', $article->getOwnerId()); + } + +} +``` + +The class is simpler, fewer modules must be specified, and the entity schemas are automatically installed. + +As well as the core modules, some contrib modules also provide their own base test cases. + +If you're using the Webform module, you may want to use `WebformAccessTestBase` instead of the standard `UnitTestCase`. + +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. diff --git a/source/_daily_emails/2023-11-28.md b/source/_daily_emails/2023-11-28.md new file mode 100644 index 000000000..efd52645e --- /dev/null +++ b/source/_daily_emails/2023-11-28.md @@ -0,0 +1,52 @@ +--- +title: > + Which PHPStan level should you use? +pubDate: 2023-11-28 +permalink: >- + archive/2023/11/28/which-phpstan-level-should-you-use +tags: + - software-development + - clean-code + - static-analysis + - phpstan +--- + +Which PHPStan level should you use? + +PHPStan has different levels. + +When you run it on your code, the errors you see will depend on what level you set. + +[In yesterday's email][yesterday], the first example code block didn't generate an error until level 5 was used. + +So, how do you know which level to use? + +## For greenfield projects + +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. + +If you work on a team, speak with the other members and decide how strict you want PHPStan to be. + +Read the rule levels and decide which are the most valuable for your team. + +If you haven't used PHPStan or static analysis before, maybe start with a lower level. + +For me, typehints and return type checking are a must, though I like to use as high a level as possible. + +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. + +## For brownfield projects + +For existing (brownfield) code, start at the lowest level, which will give you the least number of errors. + +Fix any errors, exclude any rules you want to ignore or generate a baseline containing any existing errors. + +If you like, increase the level and repeat the process. + +Keep increasing the level as long as you feel comfortable, and PHPStan gives you meaningful results. + +Again, if you haven't used PHPStan or static analysis before, maybe stick with a lower level. + +If you start with a lower level, you can increase it later. + +[yesterday]: https://www.oliverdavies.uk/archive/2023/11/27/finding-the-best-test-base diff --git a/source/_daily_emails/2023-11-29.md b/source/_daily_emails/2023-11-29.md new file mode 100644 index 000000000..24ed99d77 --- /dev/null +++ b/source/_daily_emails/2023-11-29.md @@ -0,0 +1,26 @@ +--- +title: > + The lowest level is better than no level +pubDate: 2023-11-29 +permalink: >- + archive/2023/11/29/the-lowest-level-is-better-than-no-level +tags: + - software-development + - clean-code + - static-analysis + - php + - phpstan +--- + +[Yesterday's email][yesterday] introduced the different levels that PHPStan offers and which you may want to use on your codebase. + +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. + +Level 0 includes: + +> 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.S. If you want to utilise PHPStan and static analysis on your development team and get fewer bugs, I have [availability for team coaching][coaching]. I'll show you how! + +[coaching]: https://www.oliverdavies.uk/team-coaching +[yesterday]: https://www.oliverdavies.uk/archive/2023/11/28/which-phpstan-level-should-you-use diff --git a/source/_daily_emails/2023-11-30.md b/source/_daily_emails/2023-11-30.md new file mode 100644 index 000000000..ae3cb0b87 --- /dev/null +++ b/source/_daily_emails/2023-11-30.md @@ -0,0 +1,28 @@ +--- +title: > + Are bugs good for users? +pubDate: 2023-11-30 +permalink: >- + archive/2023/11/30/are-bugs-good-for-users +tags: + - software-development + - automated-testing + - test-driven-development + - static-analysis +--- + +I recently listened to a podcast episode that was discussing if bugs are good for users. + +It suggested that bugs allowed for engagement between you and the user. + +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. + +While this may be true, I think that users would prefer applications that just work. + +If your application has major bugs, they may just go elsewhere. Maybe they won't even report the issue to you. + +Major bugs can damage your reputation with your users and potential customers, as well as affect potential sales. + +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. + +When a user reports it (if they do at all), it could be too late. diff --git a/source/_daily_emails/2023-12-01.md b/source/_daily_emails/2023-12-01.md new file mode 100644 index 000000000..0aa87dd58 --- /dev/null +++ b/source/_daily_emails/2023-12-01.md @@ -0,0 +1,32 @@ +--- +title: > + The contribution-first workflow +pubDate: 2023-12-01 +permalink: >- + archive/2023/12/01/the-contribution-first-workflow +tags: + - software-development + - open-source +--- + +I've worked on many software projects with a lot of custom code. + +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. + +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. + +But this rarely happens, as there's always the next sprint or project waiting. + +It takes too long to extract the code as it usually needs to be tidied or refactored beforehand. + +It may have been written with the client or project name within the code, which needs changing. + +My suggestion is to avoid this step. + +## Here's the thing + +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. + +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. + +Plus, you may get some issues, testing and improvements from others along the way. diff --git a/source/_daily_emails/2023-12-04.md b/source/_daily_emails/2023-12-04.md new file mode 100644 index 000000000..09b0c3da5 --- /dev/null +++ b/source/_daily_emails/2023-12-04.md @@ -0,0 +1,45 @@ +--- +title: > + Writing contrib modules as glue between your custom code +pubDate: 2023-12-04 +permalink: >- + archive/2023/12/04/writing-contrib-modules-as-glue-between-your-custom-code +tags: + - software-development + - contribution + - open-source + - drupal + - php +--- + + +A few years ago, I worked on an event booking and management website for a charity in the UK. + +One required piece of functionality was to allow event organisers to send a private message to all attendees of an event. + +We decided to use the [Private Message module] but were concerned about hitting memory limits or timeouts, as some events had several hundred attendees. + +We decided that we needed to use a queue and have it process and send the messages. + +This split the feature into three parts: + +* The UI for event organisers to enter and send their messages. +* The queue that stores and processes pending messages in the background. +* The Private Message module that would create and send each message, provide an inbox for each user, and provide notifications. + +The UI for event organisers was specific to the project and had to be custom code and not open-sourced. + +The Private Message module is already a contributed module, but what about the queue part? + +This is why the [Private Message Queue module] was created. + +Instead of keeping it within the project's custom code, we created it as an open-source module on Drupal.org. + +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. + +It provides the glue between our custom UI and the Private Message module. + +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. + +[private message module]: https://www.drupal.org/project/private_message +[private message queue module]: https://www.drupal.org/project/private_message_queue diff --git a/source/_daily_emails/2023-12-05.md b/source/_daily_emails/2023-12-05.md new file mode 100644 index 000000000..8a0e199f6 --- /dev/null +++ b/source/_daily_emails/2023-12-05.md @@ -0,0 +1,47 @@ +--- +title: > + Open-source encourages more open-source +pubDate: 2023-12-05 +permalink: >- + archive/2023/12/05/open-source-encourages-open-source +tags: + - software-development + - contribution + - open-source + - drupal + - php +--- + +[In yesterday's email][yesterday], I mentioned the Private Message Queue module - a contributed Drupal module we wrote for a project as part of a contribution-first workflow. + +In our experience, doing that and releasing Private Message Queue as its own open-source project encouraged more open-source contributions. + +We started to ask questions like, "Which user should the messages be sent from?". + +## System Users + +This led us to create the [System User module]. + +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. + +But what if a website doesn't have a system user? + +## Null Users + +This led to the [Null User module]. + +Following the Null object pattern, if there isn't a system user, instead of returning `NULL` or `FALSE`, 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. + +This pattern simplifies your code as you don't need to check for `NULL` or `FALSE` values. + +## Here's the thing + +If I remember correctly, as part of the project, we created and released around ten new contributed modules to Drupal.org. + +We were able to move straight onto the next phase of the project. + +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. + +[null user module]: https://www.drupal.org/project/null_user +[system user module]: https://www.drupal.org/project/system_user +[yesterday]: https://www.oliverdavies.uk/archive/2023/12/04/writing-contrib-modules-as-glue-between-your-custom-code diff --git a/source/_daily_emails/2023-12-06.md b/source/_daily_emails/2023-12-06.md new file mode 100644 index 000000000..c31d31052 --- /dev/null +++ b/source/_daily_emails/2023-12-06.md @@ -0,0 +1,27 @@ +--- +title: > + Open-source first doesn't mean you need to cover every use case +pubDate: 2023-12-06 +permalink: >- + archive/2023/12/06/open-source-first-doesnt-mean-you-need-to-cover-every-use-case +tags: + - software-development + - open-source + - contribution +--- + +An argument against the [contribution-first and open-source-first approach](https://www.oliverdavies.uk/archive/2023/12/01/the-contribution-first-workflow) is that it takes longer than writing custom code. + +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. + +My approach is to write the same code, whether it's private and custom or open-sourced. + +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. + +It doesn't get written if something isn't part of that objective. + +It could be added to a public roadmap for the future if it doesn't need to be part of the initial minimal version. + +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. + +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. diff --git a/source/_daily_emails/2023-12-07.md b/source/_daily_emails/2023-12-07.md new file mode 100644 index 000000000..564adacff --- /dev/null +++ b/source/_daily_emails/2023-12-07.md @@ -0,0 +1,20 @@ +--- +title: > + A Drupal case study from Oxfam +pubDate: 2023-12-07 +permalink: >- + archive/2023/12/07/a-drupal-case-study-from-oxfam +tags: + - software-development + - drupal + - php + - agile +--- + +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. + +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. + +[Listen to the episode now][listen]. + +[listen]: https://www.oliverdavies.uk/podcast/4-ed-crompton-oxfam-case-study diff --git a/source/_daily_emails/2023-12-08.md b/source/_daily_emails/2023-12-08.md new file mode 100644 index 000000000..d76f7924b --- /dev/null +++ b/source/_daily_emails/2023-12-08.md @@ -0,0 +1,22 @@ +--- +title: > + Don't just rewrite. Re-invent. +pubDate: 2023-12-08 +permalink: >- + archive/2023/12/08/dont-just-rewrite +tags: + - software-development + - neovimconf +--- + +A quote that stuck out to me from today's Neovimconf conference was this by Björn Linse (aka bfredl): + +> Don't just rewrite. Re-invent. +> +> If you're going to start over from scratch, reconsider everything. + +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. + +I'm discussing with someone whether to build a new Drupal theme or keep iterating on the existing one. + +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. diff --git a/source/_daily_emails/2023-12-09.md b/source/_daily_emails/2023-12-09.md new file mode 100644 index 000000000..74996f7c0 --- /dev/null +++ b/source/_daily_emails/2023-12-09.md @@ -0,0 +1,36 @@ +--- +title: > + Rebuild or iterate +pubDate: 2023-12-09 +permalink: >- + archive/2023/12/09/rebuild-or-iterate +tags: + - software-development + - drupal +--- + +As I said in [yesterday's email][yesterday], I'm discussing with a team how to implement their new website design. + +Their website has been live for a couple of years, and now they want to refresh its look and feel. + +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. + +There are two ways they could approach this: + +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. + +Alternatively, they could create a new theme from scratch. + +This would allow them to start with new build tools, a modern CSS framework and small and simple stylesheets. + +## Here's the thing + +There are advantages and disadvantages to both approaches. + +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. + +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. + +There isn't a right and wrong answer, and it will depend on the thoughts and objectives of the team and business. + +[yesterday]: https://www.oliverdavies.uk/archive/2023/12/08/dont-just-rewrite diff --git a/source/_daily_emails/2023-12-10.md b/source/_daily_emails/2023-12-10.md new file mode 100644 index 000000000..07423e2e1 --- /dev/null +++ b/source/_daily_emails/2023-12-10.md @@ -0,0 +1,29 @@ +--- +title: > + Suffixing names +pubDate: 2023-12-10 +permalink: >- + archive/2023/12/10/suffixing-names +tags: + - software-development + - php + - drupal + - symfony + - clean-code +--- + +When writing code, it's common to suffix the class name with the type of class it is. + +I do this often for most types of classes, such as Controllers, EventListeners, Factories, Repositories and Builders. + +However, I don't always for value objects and data transfer objects (DTOs). + +Also, I don't always suffix interfaces with `Interface`. + +I've been re-reading the documentation for the Symfony Serializer component, which references both `NameConverterInterface` and `MyDto::class`. + +Whilst it does make the names more verbose, it does clarify what the class is used for. + +Symfony's coding standards and Drupal's PHP coding standards have conventions for this, but what do you think? + +Do you add suffixes to your class or interface names, or do you prefer the simplified versions? diff --git a/source/_daily_emails/2023-12-11.md b/source/_daily_emails/2023-12-11.md new file mode 100644 index 000000000..744f1f95c --- /dev/null +++ b/source/_daily_emails/2023-12-11.md @@ -0,0 +1,44 @@ +--- +title: > + Custom coding standards and conventions +pubDate: 2023-12-11 +permalink: >- + archive/2023/12/11/custom-coding-standards-and-conventions +tags: + - software-development + - php + - drupal + - symfony + - clean-code +--- + +Open-source projects like Drupal and Symfony have their own published coding standards and conventions. + +For example, from [Symfony's coding standards][symfony]: + +* Prefix all abstract classes with `Abstract` except PHPUnit `*TestCase`. +* Suffix interfaces with `Interface`; +* Suffix traits with `Trait`; + +And from [Drupal's][drupal]: + +* Use an indent of 2 spaces, with no tabs. +* Lines should have no trailing whitespace at the end. +* Variables should be named using lowercase, and words should be separated either with uppercase characters (example: `$lowerCamelCase`) or with an underscore (example: `$snake_case`). Be consistent; do not mix camelCase and snake_case variable naming inside a file. + +But what about within custom applications? + +Do you have your own agreed coding standards and conventions to keep the code consistent? + +Do you explicitly follow the published coding standards, customise them, or follow something else? + +## Here's the thing + +Do you know where to put new custom modules, how to name them and what conventions to follow when writing code? + +Do you know where to add a new stylesheet to your theme? + +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. + +[drupal]: https://www.drupal.org/docs/develop/standards/php/php-coding-standards +[symfony]: https://symfony.com/doc/current/contributing/code/standards.html diff --git a/source/_daily_emails/2023-12-12.md b/source/_daily_emails/2023-12-12.md new file mode 100644 index 000000000..07bb826cb --- /dev/null +++ b/source/_daily_emails/2023-12-12.md @@ -0,0 +1,64 @@ +--- +title: > + DrupalCon session survey results +pubDate: 2023-12-12 +permalink: >- + archive/2023/12/12/drupalcon-session-survey-results +tags: + - software-development + - test-driven-development + - automated-testing + - php + - phpc + - drupal + - drupalcon +--- + +The survey results from my automated testing and test-driven development session at DrupalCon Lille are in, and here they are: + +## How would you rate the speaker(s)'s mastery of this topic? + +24 responses. + +* Excellent - 33.3% +* Very good - 50% +* Good - 16.7% +* Fair - 0% +* Poor - 0% + +## How would you rate the speaker(s)'s presentation skills? + +24 responses. + +* Excellent - 20.8% +* Very good - 37.5% +* Good - 33.3% +* Fair - 8.3% +* Poor - 0% + +## How would you rate the speaker(s)’s slides and other session materials? + +25 responses. + +* Excellent - 24% +* Very good - 32% +* Good - 36% +* Fair - 8% +* Poor - 0% + +## Overall, how would you rate this session? + +25 responses. + +* Excellent - 36% +* Very good - 28% +* Good - 36% +* Fair - 0% +* Poor - 0% + +Thanks to everyone who completed the survey for their feedback. + +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 [team coaching] and [private talks and workshops][workshops]. + +[team coaching]: https://www.oliverdavies.uk/team-coaching +[workshops]: https://www.oliverdavies.uk/pricing diff --git a/source/_daily_emails/2023-12-13.md b/source/_daily_emails/2023-12-13.md new file mode 100644 index 000000000..ca17ab6e7 --- /dev/null +++ b/source/_daily_emails/2023-12-13.md @@ -0,0 +1,42 @@ +--- +title: > + Reviving an old PHP project +pubDate: 2023-12-13 +permalink: >- + archive/2023/12/13/reviving-an-old-php-project +tags: + - php + - phpc + - open-source +--- + +I use Gmail/Google Apps for my email address, and I used to use a LOT of filters. + +Inspired by a Ruby gem, I created a PHP library that allows me to declare my filters in PHP and create them in XML. + +I could import the generated XML into Gmail to create the filters. + +## Gmail Filter Buider + +The project is [Gmail Filter Builder], and the last commit was in July 2020. + +It was based on PHP 7 (unsupported since November 2022) and uses five Symfony components and several other packages. + +Today, as I looked at my current Gmail filters, I decided to revisit and update Gmail Filter Builder. + +## Updating the project + +I set PHP 8.1 as the minimum required version and used a Nix Flake to ensure this was available. + +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. + +After some small changes to the application's code, it worked with PHP 8.1 and generated filters. + +Once it worked, I updated [the examples][examples]. + +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. + +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. + +[examples]: https://github.com/opdavies/gmail-filter-builder/tree/3.x/examples +[gmail filter builder]: https://github.com/opdavies/gmail-filter-builder/tree/3.x diff --git a/source/_daily_emails/2023-12-14.md b/source/_daily_emails/2023-12-14.md new file mode 100644 index 000000000..ae81cde70 --- /dev/null +++ b/source/_daily_emails/2023-12-14.md @@ -0,0 +1,28 @@ +--- +title: > + Save time and effort with Drupal distributions +pubDate: 2023-12-14 +permalink: >- + archive/2023/12/14/save-time-and-effort-with-drupal-distributions +tags: + - software-development + - drupal + - php + - phpc +--- + +Drupal distributions are pre-built versions of Drupal for specific use cases. + +Need an eCommerce store? Use Commerce Kickstart. + +Are you a local council looking for a new website? Look at LocalGov Drupal. + +Contenta CMS is an API-first Drupal distribution for headless and decoupled content. + +There are numerous others - each containing a list of pre-installed and configured modules to give you more functionality out of the box. + +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. + +Don't know if using a distribution could help for you? [Book a 1-on-1 consulting call][call], and I'll help you out. + +[call]: https://www.oliverdavies.uk/call diff --git a/source/_daily_emails/2023-12-15.md b/source/_daily_emails/2023-12-15.md new file mode 100644 index 000000000..b8e62cc3d --- /dev/null +++ b/source/_daily_emails/2023-12-15.md @@ -0,0 +1,23 @@ +--- +title: > + Building your own in-house Drupal distribution +pubDate: 2023-12-15 +permalink: >- + archive/2023/12/15/building-your-own-in-house-drupal-distribution +tags: + - software-development + - php + - drupal +--- + +On several occasions, I've seen companies who build a lot of Drupal projects creating their own in-house [Drupal distribution] for new projects. + +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. + +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. + +Alternatively, maybe keep a template composer.json file to base new projects on instead of a full distribution. + +That could declare the modules and themes you want to include, without the additional overhead. + +[drupal distribution](https://www.oliverdavies.uk/archive/2023/12/14/save-time-and-effort-with-drupal-distributions) diff --git a/source/_daily_emails/2023-12-16.md b/source/_daily_emails/2023-12-16.md new file mode 100644 index 000000000..f06e3bfe6 --- /dev/null +++ b/source/_daily_emails/2023-12-16.md @@ -0,0 +1,28 @@ +--- +title: > + Adding snapshot tests to Build Configs +pubDate: 2023-12-16 +permalink: >- + archive/2023/12/16/adding-snapshot-tests-to-build-configs +tags: + - software-development + - php + - symfony + - build-configs + - automated-testing + - test-driven-development +--- + +This week, I've started to add snapshot tests to the [Build Configs project][build configs]. + +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. + +With snapshot tests, I generate the files for each configuration and compare them to a set that I know to be correct. + +If the files match, the tests pass, but, if they don't - such as a bug in the code, the tests will fail. + +This is the level that I want to be testing this project and that provides the most value. + +If a snapshot test fails, I can try to replicate the underlying issue in a unit test whilst also fixing the snapshot test. + +[build configs]: https://www.oliverdavies.dev/build-configs diff --git a/source/_daily_emails/2023-12-17.md b/source/_daily_emails/2023-12-17.md new file mode 100644 index 000000000..ecd7f3800 --- /dev/null +++ b/source/_daily_emails/2023-12-17.md @@ -0,0 +1,34 @@ +--- +title: > + Fail fast, fix fast +pubDate: 2023-12-17 +permalink: >- + archive/2023/12/17/fail-fast-fix-fast +tags: + - software-development + - continuous-delivery + - continuous-deployment + - deployments + - feature-flags +--- + +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". + +In a software context, I'm not advocating that one in five production releases should fail, but I like trying new ideas and approaches. + +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. + +Using feature flags lets you quickly turn off a feature flag while investigating and resolving the issue without needing another deployment. + +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. + +Two of the DORA metrics refer to failure rate and restoration time: + +* Deployment frequency +* Lead time for changes +* Change failure rate +* Time to restore service + +Then, it depends on your organisation's tolerance for risk and what's acceptable. + +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. diff --git a/source/_daily_emails/2023-12-18.md b/source/_daily_emails/2023-12-18.md new file mode 100644 index 000000000..ed97d1b4c --- /dev/null +++ b/source/_daily_emails/2023-12-18.md @@ -0,0 +1,29 @@ +--- +title: > + Should you run static analysis on your tests? +pubDate: 2023-12-18 +permalink: >- + archive/2023/12/18/static-analysis-on-tests +tags: + - software-development + - php + - phpstan + - static-analysis + - automated-testing +--- + +I'm an advocate of both automated testing and static analysis but have mostly kept the two separate. + +I've typically not run PHPStan on my automated test files - ignoring them in my PHPStan configuration. + +As tests aren't production/implementation code, what's the benefit of analysing them? + +Recently, though, I've challenged this and, on some projects, started to run PHPStan on my test classes. + +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. + +If you have a bug in your test, static analysis will potentially find that, too, making your test suite more robust. + +Looking at some large open-source PHP projects, they run static analysis on their test code. + +Presumably, they're benefiting from it, so I'll try it and see if I get the same. diff --git a/source/_daily_emails/2023-12-19.md b/source/_daily_emails/2023-12-19.md new file mode 100644 index 000000000..d8544fdd6 --- /dev/null +++ b/source/_daily_emails/2023-12-19.md @@ -0,0 +1,23 @@ +--- +title: > + PHP TUIs, CLIs and open-source with Dan Leech +pubDate: 2023-12-19 +permalink: >- + archive/2023/12/19/php-tui-dan-leech +tags: + - php + - phpc + - open-source + - neovim +--- + +This week on the [Beyond Blocks podcast][podcast], I'm joined by Dan Leech - a PHP Developer and open-source project creator. + +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. + +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. + +[Listen to the episode now][episode], and I'll be back with more in the New Year. + +[episode]: https://www.oliverdavies.uk/podcast/6-dan-leech-php-tui +[podcast]: https://www.oliverdavies.uk/podcast diff --git a/source/_daily_emails/2023-12-20.md b/source/_daily_emails/2023-12-20.md new file mode 100644 index 000000000..49898a85d --- /dev/null +++ b/source/_daily_emails/2023-12-20.md @@ -0,0 +1,34 @@ +--- +title: > + hover + focus = hocus +pubDate: 2023-12-20 +permalink: >- + archive/2023/12/20/hover-focus-hocus +tags: + - software-development + - accessibility + - css + - tailwind-css +--- + +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. + +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 `:hover` and `:focus` variants. + +One of Tailwind's best features is its extensibility, which means I can create a new interaction state - `:hocus` - that works for both. + +It's very easy to do by adding this code to your `tailwind.config.js` or `tailwind.config.ts` file: + +```javascript +const plugin = require("tailwindcss/plugin"); + +module.exports = plugin(({ addVariant }) => { +  addVariant("hocus", ["&:hover", "&:focus"]); +}); +``` + +Or, use [the Tailwind CSS plugin I wrote][plugin]. + +Get more accessible websites and less duplication today! + +[plugin]: https://www.npmjs.com/package/tailwindcss-plugin-hocus-state diff --git a/source/_daily_emails/2023-12-21.md b/source/_daily_emails/2023-12-21.md new file mode 100644 index 000000000..acdcc5964 --- /dev/null +++ b/source/_daily_emails/2023-12-21.md @@ -0,0 +1,14 @@ +--- +title: > + New year coaching +pubDate: 2023-12-21 +permalink: >- + archive/2023/12/21/new-year-coaching +tags: + - software-development + - coaching +--- + +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. + +Would you like to work with me? diff --git a/source/_daily_emails/2023-12-22.md b/source/_daily_emails/2023-12-22.md new file mode 100644 index 000000000..fab44718d --- /dev/null +++ b/source/_daily_emails/2023-12-22.md @@ -0,0 +1,23 @@ +--- +title: > + Which is the best programming language, CMS or framework? +pubDate: 2023-12-22 +permalink: >- + archive/2023/12/22/best-language-cms-or-framework +tags: + - software-development + - php + - drupal +--- + +I started developing websites in HTML and CSS in 2007 before adopting PHP and Drupal in 2008. + +Since then, I've used Drupal 6, 7, 8, 9 and 10 to deliver applications for clients, agencies and in-house teams. + +I also use Symfony and Laravel, as well as JavaScript, TypeScript and Vue.js. + +## Here's the thing + +There isn't one outright "best" programming language, CMS or framework. + +It depends on the project and its requirements as well as the knowledge and experience of the team working on it. diff --git a/source/_daily_emails/2023-12-23.md b/source/_daily_emails/2023-12-23.md new file mode 100644 index 000000000..aad30a5d3 --- /dev/null +++ b/source/_daily_emails/2023-12-23.md @@ -0,0 +1,28 @@ +--- +title: > + Using a whole framework or part of it +pubDate: 2023-12-23 +permalink: >- + archive/2023/12/23/using-a-whole-framework-or-part-of-it +tags: + - software-development + - php + - composer + - drupal + - symfony + - laravel +--- + +[In yesterday's email][yesterday], I mentioned using several programming languages and frameworks. + +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. + +Using Composer, you can add parts of other frameworks to other projects. + +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. + +Start small, keep things simple, and add what you need. + +You don't need to go all in on one option, you can pick the pieces you like and that work for you. + +[yesterday]: https://www.oliverdavies.uk/archive/2023/12/22/best-language-cms-or-framework diff --git a/source/_daily_emails/2023-12-24.md b/source/_daily_emails/2023-12-24.md new file mode 100644 index 000000000..b6d378cce --- /dev/null +++ b/source/_daily_emails/2023-12-24.md @@ -0,0 +1,20 @@ +--- +title: > + This should never happen +pubDate: 2023-12-24 +permalink: >- + archive/2023/12/24/this-should-never-happen +tags: + - software-development + - clean-code +--- + +How often do you see comments like "This should never happen" in a software codebase? + +If that's true, why is it there? + +If it truly should never happen, the additional code only adds more noise and distracts from the code that is run. + +You can add a test that checks a method isn't called, but what value does this offer? + +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. diff --git a/source/_daily_emails/2023-12-25.md b/source/_daily_emails/2023-12-25.md new file mode 100644 index 000000000..29e543472 --- /dev/null +++ b/source/_daily_emails/2023-12-25.md @@ -0,0 +1,206 @@ +--- +title: > + A sneak peek of my Drupal automated testing course +pubDate: 2023-12-25 +permalink: >- + archive/2023/12/25/zero-to-test +tags: + - software-development + - drupal + - php + - phpunit + - automated-testing + - test-driven-development +--- + +Happy Christmas! + +Here's my present - a sneak peek at the first lesson in my free upcoming Automated Testing for Drupal email course. + +In this lesson, we start from scratch and end with a working test suite. + +If you like it, [register for free and get the full course][atdc] when it launches. + +## Creating a Drupal project + +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 . + +You'll need [PHP](https://www.php.net/manual/en/install.php) and [Composer](https://getcomposer.org/doc/00-intro.md). + +First, run `composer create-project drupal/recommended-project drupal` followed by `cd drupal && composer require --dev drupal/core-dev` to add the development dependencies, including PHPUnit. + +At this point, you should have a `web` directory and a `phpunit` file within `vendor/bin`. + +Finally, run `php -S 0.0.0.0:8000 -t web` to start a local web server. + +You don't need to install Drupal - as long as you see the installation page, that's fine. + +## Creating a custom module + +Before adding tests, you must create a module to place them in. + +Run `mkdir -p web/modules/custom/atdc` to create an empty module directory, and create an `atdc.info.yml` file within it with this content: + +```yaml +name: Example +type: module +core_version_requirement: ^10 +package: Custom +``` + +This is the minimum content needed for a module to be installable. + +### Writing your first test class + +Test classes are placed within each module's `tests/src` directory. + +Run `mkdir -p web/modules/custom/atdc/tests/src/Functional && touch web/modules/custom/atdc/tests/src/Functional/ExampleTest.php` to create the directory structure and a blank test class. + +Then, add this content. + +```php + PHPUnit\TextUI\RuntimeException: Class "Drupal\Tests\BrowserTestBase" not found. + +This isn't an assertion failure, but that PHPUnit can't find the files it needs to run. + +To fix this, let's configure PHPUnit. + +## Configuring PHPUnit + +Create a new `phpunit.xml.dist` file at the root of your project, with this content: + +```xml + + + + + + + + + + + ./web/modules/** + + + +``` + +This is based on `web/core/phpunit.xml.dist` with some project-specific changes. + +Namely, setting the `bootstrap` value to include the `web/core` path and fix the error, and populating the `SIMPLETEST_BASE_URL` and `SIMPLETEST_DB` environment variables. + +PHPUnit now knows where the files are, to connect to Drupal at (matching the PHP web server address) and an SQLite database. + +I've also added a `testsuite` that declares where any test classes will be located so the path doesn't need to be specified on the command line. + +## Re-running the tests + +Running the tests again will give the expected error about a failing assertion: + +> Failed asserting that false is true. + +Fix the assertion in the test by changing `FALSE` to `TRUE`, run `vendor/bin/phpunit` again, and you should see a passing test. + +> OK (1 test, 2 assertions) + +## Improving the tests + +Now you have as passing test and know PHPUnit is working, let's improve it. + +Instead of the basic check, let's check whether certain pages exist and are accessible. + +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. + +As you're writing functional tests by extending `BrowserTestBase`, you can make HTTP requests to the web server, and make assertions on the responses. + +Replace the `testBasic` test method with the following: + +```php +public function testFrontPage(): void { + $this->drupalGet('/'); + + $assert = $this->assertSession(); + $assert->statusCodeEquals(Response::HTTP_FORBIDDEN); +} + +public function testAdminPage(): void { + $this->drupalGet('/admin'); + + $assert = $this->assertSession(); + $assert->statusCodeEquals(Response::HTTP_OK); +} +``` + +These tests will make HTTP requests to the specified paths and assert the status code on the response matches the expected values. + +I'm using the constants on the `Response` class, but you can also use the status code numbers - e.g. `200` and `403`. + +## Running the updated tests + +Running `vendor/bin/phpunit`, you'll get two errors: + +> 1) Drupal\Tests\atdc\Functional\ExampleTest::testFrontPage +> Behat\Mink\Exception\ExpectationException: Current response status code is 200, but 403 expected. +> +> 2) Drupal\Tests\atdc\Functional\ExampleTest::testAdminPage +> Behat\Mink\Exception\ExpectationException: Current response status code is 403, but 200 expected. +> +> ERRORS!
    +> Tests: 2, Assertions: 4, Errors: 2. + +The responses are not returning the expected status codes, so the tests are failing. + +Reviewing them, the front page should return a 200 response code (`HTTP_OK`) as it's accessible to all users, including anonymous users. + +As we're logged out, the administration page should return a 403 (`HTTP_FORBIDDEN`). + +Swapping the assertions should get the tests to pass. + +Now, running `vendor/bin/phpunit` returns no errors or failures. + +> OK (2 tests, 4 assertions) + +Congratulations! + +## Conclusion + +In this lesson, you've created a new Drupal 10 project, configured PHPUnit and created a custom module with your first passing browser tests. + +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. + +I hope you enjoyed this sneak peek, and if you'd like to receive the course once it's complete, [register here for free][atdc]. + +[atdc]: https://www.oliverdavies.uk/atdc diff --git a/source/_daily_emails/2023-12-26.md b/source/_daily_emails/2023-12-26.md new file mode 100644 index 000000000..4729ca762 --- /dev/null +++ b/source/_daily_emails/2023-12-26.md @@ -0,0 +1,18 @@ +--- +title: > + Good code is not about being easy to write +snippet: >- + Good code is not about being easy to write. It's about how easy it is to change. +pubDate: 2023-12-26 +permalink: >- + archive/2023/12/26/good-code-is-not-about-being-easy-to-write +tags: + - software-development + - clean-code +--- + +Good code is not about being easy to write. It's about how easy it is to change. + +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? + +How easily could you refactor the code or remove it altogether if it's no longer needed? diff --git a/source/_daily_emails/2023-12-27.md b/source/_daily_emails/2023-12-27.md new file mode 100644 index 000000000..9ceb25c01 --- /dev/null +++ b/source/_daily_emails/2023-12-27.md @@ -0,0 +1,38 @@ +--- +title: >- + Writing new code is quick, to begin with +pubDate: 2023-12-27 +permalink: >- + archive/2023/12/27/writing-new-code-is-quick-to-begin-with +snippet: >- + Why is it quick to write new code in a new application, but slower as the project progresses, + with tasks that would take hours to begin with later taking days, weeks or longer. +tags: + - software-development + - technical-debt + - clean-code +--- + +When you first start a new application, adding new features is quick and easy. + +There's no existing code, and everything is written from scratch. + +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. + +Even if a sole Developer is working on the project, inconsistencies start to be introduced. + +One feature was implemented in one way and the next in a different way. + +One follows a particular design pattern, and the other does not. + +There is code within the application that isn't used and is no longer needed but hasn't been removed - creating confusion and uncertainty. + +It can't be removed, just in case it does something and removing it breaks something elsewhere. + +A task that would have taken hours to complete when the application started now takes days, weeks or longer. + +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.S. Is your New Year's resolution to deliver better software faster? [I have availability for team coaching][team coaching] starting in January 2024 and can help you avoid issues like this in your applications. + +[team coaching]: https://www.oliverdavies.uk/team-coaching diff --git a/source/_daily_emails/2023-12-28.md b/source/_daily_emails/2023-12-28.md new file mode 100644 index 000000000..4a5f583c9 --- /dev/null +++ b/source/_daily_emails/2023-12-28.md @@ -0,0 +1,31 @@ +--- +title: >- + Don't let pride get in the way of productivity +pubDate: 2023-12-28 +permalink: >- + archive/2023/12/28/pride-and-productivity +snippet: >- + Have you over been too proud to ask a question, even if it affects your productivity? +tags: + - software-development +--- + +Today, I was reading a support request on a public forum. + +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. + +A community member responded and suggested a solution. + +To this, the original poster responded: + +> Not too proud to ask where I [make the change]. + +The response to this was what caught my attention: + +> No problem. Don't let pride get in the way of productivity. + +## Here's the thing + +Don't be afraid to ask questions or say you don't know or understand something. + +No one knows everything, and there's no such thing as a stupid question. diff --git a/source/_daily_emails/2023-12-29.md b/source/_daily_emails/2023-12-29.md new file mode 100644 index 000000000..6aaaa14e9 --- /dev/null +++ b/source/_daily_emails/2023-12-29.md @@ -0,0 +1,37 @@ +--- +title: >- + Decide, automate, document +pubDate: 2023-12-29 +permalink: >- + archive/2023/12/29/decide-automate-document +snippet: > + How do you make and document decisions on your team? Here are three steps that have worked well for me. + + Decide, automate, document. +tags: + - software-development +--- + +Decide, automate, document + +Here are three steps to making decisions, such as introducing new tools and processes: + +Decide. + +Automate. + +Document. + +First of all, a decision needs to be made about what you will introduce. + +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. + +Once you've decided and added the tool or process, automate it if you can. + +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. + +Finally, document it so that it's available for others to read and reference, including new team members. + +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! + +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. diff --git a/source/_daily_emails/2023-12-30.md b/source/_daily_emails/2023-12-30.md new file mode 100644 index 000000000..9d18962e1 --- /dev/null +++ b/source/_daily_emails/2023-12-30.md @@ -0,0 +1,27 @@ +--- +title: >- + We've always done it this way +pubDate: 2023-12-30 +permalink: >- + archive/2023/12/30/weve-always-done-it-this-way +snippet: > + Has anyone told you "We've always done it this way." or "We've never needed to write tests before."? + + In my experience, these are two of the worst phases to hear from new development teams. +tags: + - software-development + - agile + - continuous-improvement +--- + +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". + +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. + +Instead, try to think about what benefits alternative approaches could offer and how they could improve any situations you're currently experiencing. + +You don't need to do it forever. Decide on something you want to try on a trial basis and set an end date. + +Then, when the trial is finished, you can decide if it achieved what you wanted, and if you want to continue with it. + +Even if you don't continue with it, you still learned something by trying. diff --git a/source/_daily_emails/2023-12-31.md b/source/_daily_emails/2023-12-31.md new file mode 100644 index 000000000..d02a30d09 --- /dev/null +++ b/source/_daily_emails/2023-12-31.md @@ -0,0 +1,28 @@ +--- +title: Just... +date: 2023-12-31 +permalink: >- + archive/2023/12/31/just +snippet: >- + Can you just... +tags: + - software-development +--- + +If you have a request that starts with "Just", it's likely a red flag! + +Why is it being made? + +What problem is it going to solve? + +Whose problem does it solve? + +Is the problem time-sensitive? + +What value does it add? + +Is it the best solution to fix the problem? + +Is it the best solution to fix the problem right now? + +To know this, we need to know why it's needed and it "just" needs doing. diff --git a/source/_layouts/daily_email.html.twig b/source/_layouts/daily_email.html.twig new file mode 100644 index 000000000..b5b5d89da --- /dev/null +++ b/source/_layouts/daily_email.html.twig @@ -0,0 +1,18 @@ +{% extends 'page' %} + +{% block content_wrapper %} + + + {{ parent() }} + +

    - Oliver

    +{% endblock %} + +{% block content_bottom %} + {% include 'daily-email-form.html.twig' with { + intro: 'Sign up here and get more like this delivered straight to your inbox every day.', + title: 'Was this useful?', + } %} + + {% include 'about-me.html.twig' %} +{% endblock %} diff --git a/source/_pages/archive.html b/source/_pages/archive.html new file mode 100644 index 000000000..9e845de87 --- /dev/null +++ b/source/_pages/archive.html @@ -0,0 +1,39 @@ +--- +title: Daily Email Archive +generator: pagination +pagination: + max_per_page: 30 + provider: data.daily_emails +use: + - daily_emails +--- + +{% block content %} +
    +
    + +
    + + {% if page.pagination.previous_page or page.pagination.next_page %} + + {% endif %} +
    +{% endblock %} + +{% block content_bottom %} + {% include 'daily-email-form.html.twig' %} + + {% include 'about-me.html.twig' %} +{% endblock %}